Tim Zöller d3dbf8e80a Tests

2025-12-05 20:38:53 +01:00

44 KiB

Raw Blame History

FitPub - Federated Fitness Tracking Platform

Project Overview

FitPub is a decentralized fitness tracking application that integrates with the Fediverse through the ActivityPub protocol. It allows users to upload FIT (Flexible and Interoperable Data Transfer) files from their fitness devices and share their activities with followers across the federated social web. The application renders GPS tracks on interactive maps and federates workout data as ActivityPub activities.

Core Concept

The platform bridges the gap between fitness tracking and social networking by leveraging the open ActivityPub standard. Users can:

Upload FIT files from GPS-enabled fitness devices (Garmin, Wahoo, etc.)
View their tracks rendered on interactive maps
Share activities with followers on Mastodon, Pleroma, and other Fediverse platforms
Follow other athletes and see their public workouts
Maintain full data ownership and privacy control

Technical Architecture

Technology Stack

Backend:

Java 17+ (LTS version)
Maven for dependency management and build automation
Spring Boot 4 for application framework
Spring Web MVC for REST API
Spring Data JPA for database operations
Spring Security for authentication and authorization
PostgreSQL for primary data storage
PostGIS extension for geospatial data

Frontend:

Thymeleaf or React for UI rendering
Leaflet.js for interactive map display
Chart.js for activity statistics visualization
Bootstrap or Tailwind CSS for responsive design

Protocols & Standards:

ActivityPub (W3C Recommendation)
WebFinger (RFC 7033) for actor discovery
HTTP Signatures for authenticated federation
JSON-LD for linked data representation
GeoJSON for geographic data interchange

System Components

1. FIT File Processing Module

Responsibilities:

Parse binary FIT files uploaded by users
Extract GPS coordinates (latitude, longitude, elevation)
Parse activity metrics (heart rate, cadence, power, speed, distance)
Validate file integrity and format
Store parsed data in normalized database schema

Key Classes:

FitFileParser: Core parsing logic using FIT SDK
TrackPointEntity: Database entity for GPS coordinates
ActivityMetricsEntity: Database entity for performance data
FitFileValidator: Validation and sanitization

2. ActivityPub Federation Module

Responsibilities:

Implement ActivityPub server-to-server (S2S) protocol
Implement ActivityPub client-to-server (C2S) protocol
Handle incoming activities from other servers
Distribute local activities to followers' servers
Manage actor profiles and collections

Key Components:

Actor Model:

Actor (User Profile)
├── inbox: OrderedCollection
├── outbox: OrderedCollection
├── followers: Collection
├── following: Collection
└── publicKey: For HTTP signature verification

Activity Types:

Create: New workout activity posted
Update: Activity edited (title, description, privacy)
Delete: Activity removed
Follow: User follows another athlete
Accept: Follow request accepted
Announce: Sharing/boosting another user's activity
Like: Appreciating someone's workout

Endpoints:

/.well-known/webfinger: User discovery
/users/{username}: Actor profile (ActivityPub object)
/users/{username}/inbox: Receive activities (POST)
/users/{username}/outbox: User's activities (GET)
/users/{username}/followers: Followers collection
/users/{username}/following: Following collection
/activities/{id}: Individual activity objects

3. Geospatial Data Module

Responsibilities:

Store GPS track data efficiently
Generate map-ready GeoJSON from track points
Calculate route statistics (distance, elevation gain/loss)
Support spatial queries (nearby activities, route matching)
Render track simplification for performance

Data Structure:

Activity
├── id: UUID
├── user: Actor reference
├── activityType: (Run, Ride, Hike, Swim, etc.)
├── startTime: Timestamp
├── endTime: Timestamp
├── title: String
├── description: Text
├── visibility: (Public, Followers, Private)
├── track: LineString (PostGIS geometry)
├── metrics: JSON (distance, duration, avg_speed, etc.)
└── statistics: JSON (elevation profile, splits, etc.)

GeoJSON Output Format:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[lon, lat, elevation], ...]
    },
    "properties": {
      "time": "ISO-8601 timestamp",
      "heartRate": 145,
      "cadence": 85,
      "speed": 4.5
    }
  }]
}

4. Web API Module

REST Endpoints:

Activity Management:

POST /api/activities/upload: Upload FIT file
GET /api/activities/{id}: Retrieve activity details
GET /api/activities/{id}/track: Get GeoJSON track data
PUT /api/activities/{id}: Update activity metadata
DELETE /api/activities/{id}: Remove activity
GET /api/activities: List user's activities (paginated)

User Management:

POST /api/users/register: Create new account
GET /api/users/{username}: Public profile
GET /api/users/{username}/activities: User's public activities
PUT /api/users/profile: Update profile information

Social Features:

POST /api/follow/{username}: Follow a user
DELETE /api/follow/{username}: Unfollow
GET /api/timeline: Federated timeline of followed users
POST /api/activities/{id}/like: Like an activity
POST /api/activities/{id}/comment: Comment on activity

