# lokeshsiddi/smart-fit-ai architecture

> Architecture diagram of the GitHub repository lokeshsiddi/smart-fit-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lokeshsiddi/smart-fit-ai
- Repository: https://github.com/lokeshsiddi/smart-fit-ai

## Overview

#### Purpose and Entry Points
Smart Fit AI is a distributed fitness platform: users register, submit activities, and receive AI-generated recommendations. Backend services are independent Spring Boot applications, each launched from its `*Application.java`; a Vite/React client is also present. Public traffic enters through the gateway, while service-to-service discovery and centralized configuration support the deployment.
- `Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/GatewayApplication.java`
- `Fitness-Microservices/fitness-app-frontend/src/main.jsx`
- `Fitness-Microservices/docker-compose.yml`

#### Edge Gateway and Identity Boundary
The API gateway is the client-facing routing and security boundary. Its security configuration and Keycloak synchronization filter indicate authentication/user identity handling occurs before downstream service access. Gateway-side user classes use a WebClient to coordinate user operations.
- `Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/config/SecurityConfig.java`
- `Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/filter/KeycloakUserSyncFilter.java`
- `Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/user/UserService.java`

#### User Domain
User Service owns registration, profile retrieval/validation, roles, and relational persistence. Activity Service validates a referenced user through its dedicated validation client/service rather than owning user data.
- `Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/controller/UserController.java`
- `Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/service/UserService.java`
- `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java`

#### Activity Ingestion and Event Production
Activity Service accepts activity requests, maps them to activity documents, persists them to MongoDB, and publishes activity events to RabbitMQ. This is the synchronous-to-asynchronous boundary: successful activity submission need not wait for AI generation.
- `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java`
- `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`
- `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/config/RabbitMqConfig.java`

#### AI Recommendation Pipeline
AI Service consumes activity messages, transforms activity context into a Gemini request, persists generated recommendation documents, and exposes recommendation retrieval. It owns recommendation storage separately from activity history, preserving database-per-service isolation.
- `Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java`
- `Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java`
- `Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java`

#### Platform Control Plane
Config Server centrally serves service-specific configuration; Eureka provides registration/discovery for gateway and service routing. Each backend service has its own Spring configuration and Docker image definition.
- `Fitness-Microservices/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java`
- `Fitness-Microservices/configserver/src/main/resources/config/api-gateway.yml`
- `Fitness-Microservices/eureka/src/main/java/com/server/eureka/EurekaApplication.java`

#### Runtime and External Dependencies
The primary runtime is Java 21 with Spring Boot 3/Spring Cloud; frontend runtime is React/Vite. Infrastructure includes PostgreSQL for users, MongoDB for activity and recommendation documents, RabbitMQ for events, Eureka, Config Server, and Google Gemini API. Keycloak is materially implied by the gateway filter. Deployment artifacts are Dockerfiles per service and a compose definition.
- `Fitness-Microservices/userservice/src/main/resources/application.yml`
- `Fitness-Microservices/aiservice/src/main/resources/application.yml`
- `Fitness-Microservices/activityservice/Dockerfile`

