# iwrite3/fittrack architecture

> Architecture diagram of the GitHub repository iwrite3/fittrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iwrite3/fittrack
- Repository: https://github.com/iwrite3/fittrack

## Overview

FitTrack accepts workout entries through its React client, routes requests through an authenticated gateway, validates users and stores activities, then asynchronously generates and serves AI coaching recommendations. User profiles supply biometrics for calorie estimates; the client polls for results and displays activity history and statistics. The map includes the documented service-discovery/configuration role and Keycloak authentication. Some service links are documented rather than visible in sampled call sites; those edges cite the README.

Main entry points: [`fitness-app-frontend/src/App.jsx`](https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/App.jsx) (FitTrack app), [`gateway/src/main/java/com/fitness/gateway/RouteConfig.java`](https://github.com/iwrite3/fittrack/blob/main/gateway/src/main/java/com/fitness/gateway/RouteConfig.java) (API gateway), [`activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`](https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java) (Activity tracking), [`userservice/src/main/java/com/fitness/userservice/controller/UserController.java`](https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/controller/UserController.java) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Fitness client"]
  node_frontend["FitTrack app<br/>[App.jsx]"]
  node_activity_ui["Activity views<br/>[ActivityDetail.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_stats["Activity statistics<br/>[stats.js]"]
end

subgraph group_identity["Identity and gateway"]
  node_keycloak["Keycloak"]
  node_gateway["API gateway<br/>[RouteConfig.java]"]
  node_gateway_user["User sync"]
  node_discovery["Service discovery"]
  node_config_server["Configuration service"]
end

subgraph group_accounts["User accounts"]
  node_user_api["User API"]
  node_user_logic["User management<br/>[UserService.java]"]
  node_user_store[("User records")]
end

subgraph group_tracking["Activity tracking"]
  node_activity_api["Activity API"]
  node_activity_logic["Activity tracking"]
  node_user_validation["User validation"]
  node_activity_store[("Activity records")]
end

subgraph group_coaching["AI coaching"]
  node_event_listener["Activity listener"]
  node_ai_logic["AI analysis"]
  node_recommendation_api["Recommendation API"]
  node_recommendation_logic["Recommendation queries"]
  node_recommendation_store[("Recommendations")]
end

node_athlete(("Athlete"))
node_postgres[("PostgreSQL")]
node_mongo_activity[("MongoDB")]
node_rabbit["RabbitMQ"]
node_openrouter["OpenRouter"]

node_athlete -->|"logs workouts"| node_frontend
node_frontend -->|"authenticates with"| node_keycloak
node_frontend -->|"renders"| node_activity_ui
node_frontend -->|"requests data"| node_api_client
node_frontend -->|"calculates summaries"| node_stats
node_frontend -->|"sends API requests"| node_gateway
node_gateway -->|"routes requests"| node_user_api
node_gateway -->|"routes requests"| node_activity_api
node_gateway -->|"routes requests"| node_recommendation_api
node_keycloak -->|"provides identity"| node_gateway_user
node_gateway_user -.->|"synchronizes users"| node_user_api
node_user_api -->|"delegates to"| node_user_logic
node_user_logic -->|"reads and writes"| node_user_store
node_user_store -->|"persists users"| node_postgres
node_activity_api -->|"delegates to"| node_activity_logic
node_activity_logic -->|"validates and loads profile"| node_user_validation
node_user_validation -->|"requests user data"| node_user_api
node_activity_logic -->|"saves and queries"| node_activity_store
node_activity_store -->|"persists activities"| node_mongo_activity
node_activity_logic -->|"publishes activity event"| node_rabbit
node_rabbit -->|"delivers event"| node_event_listener
node_event_listener -->|"processes activity"| node_ai_logic
node_ai_logic -->|"requests analysis"| node_openrouter
node_event_listener -->|"stores recommendation"| node_recommendation_store
node_recommendation_api -->|"delegates to"| node_recommendation_logic
node_recommendation_logic -->|"queries recommendations"| node_recommendation_store
node_recommendation_store -->|"persists results"| node_mongo_activity
node_frontend -->|"polls for results"| node_recommendation_api
node_discovery -.->|"supports discovery"| node_gateway
node_config_server -.->|"supplies configuration"| node_gateway

click node_frontend "https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/App.jsx"
click node_activity_ui "https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/components/ActivityDetail.jsx"
click node_api_client "https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/services/api.js"
click node_stats "https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/utils/stats.js"
click node_gateway "https://github.com/iwrite3/fittrack/blob/main/gateway/src/main/java/com/fitness/gateway/RouteConfig.java"
click node_gateway_user "https://github.com/iwrite3/fittrack/blob/main/gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java"
click node_user_api "https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/controller/UserController.java"
click node_user_logic "https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/service/UserService.java"
click node_user_store "https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/repository/UserRepository.java"
click node_activity_api "https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java"
click node_activity_logic "https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java"
click node_user_validation "https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java"
click node_activity_store "https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/ActivityRepository.java"
click node_event_listener "https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java"
click node_ai_logic "https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/ActivityAIService.java"
click node_recommendation_api "https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java"
click node_recommendation_logic "https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/RecommendationService.java"
click node_recommendation_store "https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/controller/repository/RecommendationRepository.java"
click node_discovery "https://github.com/iwrite3/fittrack/blob/main/eureka/src/main/java/com/server/eureka/EurekaApplication.java"
click node_config_server "https://github.com/iwrite3/fittrack/blob/main/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_activity_ui,node_api_client,node_stats toneBlue
class node_keycloak,node_gateway,node_gateway_user,node_discovery,node_config_server,node_postgres,node_mongo_activity toneAmber
class node_user_api,node_user_logic,node_user_store,node_openrouter toneMint
class node_activity_api,node_activity_logic,node_user_validation,node_activity_store toneRose
class node_event_listener,node_ai_logic,node_recommendation_api,node_recommendation_logic,node_recommendation_store,node_athlete,node_rabbit toneIndigo
```

## Components

### Fitness client

- [FitTrack app](https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/App.jsx): `fitness-app-frontend/src/App.jsx`
- [Activity views](https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/components/ActivityDetail.jsx): `fitness-app-frontend/src/components/ActivityDetail.jsx`
- [API client](https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/services/api.js): `fitness-app-frontend/src/services/api.js`
- [Activity statistics](https://github.com/iwrite3/fittrack/blob/main/fitness-app-frontend/src/utils/stats.js): `fitness-app-frontend/src/utils/stats.js`

### Identity and gateway

- **Keycloak**
- [API gateway](https://github.com/iwrite3/fittrack/blob/main/gateway/src/main/java/com/fitness/gateway/RouteConfig.java): `gateway/src/main/java/com/fitness/gateway/RouteConfig.java`
- [User sync](https://github.com/iwrite3/fittrack/blob/main/gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java): `gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java`
- [Service discovery](https://github.com/iwrite3/fittrack/blob/main/eureka/src/main/java/com/server/eureka/EurekaApplication.java): `eureka/src/main/java/com/server/eureka/EurekaApplication.java`
- [Configuration service](https://github.com/iwrite3/fittrack/blob/main/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java): `configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java`

### User accounts

- [User API](https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/controller/UserController.java): `userservice/src/main/java/com/fitness/userservice/controller/UserController.java`
- [User management](https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/service/UserService.java): `userservice/src/main/java/com/fitness/userservice/service/UserService.java`
- [User records](https://github.com/iwrite3/fittrack/blob/main/userservice/src/main/java/com/fitness/userservice/repository/UserRepository.java): `userservice/src/main/java/com/fitness/userservice/repository/UserRepository.java`

### Activity tracking

- [Activity API](https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java): `activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java`
- [Activity tracking](https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java): `activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`
- [User validation](https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java): `activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java`
- [Activity records](https://github.com/iwrite3/fittrack/blob/main/activityservice/src/main/java/com/fitness/activityservice/ActivityRepository.java): `activityservice/src/main/java/com/fitness/activityservice/ActivityRepository.java`

### AI coaching

- [Activity listener](https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java): `aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java`
- [AI analysis](https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/ActivityAIService.java): `aiservice/src/main/java/com/fitness/aiservice/service/ActivityAIService.java`
- [Recommendation API](https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java): `aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java`
- [Recommendation queries](https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/RecommendationService.java): `aiservice/src/main/java/com/fitness/aiservice/service/RecommendationService.java`
- [Recommendations](https://github.com/iwrite3/fittrack/blob/main/aiservice/src/main/java/com/fitness/aiservice/controller/repository/RecommendationRepository.java): `aiservice/src/main/java/com/fitness/aiservice/controller/repository/RecommendationRepository.java`

### Other components

- **Athlete**
- **PostgreSQL**
- **MongoDB**
- **RabbitMQ**
- **OpenRouter**

## Connections

- Athlete → FitTrack app: logs workouts (evidence: `README.md`)
- FitTrack app → Keycloak: authenticates with (evidence: `README.md`)
- FitTrack app → Activity views: renders (evidence: `fitness-app-frontend/src/App.jsx`)
- FitTrack app → API client: requests data (evidence: `fitness-app-frontend/src/App.jsx`)
- FitTrack app → Activity statistics: calculates summaries (evidence: `fitness-app-frontend/src/App.jsx`)
- FitTrack app → API gateway: sends API requests (evidence: `README.md`)
- API gateway → User API: routes requests (evidence: `README.md`)
- API gateway → Activity API: routes requests (evidence: `README.md`)
- API gateway → Recommendation API: routes requests (evidence: `README.md`)
- Keycloak → User sync: provides identity (evidence: `README.md`)
- User sync → User API: synchronizes users
- User API → User management: delegates to (evidence: `userservice/src/main/java/com/fitness/userservice/controller/UserController.java`)
- User management → User records: reads and writes (evidence: `userservice/src/main/java/com/fitness/userservice/service/UserService.java`)
- User records → PostgreSQL: persists users (evidence: `README.md`)
- Activity API → Activity tracking: delegates to (evidence: `activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java`)
- Activity tracking → User validation: validates and loads profile (evidence: `activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`)
- User validation → User API: requests user data (evidence: `activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java`)
- Activity tracking → Activity records: saves and queries (evidence: `activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`)
- Activity records → MongoDB: persists activities (evidence: `README.md`)
- Activity tracking → RabbitMQ: publishes activity event (evidence: `activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`)
- RabbitMQ → Activity listener: delivers event (evidence: `README.md`)
- Activity listener → AI analysis: processes activity (evidence: `aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java`)
- AI analysis → OpenRouter: requests analysis
- Activity listener → Recommendations: stores recommendation (evidence: `aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java`)
- Recommendation API → Recommendation queries: delegates to (evidence: `aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java`)
- Recommendation queries → Recommendations: queries recommendations (evidence: `aiservice/src/main/java/com/fitness/aiservice/service/RecommendationService.java`)
- Recommendations → MongoDB: persists results (evidence: `README.md`)
- FitTrack app → Recommendation API: polls for results (evidence: `fitness-app-frontend/src/App.jsx`)
- Service discovery → API gateway: supports discovery
- Configuration service → API gateway: supplies configuration