5. Authentication & Authorization

Implementation:

JWT tokens for session management
OAuth 2.0 for third-party integrations (optional)
HTTP Signatures (required for ActivityPub federation)
RSA key pairs per user for signature verification

Security Considerations:

Password hashing with bcrypt
Rate limiting on API endpoints
CORS configuration for frontend
Content-Security-Policy headers
Input validation and sanitization
Protection against SSRF in federation

Database Schema

Core Tables

users

id (UUID, PK)
username (VARCHAR, UNIQUE)
email (VARCHAR, UNIQUE)
password_hash (VARCHAR)
display_name (VARCHAR)
bio (TEXT)
avatar_url (VARCHAR)
public_key (TEXT)
private_key (TEXT, encrypted)
created_at (TIMESTAMP)
updated_at (TIMESTAMP)

activities

id (UUID, PK)
user_id (UUID, FK → users)
activity_type (VARCHAR)
title (VARCHAR)
description (TEXT)
started_at (TIMESTAMP)
ended_at (TIMESTAMP)
visibility (VARCHAR)
track (GEOMETRY LineString, PostGIS)
total_distance (DECIMAL)
total_duration (INTERVAL)
elevation_gain (DECIMAL)
elevation_loss (DECIMAL)
raw_fit_file (BYTEA, optional)
created_at (TIMESTAMP)
updated_at (TIMESTAMP)

track_points

id (BIGSERIAL, PK)
activity_id (UUID, FK → activities)
timestamp (TIMESTAMP)
position (GEOMETRY Point, PostGIS)
elevation (DECIMAL)
heart_rate (INTEGER)
cadence (INTEGER)
power (INTEGER)
speed (DECIMAL)
temperature (DECIMAL)

follows

id (UUID, PK)
follower_id (UUID, FK → users)
following_id (UUID, FK → users OR remote_actor_id)
status (VARCHAR: pending, accepted)
created_at (TIMESTAMP)

remote_actors

id (UUID, PK)
actor_uri (VARCHAR, UNIQUE)
username (VARCHAR)
domain (VARCHAR)
inbox_url (VARCHAR)
outbox_url (VARCHAR)
public_key (TEXT)
avatar_url (VARCHAR)
display_name (VARCHAR)
last_fetched (TIMESTAMP)

activity_pub_activities

id (UUID, PK)
activity_type (VARCHAR)
actor_id (UUID)
object_id (VARCHAR)
target_id (VARCHAR)
content (JSONB)
created_at (TIMESTAMP)

likes

id (UUID, PK)
activity_id (UUID, FK → activities)
user_id (UUID, FK → users OR remote_actor_id)
created_at (TIMESTAMP)

comments

id (UUID, PK)
activity_id (UUID, FK → activities)
user_id (UUID, FK → users OR remote_actor_id)
content (TEXT)
created_at (TIMESTAMP)
updated_at (TIMESTAMP)

ActivityPub Integration Details

Actor Object Example

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "type": "Person",
  "id": "https://fitpub.example/users/runner123",
  "preferredUsername": "runner123",
  "name": "Jane Runner",
  "summary": "Marathon runner | Trail enthusiast | 🏃‍♀️",
  "inbox": "https://fitpub.example/users/runner123/inbox",
  "outbox": "https://fitpub.example/users/runner123/outbox",
  "followers": "https://fitpub.example/users/runner123/followers",
  "following": "https://fitpub.example/users/runner123/following",
  "publicKey": {
    "id": "https://fitpub.example/users/runner123#main-key",
    "owner": "https://fitpub.example/users/runner123",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n..."
  },
  "icon": {
    "type": "Image",
    "mediaType": "image/jpeg",
    "url": "https://fitpub.example/avatars/runner123.jpg"
  }
}

Activity Object Example (Workout Post)

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://fitpub.example/activities/create/12345",
  "actor": "https://fitpub.example/users/runner123",
  "published": "2025-11-27T10:30:00Z",
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://fitpub.example/users/runner123/followers"],
  "object": {
    "type": "Note",
    "id": "https://fitpub.example/workouts/98765",
    "attributedTo": "https://fitpub.example/users/runner123",
    "content": "Morning 10K run through the park! Felt strong today. 💪",
    "published": "2025-11-27T10:30:00Z",
    "attachment": [
      {
        "type": "Document",
        "mediaType": "application/geo+json",
        "name": "GPS Track",
        "url": "https://fitpub.example/workouts/98765/track.geojson"
      },
      {
        "type": "Image",
        "mediaType": "image/png",
        "name": "Route Map",
        "url": "https://fitpub.example/workouts/98765/map.png"
      }
    ],
    "tag": [
      {
        "type": "Hashtag",
        "name": "#running"
      },
      {
        "type": "Hashtag",
        "name": "#10k"
      }
    ],
    "summary": "10.2 km • 48:23 • 4:44/km pace",
    "workoutData": {
      "distance": 10200,
      "duration": "PT48M23S",
      "activityType": "Run",
      "averagePace": "PT4M44S",
      "elevationGain": 127,
      "averageHeartRate": 152
    }
  }
}