Main entry points: [`Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/GatewayApplication.java`](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/GatewayApplication.java) (API Gateway), [`Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java) (Activity Service), [`Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/service/UserService.java`](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/service/UserService.java) (User Service), [`Fitness-Microservices/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java`](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java) (Config Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["React/Vite Client<br/>frontend<br/>[main.jsx]"]
end

subgraph group_edge["Edge &amp; Identity"]
  node_gateway{{"API Gateway<br/>Spring Boot gateway"}}
  node_gateway_security["Security &amp; User Sync<br/>gateway filter"]
  node_keycloak["Keycloak<br/>identity provider"]
end

subgraph group_domains["Domain Services"]
  node_user_service["User Service<br/>Spring Boot service<br/>[UserService.java]"]
  node_user_api["User API<br/>REST controller"]
  node_user_db[("User PostgreSQL<br/>relational database")]
  node_activity_api["Activity API<br/>REST controller"]
  node_activity_service["Activity Service<br/>Spring Boot service"]
  node_user_validation["User Validation<br/>service client"]
  node_activity_db[("Activity MongoDB<br/>document database")]
  node_rabbitmq["RabbitMQ<br/>event broker"]
  node_ai_consumer["Activity Event Consumer<br/>message listener"]
  node_gemini_service["Gemini Generator<br/>AI integration<br/>[GeminiService.java]"]
  node_gemini["Google Gemini API<br/>external AI API"]
  node_recommendation_api["Recommendation API<br/>REST controller"]
  node_recommendation_db[("Recommendation MongoDB<br/>document database")]
end

subgraph group_platform["Platform Services"]
  node_config_server["Config Server<br/>Spring Cloud config"]
  node_eureka(("Eureka<br/>service discovery"))
  node_compose["Docker Compose<br/>deployment definition<br/>[docker-compose.yml]"]
end

node_frontend -->|"public API"| node_gateway
node_gateway -->|"secures requests"| node_gateway_security
node_gateway_security -->|"identity sync"| node_keycloak
node_gateway -->|"routes user requests"| node_user_api
node_gateway -->|"routes activity requests"| node_activity_api
node_gateway -->|"routes recommendation requests"| node_recommendation_api
node_user_api -->|"handles"| node_user_service
node_user_service -->|"owns"| node_user_db
node_activity_api -->|"handles"| node_activity_service
node_activity_service -->|"validates user"| node_user_validation
node_user_validation -->|"user lookup"| node_user_service
node_activity_service -->|"owns"| node_activity_db
node_activity_service -->|"publishes activity event"| node_rabbitmq
node_rabbitmq -->|"delivers event"| node_ai_consumer
node_ai_consumer -->|"activity context"| node_gemini_service
node_gemini_service -->|"generates recommendation"| node_gemini
node_gemini_service -->|"persists recommendation"| node_recommendation_db
node_recommendation_api -->|"retrieves"| node_recommendation_db
node_gateway -.->|"registers/discovers"| node_eureka
node_user_service -.->|"registers"| node_eureka
node_activity_service -.->|"registers"| node_eureka
node_ai_consumer -.->|"registers"| node_eureka
node_gateway -.->|"loads config"| node_config_server
node_user_service -.->|"loads config"| node_config_server
node_activity_service -.->|"loads config"| node_config_server
node_ai_consumer -.->|"loads config"| node_config_server
node_compose -.->|"deploys"| node_gateway
node_compose -.->|"deploys"| node_config_server
node_compose -.->|"deploys"| node_eureka

click node_frontend "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/fitness-app-frontend/src/main.jsx"
click node_gateway "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/GatewayApplication.java"
click node_gateway_security "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/filter/KeycloakUserSyncFilter.java"
click node_user_service "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/service/UserService.java"
click node_user_api "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/controller/UserController.java"
click node_activity_api "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java"
click node_activity_service "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java"
click node_user_validation "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java"
click node_rabbitmq "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/config/RabbitMqConfig.java"
click node_ai_consumer "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java"
click node_gemini_service "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java"
click node_recommendation_api "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java"
click node_config_server "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java"
click node_eureka "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/eureka/src/main/java/com/server/eureka/EurekaApplication.java"
click node_compose "https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/docker-compose.yml"

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 toneBlue
class node_gateway,node_gateway_security,node_keycloak toneAmber
class node_user_service,node_user_api,node_user_db,node_activity_api,node_activity_service,node_user_validation,node_activity_db,node_rabbitmq,node_ai_consumer,node_gemini_service,node_gemini,node_recommendation_api,node_recommendation_db toneMint
class node_config_server,node_eureka,node_compose toneRose
```

## Components

### Client

- [React/Vite Client](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/fitness-app-frontend/src/main.jsx): frontend · `Fitness-Microservices/fitness-app-frontend/src/main.jsx`

### Edge & Identity

- [API Gateway](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/GatewayApplication.java): Spring Boot gateway · Public routing and security boundary. · `Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/GatewayApplication.java`
- [Security & User Sync](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/filter/KeycloakUserSyncFilter.java): gateway filter · Authenticates requests and synchronizes Keycloak identities. · `Fitness-Microservices/gateway/src/main/java/com/fitness/gateway/filter/KeycloakUserSyncFilter.java`
- **Keycloak**: identity provider

### Domain Services

- [User Service](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/service/UserService.java): Spring Boot service · Owns registration, profiles, validation, and roles. · `Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/service/UserService.java`
- [User API](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/controller/UserController.java): REST controller · `Fitness-Microservices/userservice/src/main/java/com/fitness/userservice/controller/UserController.java`
- **User PostgreSQL**: relational database
- [Activity API](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java): REST controller · `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java`
- [Activity Service](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java): Spring Boot service · Persists activities and emits activity events. · `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/ActivityService.java`
- [User Validation](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java): service client · Validates referenced users with User Service. · `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java`
- **Activity MongoDB**: document database
- [RabbitMQ](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/config/RabbitMqConfig.java): event broker · Asynchronous activity-event boundary. · `Fitness-Microservices/activityservice/src/main/java/com/fitness/activityservice/config/RabbitMqConfig.java`
- [Activity Event Consumer](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java): message listener · `Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java`
- [Gemini Generator](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java): AI integration · Builds Gemini requests from activity context. · `Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java`
- **Google Gemini API**: external AI API
- [Recommendation API](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java): REST controller · `Fitness-Microservices/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java`
- **Recommendation MongoDB**: document database

### Platform Services

- [Config Server](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java): Spring Cloud config · Serves service-specific centralized configuration. · `Fitness-Microservices/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java`
- [Eureka](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/eureka/src/main/java/com/server/eureka/EurekaApplication.java): service discovery · `Fitness-Microservices/eureka/src/main/java/com/server/eureka/EurekaApplication.java`
- [Docker Compose](https://github.com/lokeshsiddi/smart-fit-ai/blob/main/Fitness-Microservices/docker-compose.yml): deployment definition · Coordinates local distributed runtime. · `Fitness-Microservices/docker-compose.yml`

## Connections

- React/Vite Client → API Gateway: public API
- API Gateway → Security & User Sync: secures requests
- Security & User Sync → Keycloak: identity sync
- API Gateway → User API: routes user requests
- API Gateway → Activity API: routes activity requests
- API Gateway → Recommendation API: routes recommendation requests
- User API → User Service: handles
- User Service → User PostgreSQL: owns
- Activity API → Activity Service: handles
- Activity Service → User Validation: validates user
- User Validation → User Service: user lookup
- Activity Service → Activity MongoDB: owns
- Activity Service → RabbitMQ: publishes activity event
- RabbitMQ → Activity Event Consumer: delivers event
- Activity Event Consumer → Gemini Generator: activity context
- Gemini Generator → Google Gemini API: generates recommendation
- Gemini Generator → Recommendation MongoDB: persists recommendation
- Recommendation API → Recommendation MongoDB: retrieves
- API Gateway → Eureka: registers/discovers
- User Service → Eureka: registers
- Activity Service → Eureka: registers
- Activity Event Consumer → Eureka: registers
- API Gateway → Config Server: loads config
- User Service → Config Server: loads config
- Activity Service → Config Server: loads config
- Activity Event Consumer → Config Server: loads config
- Docker Compose → API Gateway: deploys
- Docker Compose → Config Server: deploys
- Docker Compose → Eureka: deploys