# siddarth2904/befit architecture

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

- Interactive diagram: https://gitdiagram.com/siddarth2904/befit
- Repository: https://github.com/siddarth2904/befit

## Overview

#### Purpose and topology
BeFit is a fitness-tracking microservice system with a React client. Users authenticate through the gateway, manage activity records, and receive AI-generated recommendations. Each backend is an independent Spring Boot/Maven application; runtime service discovery and centralized configuration support the fleet.

#### Client entry and user interaction
The Vite/React frontend is the browser entry point. It initializes the app, holds authentication state, renders activity creation/list/detail flows, and calls backend APIs.
- `fitness-frontend/src/main.jsx`
- `fitness-frontend/src/App.jsx`
- `fitness-frontend/src/services/api.js`
- `fitness-frontend/src/store/authSlice.js`

#### API gateway and identity boundary
The gateway is the external backend boundary. Spring Security protects routed requests; a Keycloak-oriented filter synchronizes authenticated user information into the system through gateway user-service integration. This separates client-facing authentication from downstream domain services.
- `apigateway/apigateway/src/main/java/com/fitness/apigateway/ApigatewayApplication.java`
- `apigateway/apigateway/src/main/java/com/fitness/apigateway/configs/SecurityConfig.java`
- `apigateway/apigateway/src/main/java/com/fitness/apigateway/filters/KeycloakUserSyncFilter.java`
- `apigateway/apigateway/src/main/java/com/fitness/apigateway/services/UserService.java`

#### User domain service
The user service owns application user records, user type, registration DTOs, and persistence access. Gateway sync/registration flows cross into this service rather than allowing other services to own user state.
- `userservice/userservice/src/main/java/com/fitness/userservice/controllers/UserController.java`
- `userservice/userservice/src/main/java/com/fitness/userservice/services/UserService.java`
- `userservice/userservice/src/main/java/com/fitness/userservice/model/User.java`
- `userservice/userservice/src/main/java/com/fitness/userservice/repositories/UserRepository.java`

#### Activity ingestion and persistence
The activity service exposes activity operations, validates referenced users through an outbound WebClient boundary, and persists activity entities to MongoDB. It also configures RabbitMQ, indicating activity creation/update is the producer-side event boundary for recommendation processing.
- `activityservice/activityservice/src/main/java/com/fitness/activityservice/controllers/ActivityController.java`
- `activityservice/activityservice/src/main/java/com/fitness/activityservice/services/ActivityService.java`
- `activityservice/activityservice/src/main/java/com/fitness/activityservice/services/UserValidationService.java`
- `activityservice/activityservice/src/main/java/com/fitness/activityservice/repositories/ActivityRepository.java`

#### Asynchronous AI recommendations
The AI service consumes activity messages from RabbitMQ, transforms activity data into recommendation-generation work, calls Gemini through a dedicated service boundary, and persists recommendations in MongoDB. Recommendations are exposed through a controller independently of activity writes, decoupling AI latency/failure from activity ingestion.
- `aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityMessageListener.java`
- `aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityAIService.java`
- `aiservice/aiservice/src/main/java/com/fitness/aiservice/services/GeminiService.java`
- `aiservice/aiservice/src/main/java/com/fitness/aiservice/repository/RecommendationRepository.java`

#### Platform services and runtime dependencies
Eureka provides service registration/discovery; Config Server centrally serves per-service configuration. Spring Boot is the backend runtime, with MongoDB for activity/recommendation data, RabbitMQ for activity events, Keycloak for identity integration, and Gemini as the external AI provider. Service-specific configuration files define the deployment wiring.
- `eureka/eureka/src/main/java/com/server/eureka/EurekaApplication.java`
- `configserver/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java`
- `configserver/configserver/src/main/resources/config/activity-service.yml`
- `configserver/configserver/src/main/resources/config/ai-service.yml`