WebFinger Implementation

Request:

GET /.well-known/webfinger?resource=acct:runner123@fitpub.example

Response:

{
  "subject": "acct:runner123@fitpub.example",
  "aliases": [
    "https://fitpub.example/users/runner123"
  ],
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://fitpub.example/users/runner123"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://fitpub.example/@runner123"
    }
  ]
}

FIT File Processing Pipeline

Parse Flow

Upload Validation
- Verify file size (max 50MB)
- Check MIME type
- Validate FIT file header
Parsing
- Use FIT SDK to decode binary format
- Extract messages: FileId, Record, Lap, Session, Activity
- Handle corrupted or incomplete files gracefully
Data Extraction
- Record Messages: GPS coordinates, timestamp, heart rate, cadence, speed, power
- Lap Messages: Split data, lap times, lap distances
- Session Messages: Total distance, total time, average/max values
- Activity Messages: Activity type, timestamp
Data Transformation
- Convert semicircles to decimal degrees (lat/lon)
- Calculate derived metrics (pace, grade-adjusted pace)
- Detect pauses and stopped periods
- Smooth GPS noise using Kalman filtering (optional)
Storage
- Batch insert track points (optimize for performance)
- Create PostGIS LineString geometry from points
- Calculate bounding box for spatial indexing
- Generate activity statistics
Map Rendering Preparation
- Simplify track using Douglas-Peucker algorithm for web display
- Generate elevation profile data
- Create thumbnail static map image (optional)
- Prepare GeoJSON response

Privacy & Visibility Controls

Visibility Levels

Public: Visible to everyone, federated across ActivityPub
Followers Only: Visible to approved followers, sent to follower inboxes
Private: Visible only to the user, not federated

Privacy Features

Ability to hide exact start/end locations (fuzzy start/finish)
Option to exclude specific segments from public view
Bulk privacy updates for historical activities
Export all personal data (GDPR compliance)
Delete account with activity cleanup

Map Rendering

Frontend Map Stack

Leaflet.js Configuration:

Base layer: OpenStreetMap tiles
Alternative layers: Satellite, Terrain (Thunderforest, Mapbox)
Custom track overlay as GeoJSON layer
Markers for start (green) and finish (red)
Popup markers for lap splits
Heatmap overlay for intensity (heart rate zones)

Interactive Features:

Click on track to see point-in-time metrics
Elevation profile chart synchronized with map
Segment highlighting
Playback animation of activity
Compare multiple activities on same map

Static Map Generation

For ActivityPub federated posts and thumbnails:

Use StaticMap library or external service
Generate PNG/JPEG preview of route
Include in ActivityPub attachment
Cache generated images

Federation Workflow Examples

Scenario 1: User Posts New Activity

User uploads FIT file via web UI
Backend parses file and stores data
User adds title, description, and sets visibility to "Public"
System creates ActivityPub Create activity
Activity is added to user's outbox
System retrieves list of followers
For each remote follower:
- Sign HTTP request with user's private key
- POST activity to follower's server inbox
Remote servers receive and process the activity
Activity appears in followers' timelines on their platforms

Scenario 2: Remote User Follows Local User

Remote user (on Mastodon) clicks "Follow" on local user's profile
Mastodon server sends Follow activity to local user's inbox
FitPub receives and validates the activity
FitPub creates Accept activity in response
FitPub stores the follow relationship
FitPub sends Accept to remote server's inbox
Follow relationship is now active
Future public activities will be sent to remote follower

Scenario 3: Remote User Likes Local Activity

Remote user views local activity on their platform
User clicks "Like" or equivalent action
Remote server sends Like activity to local inbox
FitPub receives and processes the like
Like count is incremented and stored
Like appears on activity page
Original poster may receive notification

Development Roadmap

Phase 1: MVP (Minimum Viable Product)

System Component 1: FIT File Processing Module ✅

FIT file upload and parsing (FitParser)
FIT file validation (FitFileValidator)
Activity entity with JSONB track points and simplified LineString
Activity metrics extraction and storage
Track simplification using Douglas-Peucker algorithm
FIT file service with comprehensive tests
Integration test with real FIT file

User Management & Security ✅

User entity with ActivityPub keys
UserRepository with custom queries
Password hashing with BCrypt
JWT token provider for session management
HTTP Signature validator for ActivityPub federation
UserDetailsService implementation
Security configuration (Spring Security)
User registration endpoint (POST /api/auth/register)
Login endpoint with JWT response (POST /api/auth/login)

Application Infrastructure ✅

Main application class (FitPubApplication.java)
Application configuration (application.yml)
Database configuration (PostgreSQL + PostGIS with Testcontainers Dev Services)
CORS configuration for frontend
Exception handling (global error handlers)
Logging configuration
Profile-specific configs (application-dev.yml, application-prod.yml)

Activity REST API ✅

POST /api/activities/upload - Upload FIT file
GET /api/activities/{id} - Get activity details
GET /api/activities - List user's activities (paginated)
PUT /api/activities/{id} - Update activity metadata
DELETE /api/activities/{id} - Delete activity
Activity DTOs for API responses
All endpoints tested and working

ActivityPub Actor Profile ✅

Actor model classes (Person, PublicKey)
GET /users/{username} - Actor profile endpoint
Actor JSON-LD serialization with @context
Public key embedding in actor profile
Profile metadata (name, bio, avatar)
Tested with application/activity+json and application/ld+json

WebFinger Support ✅

WebFinger controller
GET /.well-known/webfinger - User discovery
WebFinger response DTO
Account identifier parsing (acct:user@domain)
Tested with valid and invalid requests

ActivityPub Collections ✅

POST /users/{username}/inbox - Inbox endpoint (accepts activities with 202 Accepted)
GET /users/{username}/outbox - Outbox endpoint (returns empty OrderedCollection)
GET /users/{username}/followers - Followers collection (returns empty OrderedCollection)
GET /users/{username}/following - Following collection (returns empty OrderedCollection)
OrderedCollection model classes
Basic collection structure (TODOs exist for populating with actual data)
All endpoints tested and working

Basic Federation ✅

Federation service for outbound activities (FederationService.java)
HTTP signature signing for outbound requests (signRequest method in HttpSignatureValidator)
HTTP signature verification for inbound requests (validate method already existed)
Follow activity - Remote user follows local user (InboxProcessor)
Accept activity - Accept follow requests (FederationService.sendAcceptActivity)
Undo activity - Unfollow support (InboxProcessor)
Follow entity and repository (Follow.java, FollowRepository.java)
Remote actor entity and repository (RemoteActor.java, RemoteActorRepository.java)
Inbox processor for incoming activities (InboxProcessor.java)
Remote actor fetching and caching
Follower inbox collection for activity distribution

Public Timeline ✅

Timeline service (TimelineService.java)
Timeline DTOs for response (TimelineActivityDTO.java with ActivityMetricsSummary)
GET /api/timeline/federated - Federated timeline for authenticated user
GET /api/timeline/public - Public timeline (all public activities)
GET /api/timeline/user - User's own timeline
Timeline filtering and pagination (Spring Data Pageable)
Activity visibility enforcement (PUBLIC, FOLLOWERS)
Repository methods for timeline queries (findByUserIdInAndVisibilityInOrderByStartedAtDesc, findByVisibilityOrderByStartedAtDesc)

Database Migrations ✅

Flyway setup and configuration
V1: Enable PostGIS extension
V2: Users table with indexes (username, email, created_at)
V3: Activities table with geospatial support (GIST index on simplified_track, GIN index on track_points_json)
V4: Activity metrics table with one-to-one relationship
V5: Follows table for federation (follower_id, following_actor_uri, status)
V6: Remote actors table for ActivityPub federation cache
All indexes for performance (user lookups, activity queries, spatial queries)
Changed Hibernate ddl-auto from 'update' to 'validate'

Frontend Infrastructure ✅

Choose frontend approach (Thymeleaf + HTMX for server-side rendering with dynamic interactions)
Static asset structure (css/, js/, img/ directories)
HTMX dependency setup (via CDN in layout.html)
Leaflet.js dependency setup (via CDN in layout.html)
Chart.js dependency setup (via CDN in layout.html)
CSS framework setup (Bootstrap 5.3.2 via CDN + Bootstrap Icons)
Base Thymeleaf layout template with navigation (layout.html)
Responsive mobile design foundation (Bootstrap grid + custom CSS)
Custom CSS with FitPub theme (fitpub.css)
Custom JavaScript utilities (fitpub.js with map/chart helpers)
Thymeleaf dependencies added to pom.xml
Home page template (index.html)
Home controller for routing

Authentication UI ✅

User registration page/form (auth/register.html)
Login page/form (auth/login.html)
JWT token storage (localStorage in auth.js)
Authentication state management (FitPubAuth object in auth.js)
Protected route handling (SecurityConfig.java + client-side checks)
Logout functionality (client-side token removal + server endpoint)
Session expiration handling (JWT expiration check + warning)
Login/registration error display (alert components in forms)
Authentication view controller (AuthViewController.java)
Dynamic navigation menu (shows/hides based on auth status)
Form validation with Bootstrap
Loading states for submit buttons
Password confirmation validation
Authenticated API fetch helper (authenticatedFetch in auth.js)

Activity Upload & Management UI ✅