Main entry points: [`activityservice/activityservice/src/main/java/com/fitness/activityservice/services/ActivityService.java`](https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/services/ActivityService.java) (Activity service), [`apigateway/apigateway/src/main/java/com/fitness/apigateway/ApigatewayApplication.java`](https://github.com/siddarth2904/befit/blob/main/apigateway/apigateway/src/main/java/com/fitness/apigateway/ApigatewayApplication.java) (API gateway), [`aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityAIService.java`](https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityAIService.java) (Recommendation generator), [`userservice/userservice/src/main/java/com/fitness/userservice/services/UserService.java`](https://github.com/siddarth2904/befit/blob/main/userservice/userservice/src/main/java/com/fitness/userservice/services/UserService.java) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["React client<br/>Vite/React<br/>[App.jsx]"]
  node_api_client["API client<br/>frontend service<br/>[api.js]"]
end

subgraph group_edge["API &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_repository[("User repository<br/>persistence access")]
  node_activity_api["Activity service<br/>Spring Boot service"]
  node_user_validation["User validation<br/>WebClient boundary"]
  node_activity_repository[("Activity repository<br/>Mongo persistence")]
  node_activity_mongo[("Activity MongoDB<br/>database")]
end

subgraph group_ai["Recommendation Pipeline"]
  node_rabbitmq["RabbitMQ<br/>event broker"]
  node_ai_listener["Activity listener<br/>message consumer"]
  node_ai_service["Recommendation generator<br/>AI orchestration"]
  node_gemini{{"Gemini<br/>external AI provider"}}
  node_recommendation_repository[("Recommendation repository<br/>Mongo persistence")]
  node_recommendation_mongo[("Recommendation MongoDB<br/>database")]
end

subgraph group_platform["Platform"]
  node_eureka{{"Eureka<br/>service discovery"}}
  node_config_server{{"Config Server<br/>central configuration"}}
end

node_frontend -->|"uses"| node_api_client
node_api_client -->|"API requests"| node_gateway
node_gateway -->|"secured routing"| node_gateway_security
node_gateway_security -->|"authenticates"| node_keycloak
node_gateway_security -->|"syncs users"| node_user_service
node_gateway -->|"routes activity APIs"| node_activity_api
node_gateway -->|"routes user APIs"| node_user_service
node_user_service -->|"persists users"| node_user_repository
node_activity_api -->|"validates user"| node_user_validation
node_user_validation -->|"checks user"| node_user_service
node_activity_api -->|"stores activities"| node_activity_repository
node_activity_repository -->|"MongoDB"| node_activity_mongo
node_activity_api -->|"publishes activity events"| node_rabbitmq
node_rabbitmq -->|"delivers events"| node_ai_listener
node_ai_listener -->|"activity data"| node_ai_service
node_ai_service -->|"generates recommendations"| node_gemini
node_ai_service -->|"persists recommendations"| node_recommendation_repository
node_recommendation_repository -->|"MongoDB"| node_recommendation_mongo
node_gateway -.->|"registers/discovers"| node_eureka
node_user_service -.->|"registers"| node_eureka
node_activity_api -.->|"registers"| node_eureka
node_ai_service -.->|"registers"| node_eureka
node_activity_api -.->|"loads config"| node_config_server
node_ai_service -.->|"loads config"| node_config_server

click node_frontend "https://github.com/siddarth2904/befit/blob/main/fitness-frontend/src/App.jsx"
click node_api_client "https://github.com/siddarth2904/befit/blob/main/fitness-frontend/src/services/api.js"
click node_gateway "https://github.com/siddarth2904/befit/blob/main/apigateway/apigateway/src/main/java/com/fitness/apigateway/ApigatewayApplication.java"
click node_gateway_security "https://github.com/siddarth2904/befit/blob/main/apigateway/apigateway/src/main/java/com/fitness/apigateway/filters/KeycloakUserSyncFilter.java"
click node_user_service "https://github.com/siddarth2904/befit/blob/main/userservice/userservice/src/main/java/com/fitness/userservice/services/UserService.java"
click node_user_repository "https://github.com/siddarth2904/befit/blob/main/userservice/userservice/src/main/java/com/fitness/userservice/repositories/UserRepository.java"
click node_activity_api "https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/services/ActivityService.java"
click node_user_validation "https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/services/UserValidationService.java"
click node_activity_repository "https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/repositories/ActivityRepository.java"
click node_ai_listener "https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityMessageListener.java"
click node_ai_service "https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityAIService.java"
click node_recommendation_repository "https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/repository/RecommendationRepository.java"
click node_eureka "https://github.com/siddarth2904/befit/blob/main/eureka/eureka/src/main/java/com/server/eureka/EurekaApplication.java"
click node_config_server "https://github.com/siddarth2904/befit/blob/main/configserver/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_api_client toneBlue
class node_gateway,node_gateway_security,node_keycloak toneAmber
class node_user_service,node_user_repository,node_activity_api,node_user_validation,node_activity_repository,node_activity_mongo toneMint
class node_rabbitmq,node_ai_listener,node_ai_service,node_gemini,node_recommendation_repository,node_recommendation_mongo toneRose
class node_eureka,node_config_server toneIndigo
```

## Components

### Client

- [React client](https://github.com/siddarth2904/befit/blob/main/fitness-frontend/src/App.jsx): Vite/React · Authentication state and activity UI. · `fitness-frontend/src/App.jsx`
- [API client](https://github.com/siddarth2904/befit/blob/main/fitness-frontend/src/services/api.js): frontend service · `fitness-frontend/src/services/api.js`

### API & Identity

- [API gateway](https://github.com/siddarth2904/befit/blob/main/apigateway/apigateway/src/main/java/com/fitness/apigateway/ApigatewayApplication.java): Spring Boot gateway · External backend entry point. · `apigateway/apigateway/src/main/java/com/fitness/apigateway/ApigatewayApplication.java`
- [Security & user sync](https://github.com/siddarth2904/befit/blob/main/apigateway/apigateway/src/main/java/com/fitness/apigateway/filters/KeycloakUserSyncFilter.java): gateway filter · Protects requests and synchronizes Keycloak users. · `apigateway/apigateway/src/main/java/com/fitness/apigateway/filters/KeycloakUserSyncFilter.java`
- **Keycloak**: identity provider

### Domain Services

- [User service](https://github.com/siddarth2904/befit/blob/main/userservice/userservice/src/main/java/com/fitness/userservice/services/UserService.java): Spring Boot service · Owns application user records and registration. · `userservice/userservice/src/main/java/com/fitness/userservice/services/UserService.java`
- [User repository](https://github.com/siddarth2904/befit/blob/main/userservice/userservice/src/main/java/com/fitness/userservice/repositories/UserRepository.java): persistence access · `userservice/userservice/src/main/java/com/fitness/userservice/repositories/UserRepository.java`
- [Activity service](https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/services/ActivityService.java): Spring Boot service · Handles activity operations. · `activityservice/activityservice/src/main/java/com/fitness/activityservice/services/ActivityService.java`
- [User validation](https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/services/UserValidationService.java): WebClient boundary · Validates referenced users before activity writes. · `activityservice/activityservice/src/main/java/com/fitness/activityservice/services/UserValidationService.java`
- [Activity repository](https://github.com/siddarth2904/befit/blob/main/activityservice/activityservice/src/main/java/com/fitness/activityservice/repositories/ActivityRepository.java): Mongo persistence · `activityservice/activityservice/src/main/java/com/fitness/activityservice/repositories/ActivityRepository.java`
- **Activity MongoDB**: database

### Recommendation Pipeline

- **RabbitMQ**: event broker · Carries activity events to recommendation processing.
- [Activity listener](https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityMessageListener.java): message consumer · Consumes activity messages. · `aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityMessageListener.java`
- [Recommendation generator](https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityAIService.java): AI orchestration · Transforms activities into recommendation work. · `aiservice/aiservice/src/main/java/com/fitness/aiservice/services/ActivityAIService.java`
- **Gemini**: external AI provider
- [Recommendation repository](https://github.com/siddarth2904/befit/blob/main/aiservice/aiservice/src/main/java/com/fitness/aiservice/repository/RecommendationRepository.java): Mongo persistence · `aiservice/aiservice/src/main/java/com/fitness/aiservice/repository/RecommendationRepository.java`
- **Recommendation MongoDB**: database

### Platform

- [Eureka](https://github.com/siddarth2904/befit/blob/main/eureka/eureka/src/main/java/com/server/eureka/EurekaApplication.java): service discovery · `eureka/eureka/src/main/java/com/server/eureka/EurekaApplication.java`
- [Config Server](https://github.com/siddarth2904/befit/blob/main/configserver/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java): central configuration · Serves deployment wiring per service. · `configserver/configserver/src/main/java/com/fitness/configserver/ConfigserverApplication.java`

## Connections

- React client → API client: uses
- API client → API gateway: API requests
- API gateway → Security & user sync: secured routing
- Security & user sync → Keycloak: authenticates
- Security & user sync → User service: syncs users
- API gateway → Activity service: routes activity APIs
- API gateway → User service: routes user APIs
- User service → User repository: persists users
- Activity service → User validation: validates user
- User validation → User service: checks user
- Activity service → Activity repository: stores activities
- Activity repository → Activity MongoDB: MongoDB
- Activity service → RabbitMQ: publishes activity events
- RabbitMQ → Activity listener: delivers events
- Activity listener → Recommendation generator: activity data
- Recommendation generator → Gemini: generates recommendations
- Recommendation generator → Recommendation repository: persists recommendations
- Recommendation repository → Recommendation MongoDB: MongoDB
- API gateway → Eureka: registers/discovers
- User service → Eureka: registers
- Activity service → Eureka: registers
- Recommendation generator → Eureka: registers
- Activity service → Config Server: loads config
- Recommendation generator → Config Server: loads config