FIT file upload form with drag-and-drop
Upload progress indicator
Activity metadata form (title, description, visibility)
Activity list view (user's own activities)
Activity pagination controls
Activity delete confirmation dialog
Activity edit form
File upload validation and error messages

Map Rendering & Visualization ✅

Leaflet.js map initialization
OpenStreetMap tile layer integration
GeoJSON track rendering on map
Start/finish markers (green/red)
Map bounds auto-fitting to track
Track click handler for point-in-time metrics
Map loading states and error handling
Responsive map sizing

Activity Detail Page ✅

Activity metadata display (title, description, date, type)
Interactive map with GPS track
Activity metrics display (distance, duration, pace, elevation)
Elevation profile chart (Chart.js)
Activity statistics summary cards (distance, duration, pace, elevation gain)
Visibility indicator (Public/Followers/Private)
Additional metrics display (heart rate, cadence, speed, calories - shown if available)
Edit button linking to activity edit page
Delete button with confirmation modal
Back to activities button
Loading state indicator
Error handling and display
Start/finish markers on map
Map bounds auto-fitting to track
Responsive layout for mobile
User profile links from activity cards and timeline

Timeline & Social Features UI ✅

Public timeline page (timeline/public.html)
Federated timeline page (timeline/federated.html - following feed)
User timeline page (timeline/user.html - own activities)
Timeline activity cards with preview maps (Leaflet.js integration)
Activity card metrics summary (distance, duration, pace, elevation)
Pagination for timeline (with prev/next and page numbers)
Empty state messages (for each timeline type)
Loading states for timelines (spinner and loading text)
Timeline view controller (TimelineViewController.java)
Timeline JavaScript module (timeline.js with dynamic loading)
Timeline CSS styles (timeline-card, user-avatar, preview-map)
User information display (avatar, display name, username, federation indicator)
Time ago formatting (e.g., "2h ago", "3d ago")
Activity type badges (Run, Ride, Hike)
Visibility indicators (Public/Followers/Private)
Interactive preview maps with start/finish markers
Responsive design for mobile and desktop
Authentication-aware UI (shows/hides features based on login status)
Error handling and user-friendly error messages

User Profile UI ✅

Public user profile page (profile/public.html)
User profile display (avatar, bio, display name)
User's activity list on profile with pagination
Follower/following counts display (real data from backend)
Profile edit page (profile/edit.html)
Avatar URL input
Profile settings form with validation
Profile view controller (ProfileViewController.java)
User API endpoints (UserController.java)
User DTOs (UserDTO, UserUpdateRequest)
GET /api/users/me - Get current user profile
PUT /api/users/me - Update current user profile
GET /api/users/{username} - Get user by username
GET /api/activities/user/{username} - Get user's public activities
Profile CSS styles (avatar-placeholder-large, stat-card, activity-item)
Character counter for bio (500 chars max)
Avatar preview on edit page
Form validation and error handling
Success messages and redirects
Responsive mobile design
Settings page placeholder (settings.html)
Client-side authentication checks for protected pages

User Discovery UI ✅

Discover users page (users/discover.html)
User search functionality with live search bar
Browse all users with pagination
User cards grid layout with avatar, bio, and stats
Responsive design for mobile and desktop
Empty state for no results
Loading indicators
View controller route (GET /discover)
Integration with backend search and browse APIs

Navigation & Layout ✅

Top navigation bar with logo
Navigation links (Timeline, Discover, My Activities, Upload, Profile)
User menu dropdown (Profile, Settings, Logout)
Footer with app info
Mobile hamburger menu (Bootstrap responsive navbar)
Dynamic navigation (shows/hides based on auth status)

Error Handling & User Feedback ✅

API error message display (in activity upload, detail, list pages)
Success notifications (FitPub.showAlert function)
Form validation error display (registration, login, activity forms)
Loading spinners (activity detail page, upload page, timeline, profile)
Empty states for timelines and profiles
Client-side 403 handling via authentication redirects

Phase 1 (MVP) - ✅ COMPLETE!

All core features implemented and working:

✅ FIT file upload and processing
✅ GPS track visualization with Leaflet maps
✅ Activity management (CRUD operations)
✅ User authentication and profiles
✅ Public, federated, and user timelines
✅ ActivityPub federation (Follow/Accept/Undo)
✅ WebFinger user discovery
✅ Responsive mobile-friendly UI
✅ PostgreSQL + PostGIS database
✅ Complete REST API

Likes on activities (Like entity, repository, ActivityPub Like activity support)
Comments on activities (Comment entity, repository, ActivityPub Note activity support)
Activity sharing (Announce/boost functionality via ActivityPub)
Privacy protection for GPS tracks (fuzzy start/finish zones)
OSM tile rendering for activity maps (OsmTileRenderer with caching)
Activity image generation with track overlay (ActivityImageService)
FIT epoch timestamp fix (631065600 second offset for proper date handling)
Web Mercator projection for accurate track-to-map alignment
User search and discovery backend (UserRepository.searchUsers, UserRepository.findAllEnabledUsers, GET /api/users/search, GET /api/users/browse)
User search and discovery UI (users/discover.html, /discover route, search bar with live filtering, user cards grid, pagination)
Followers/following lists (ActorDTO, GET /api/users/{username}/followers, GET /api/users/{username}/following)
Follower/following counts (UserController.populateSocialCounts, UserDTO with followersCount/followingCount, frontend displays real counts)
Heart rate chart over time on activity details (Chart.js line chart, elapsed time x-axis, heart rate y-axis)
Speed/pace chart over time on activity details (Chart.js line chart with smoothin69287079d5e0a4532ba818ee.fitg, displays speed in km/h with pace in tooltip)
Notifications system (Notification entity, NotificationRepository, NotificationService, NotificationController REST API, notifications.html UI, notification bell in nav with unread count, polling every 30s, mark as read/delete, all/unread filter tabs)
Custom 404 Not Found page (error/404.html with animated compass icon, suggestions, gradient background)
Custom 403 Forbidden page (error/403.html with shield-lock icon, auth-aware login button, gradient background)
Custom 500 Internal Server Error page (error/500.html with tools icon, recovery suggestions)
Generic error page (error/error.html with dynamic error code display, technical details toggle)
Empty state illustrations (reusable CSS classes in fitpub.css, floating animation, variant colors for activities/notifications/timeline/users/search, updated all timeline pages, notifications page, and discover page)
Enhanced privacy controls UI
Follow/unfollow buttons on user profiles
Activity visibility to followers (implement FOLLOWERS visibility enforcement)
Breadcrumb navigation
Active route highlighting in navigation
Global error boundary/handler

Phase 3: Advanced Analytics ✅

Personal records tracking (PersonalRecord entity, PersonalRecordRepository, PersonalRecordService)
10 record types (FASTEST_1K, FASTEST_5K, FASTEST_10K, FASTEST_HALF_MARATHON, FASTEST_MARATHON, LONGEST_DISTANCE, LONGEST_DURATION, HIGHEST_ELEVATION_GAIN, MAX_SPEED, BEST_AVERAGE_PACE)
Automatic PR detection on activity save
Split time calculations for distance PRs
Previous value tracking and improvement calculations
Training load and recovery metrics (TrainingLoad entity, TrainingLoadRepository, TrainingLoadService)
Training Stress Score (TSS) calculation based on duration, distance, and elevation
Acute Training Load (ATL) - 7-day rolling average (fatigue)
Chronic Training Load (CTL) - 28-day rolling average (fitness)
Training Stress Balance (TSB) - CTL - ATL (freshness)
Form status calculation (FRESH, OPTIMAL, FATIGUED, UNKNOWN)
Achievement/badge system (Achievement entity, AchievementRepository, AchievementService)
25+ achievement types with badge icons and colors
First activity achievements (by type)
Distance milestones (10K, 50K, 100K, 250K, 500K, 1000K)
Activity count milestones (10, 50, 100, 250, 500, 1000 activities)
Streak achievements (7, 30, 100 days)
Time-based achievements (early bird, night owl)
Elevation achievements (mountaineer 1000m, 5000m, 10000m)
Variety achievements (trying multiple activity types)
Speed achievements (speed demon 40+ km/h)
Weekly/monthly/yearly summaries (ActivitySummary entity, ActivitySummaryRepository, ActivitySummaryService)
Period-based aggregations (weekly, monthly, yearly)
Activity type breakdown per period
Total metrics (distance, duration, elevation gain)
Average and max speed tracking
PRs and achievements counts per period
Async summary updates
Analytics REST API (AnalyticsController)
GET /api/analytics/dashboard - Dashboard stats
GET /api/analytics/personal-records - List PRs with optional activity type filter
GET /api/analytics/achievements - List earned achievements
GET /api/analytics/training-load - Training load data with date range
GET /api/analytics/form-status - Current form status
GET /api/analytics/summaries/{period} - Weekly/monthly/yearly summaries
Analytics UI pages (AnalyticsViewController)
Analytics dashboard (analytics/dashboard.html) with stats overview, current week/month, recent PRs and achievements
Personal records page (analytics/personal-records.html) with activity type filters, improvement display
Achievements page (analytics/achievements.html) with badge gallery, animations, metadata display
Training load page (analytics/training-load.html) with form status card, Chart.js charts (TSS bar chart, ATL vs CTL line chart, TSB line chart with color zones)
Summaries page (analytics/summaries.html) with weekly/monthly/yearly tabs, summary cards, type breakdown
Analytics link in navigation (authenticated users only)
Database migration V10__create_analytics_tables.sql
Integration with FitFileService (auto-update analytics on activity save)
Security configuration updated (analytics routes and API endpoints)
Weather data integration (WeatherData entity, WeatherDataRepository, WeatherService with OpenWeatherMap API)
Weather database migration V11__create_weather_data_table.sql
Weather API configuration (fitpub.weather.enabled, fitpub.weather.api-key)
Weather fetching on activity upload (automatic for activities within 5 days)
Weather API endpoint GET /api/activities/{id}/weather
Weather display on activity detail page (temperature, humidity, wind, pressure, precipitation)

Phase 4: Enhanced Federation

Rich preview cards for activities
Cross-platform activity sync

Phase 5: Mobile & Integrations

Progressive Web App (PWA)
Native mobile apps (optional)
Direct device sync (Garmin Connect API)
Webhook integrations
Import from Strava, Garmin, etc.
Avatar file upload (currently URL-based)

Phase 6: Testing & Documentation

Testing: ✅ 77 tests passing

Unit tests for TrainingLoadService (10 tests - TSS, ATL, CTL, TSB calculations)
Unit tests for PersonalRecordService (13 tests - all PR types, improvement detection)
Unit tests for AchievementService (16 tests - all badge types, edge cases)
Unit tests for FitFileService (10 tests - existing tests updated and fixed)
Integration tests for ActivityController (10 tests - full stack HTTP to database)
Integration tests for ActivityPub federation endpoints
Integration tests for WebFinger discovery
Integration tests for Timeline and Analytics REST API endpoints
Frontend E2E tests with Playwright or Cypress

Documentation:

Create comprehensive README.md with project overview and features
Write database setup guide (PostgreSQL + PostGIS installation)
Create API documentation with Swagger/OpenAPI
Write deployment instructions (Docker, Kubernetes, bare metal)
Create user documentation (how to use FitPub)
Write administrator guide (configuration, maintenance)
Document frontend development setup and architecture

Maven Project Structure

fitpub/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── fitpub/
│   │   │           ├── FitPubApplication.java
│   │   │           ├── config/
│   │   │           │   ├── SecurityConfig.java
│   │   │           │   ├── WebConfig.java
│   │   │           │   └── ActivityPubConfig.java
│   │   │           ├── controller/
│   │   │           │   ├── ActivityController.java
│   │   │           │   ├── UserController.java
│   │   │           │   ├── ActivityPubController.java
│   │   │           │   └── WebFingerController.java
│   │   │           ├── service/
│   │   │           │   ├── FitFileService.java
│   │   │           │   ├── ActivityService.java
│   │   │           │   ├── FederationService.java
│   │   │           │   ├── UserService.java
│   │   │           │   └── GeospatialService.java
│   │   │           ├── model/
│   │   │           │   ├── entity/
│   │   │           │   │   ├── User.java
│   │   │           │   │   ├── Activity.java
│   │   │           │   │   ├── TrackPoint.java
│   │   │           │   │   ├── Follow.java
│   │   │           │   │   └── RemoteActor.java
│   │   │           │   ├── dto/
│   │   │           │   │   ├── ActivityDTO.java
│   │   │           │   │   ├── UserDTO.java
│   │   │           │   │   └── TrackDTO.java
│   │   │           │   └── activitypub/
│   │   │           │       ├── Actor.java
│   │   │           │       ├── Activity.java
│   │   │           │       └── Collection.java
│   │   │           ├── repository/
│   │   │           │   ├── UserRepository.java
│   │   │           │   ├── ActivityRepository.java
│   │   │           │   ├── TrackPointRepository.java
│   │   │           │   └── FollowRepository.java
│   │   │           ├── security/
│   │   │           │   ├── JwtTokenProvider.java
│   │   │           │   ├── HttpSignatureValidator.java
│   │   │           │   └── UserDetailsServiceImpl.java
│   │   │           └── util/
│   │   │               ├── FitParser.java
│   │   │               ├── GeoJsonConverter.java
│   │   │               └── ActivityPubUtil.java
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       ├── application-prod.yml
│   │       ├── static/
│   │       │   ├── css/
│   │       │   ├── js/
│   │       │   └── img/
│   │       └── templates/
│   │           ├── index.html
│   │           ├── activity.html
│   │           └── profile.html
│   └── test/
│       └── java/
│           └── com/
│               └── fitpub/
│                   ├── service/
│                   ├── controller/
│                   └── integration/
└── README.md

Key Maven Dependencies

<dependencies>
    <!-- Spring Boot Starters -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    
    <!-- Database -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
    </dependency>
    <dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate-spatial</artifactId>
    </dependency>
    
    <!-- FIT File Processing -->
    <dependency>
        <groupId>com.garmin</groupId>
        <artifactId>fit</artifactId>
        <version>21.XX.XX</version>
    </dependency>
    
    <!-- JSON Processing -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
    
    <!-- HTTP Client -->
    <dependency>
        <groupId>org.apache.httpcomponents.client5</groupId>
        <artifactId>httpclient5</artifactId>
    </dependency>
    
    <!-- JWT -->
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
    </dependency>
    
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    
    <!-- Testing -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Configuration Examples

application.yml

spring:
  application:
    name: fitpub
  datasource:
    url: jdbc:postgresql://localhost:5432/fitpub
    username: fitpub_user
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        dialect: org.hibernate.spatial.dialect.postgis.PostgisDialect
  servlet:
    multipart:
      max-file-size: 50MB
      max-request-size: 50MB

fitpub:
  domain: fitpub.example
  base-url: https://fitpub.example
  activitypub:
    enabled: true
    max-federation-retries: 3
  security:
    jwt:
      secret: ${JWT_SECRET}
      expiration: 86400000 # 24 hours
  storage:
    fit-files:
      path: /var/fitpub/fit-files
      retention-days: 365

Deployment Considerations

Infrastructure Requirements

Application Server: JVM-based (Java 17+)
Database: PostgreSQL 13+ with PostGIS extension
Reverse Proxy: Nginx or Traefik for HTTPS termination
Storage: File storage for FIT files and generated assets
Cache: Redis (optional, for session management)

Scaling Strategy

Horizontal scaling of application servers
Database read replicas for heavy read operations
CDN for static assets and map tiles
Background job processing for FIT file parsing (Spring Batch or async)
Rate limiting and request throttling

Monitoring & Observability

Application metrics (Micrometer + Prometheus)
Database query performance monitoring
Federation success/failure rates
API response times
User activity analytics

Legal & Compliance

Licensing Considerations

Choose appropriate open-source license (AGPL, MIT, Apache 2.0)
Comply with FIT SDK licensing terms
Attribute map tile providers
Terms of Service for user-generated content
Privacy Policy (GDPR, CCPA compliance)

Data Retention

User data export functionality
Right to be forgotten (account deletion)
Activity data backup procedures
Federation data cleanup (remove data from remote deleted actors)

Community & Contribution

Open Source Goals

Public GitHub repository
Contribution guidelines
Code of conduct
Issue templates
Documentation for developers
Public roadmap and feature requests

Fediverse Integration

Publish FEP (Fediverse Enhancement Proposal) if introducing custom extensions
Collaborate with other ActivityPub developers
Test interoperability with major platforms (Mastodon, Pleroma, Pixelfed)
Participate in Fediverse developer community

Future Enhancements

AI-Powered Insights: Training recommendations, injury prevention
Virtual Racing: Compete on same routes asynchronously
Route Planning: Create routes and share with community
Live Tracking: Real-time activity sharing during workout
Wearable Integration: Direct sync with smartwatches
Audio Cues: Export audio-guided workouts
Social Challenges: Group goals and competitions
Marketplace: Routes, training plans, coaching services

Getting Started

Prerequisites

Java 17 or higher
Maven 3.8+
PostgreSQL 13+ with PostGIS
Git

Quick Start

Clone repository
Set up PostgreSQL database with PostGIS extension
Configure application.yml with database credentials
Run mvn clean install
Start application: mvn spring-boot:run
Access at http://localhost:8080

First Steps

Register a user account
Upload a FIT file from your GPS device
View your activity on the interactive map
Set up ActivityPub federation (optional)
Follow other athletes on the Fediverse

Project Status: Planning & Initial Development

License: TBD

Contributors Welcome: Yes

Contact: [Project repository or contact information]

44 KiB Raw Blame History

FitPub - Federated Fitness Tracking Platform

Project Overview

Core Concept

Technical Architecture

Technology Stack

System Components

1. FIT File Processing Module

2. ActivityPub Federation Module

3. Geospatial Data Module

4. Web API Module

5. Authentication & Authorization

Database Schema

Core Tables

ActivityPub Integration Details

Actor Object Example

Activity Object Example (Workout Post)

WebFinger Implementation

FIT File Processing Pipeline

Parse Flow

Privacy & Visibility Controls

Visibility Levels

Privacy Features

Map Rendering

Frontend Map Stack

Static Map Generation

Federation Workflow Examples

Scenario 1: User Posts New Activity

Scenario 2: Remote User Follows Local User

Scenario 3: Remote User Likes Local Activity

Development Roadmap

Phase 1: MVP (Minimum Viable Product)

Phase 1 (MVP) - ✅ COMPLETE!

Phase 2: Social Features & Enhancements ✅

Phase 3: Advanced Analytics ✅

Phase 4: Enhanced Federation

Phase 5: Mobile & Integrations

Phase 6: Testing & Documentation

Maven Project Structure

Key Maven Dependencies

Configuration Examples

application.yml

Deployment Considerations

Infrastructure Requirements

Scaling Strategy

Monitoring & Observability

Legal & Compliance

Licensing Considerations

Data Retention

Community & Contribution

Open Source Goals

Fediverse Integration

Future Enhancements

Getting Started

Prerequisites

Quick Start

First Steps

44 KiB

Raw Blame History