# embarkxofficial/fitness-app-microservices architecture

> Architecture diagram of the GitHub repository embarkxofficial/fitness-app-microservices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/embarkxofficial/fitness-app-microservices
- Repository: https://github.com/embarkxofficial/fitness-app-microservices

## Overview

1. **Overall shape**
   - This is a Spring Boot microservices fitness application with a React frontend.
   - The backend is split into separate deployable services: **gateway**, **user-service**, **activity-service**, **ai-service**, plus supporting **config-server** and **eureka** service discovery.
   - The repo is organized so each service has its own Maven build, application entry point, and runtime config.

2. **Client layer**
   - `fitness-app-frontend` is a Vite/React SPA.
   - It contains UI components for activity browsing and editing, plus an auth slice in Redux.
   - The frontend uses `src/services/api.js` as its API boundary, so the browser likely talks to the backend through a single HTTP entrypoint rather than directly to each service.

3. **Edge/API gateway**
   - `gateway` is the main external entrypoint for backend traffic.
   - It contains `SecurityConfig`, `KeycloakUserSyncFilter`, and user-related DTO/service classes, indicating it handles authentication/authorization concerns and user synchronization at the edge.
   - `WebClientConfig` suggests it also makes downstream HTTP calls to internal services.
   - Architecturally, this is the boundary between the frontend and the internal microservices.

4. **Service discovery and centralized configuration**
   - `eureka` provides service registration and discovery.
   - `configserver` centralizes configuration for the services, with separate YAML files for `activity-service`, `ai-service`, `api-gateway`, and `user-service`.
   - This means runtime behavior is externally managed and services are not configured only from local files.

5. **User management service**
   - `userservice` owns user registration and user data.
   - Core pieces include `UserController`, `UserService`, `UserRepository`, and models for `User` and `UserRole`.
   - DTOs `RegisterRequest` and `UserResponse` define the service’s API contract.
   - This service is the system of record for user accounts and roles.

6. **Activity tracking service**
   - `activityservice` owns fitness activity records.
   - It includes `ActivityController`, `ActivityService`, `ActivityRepository`, and domain models `Activity` and `ActivityType`.
   - `UserValidationService` suggests it validates user identity or existence against another service before accepting activity data.
   - DTOs `ActivityRequest` and `ActivityResponse` separate API payloads from persistence models.

7. **AI/recommendation service**
   - `aiservice` owns recommendation generation and AI-assisted activity analysis.
   - Key classes are `RecommendationController`, `RecommendationService`, `RecommendationRepository`, `ActivityAIService`, `ActivityMessageListener`, and `GeminiService`.
   - The presence of a RabbitMQ listener plus a Gemini-specific service suggests this service consumes activity events, enriches them with AI logic, and stores recommendations.
   - `Recommendation` is the primary persisted output.

8. **Data storage boundaries**
   - The services with repositories (`userservice`, `activityservice`, `aiservice`) are MongoDB-backed, as indicated by `MongoConfig` and the repository structure.
   - Each service owns its own data model and persistence layer, which keeps user, activity, and recommendation data separated.
   - There is no shared database module in the repo, reinforcing service autonomy.

9. **Asynchronous messaging**
   - `activityservice` and `aiservice` both include `RabbitMqConfig`.
   - `aiservice` has `ActivityMessageListener`, which strongly suggests activity events are published by one service and consumed by the AI service.
   - This is the main asynchronous data flow in the architecture: activity creation can trigger downstream recommendation generation without blocking the user request.

10. **Synchronous service-to-service calls**
   - `WebClientConfig` appears in multiple services, including the gateway and activity service, showing that some internal interactions are done over HTTP.
   - Likely examples are user validation from activity processing and gateway-mediated access to backend APIs.
   - The architecture therefore mixes synchronous REST calls with asynchronous event handling.

11. **Security and identity**
   - The gateway contains explicit security and user-sync logic, and the frontend has `authConfig.js` plus Redux auth state.
   - This points to an identity-centric design where authentication is handled at the edge and user state is synchronized into the backend domain.
   - `KeycloakUserSyncFilter` indicates integration with an external identity provider, with the gateway acting as the bridge into internal services.

12. **Request flow at a high level**
   - A user interacts with the React app.
   - The app sends requests to the gateway.
   - The gateway authenticates/authorizes and forwards requests to the appropriate microservice discovered via Eureka.
   - User and activity data are persisted in their owning services, and activity events can flow into the AI service through RabbitMQ for recommendation generation.

13. **Operational structure**
   - Every backend subproject has its own Spring Boot main class, `pom.xml`, and test skeleton, so each service can be built and deployed independently.
   - The repo also includes per-service `application.yml` files, with the config server providing centralized overrides.
   - This is a classic microservices deployment model rather than a single monolith.

14. **Key architectural boundaries to diagram**
   - **Browser/UI boundary:** React frontend
   - **Edge boundary:** Spring Cloud Gateway
   - **Discovery/config boundary:** Eureka + Config Server
   - **Domain services:** user, activity, AI/recommendation
   - **Messaging boundary:** RabbitMQ between activity and AI
   - **External dependency boundary:** Keycloak for identity and Gemini for AI-related processing

Main entry points: [`gateway`](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/gateway) (Gateway), [`activityservice`](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/activityservice) (Activity Service), [`aiservice`](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/aiservice) (AI Service), [`configserver`](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/configserver) (Config Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fitness_app_frontend["React App<br/>spa"]
  node_frontend_api["API Client<br/>frontend-http<br/>[api.js]"]
  node_frontend_auth["Auth Slice<br/>redux-auth<br/>[authSlice.js]"]
end

subgraph group_edge["Edge"]
  node_gateway_app["Gateway"]
  node_gateway_security["Security"]
  node_gateway_sync["User Sync<br/>identity-filter"]
  node_gateway_user_client["User Client<br/>webclient-user"]
end

subgraph group_platform["Platform"]
  node_eureka_app["Eureka<br/>service-discovery"]
  node_configserver_app["Config Server<br/>central-config"]
end

subgraph group_services["Domain Services"]
  node_user_service_app["User Service<br/>user-domain-service"]
  node_user_controller["User API<br/>rest-controller"]
  node_user_model["User Model<br/>domain-model<br/>[User.java]"]
  node_activity_service_app["Activity Service<br/>activity-domain-service"]
  node_activity_controller["Activity API<br/>rest-controller"]
  node_activity_validation["User Check<br/>service-validation"]
  node_activity_model["Activity Model<br/>domain-model<br/>[Activity.java]"]
  node_ai_service_app["AI Service<br/>recommendation-service"]
  node_ai_controller["Recommendation API<br/>rest-controller"]
  node_ai_listener["Event Listener<br/>rabbitmq-consumer"]
  node_ai_gemini["Gemini AI<br/>ai-adapter<br/>[GeminiService.java]"]
end

node_fitness_app_frontend -->|"uses"| node_frontend_api
node_fitness_app_frontend -->|"stores auth"| node_frontend_auth
node_frontend_api -->|"requests"| node_gateway_app
node_frontend_auth -.->|"supports login"| node_gateway_security
node_gateway_app -->|"enforces"| node_gateway_security
node_gateway_app -->|"syncs user"| node_gateway_sync
node_gateway_app -->|"calls downstream"| node_gateway_user_client
node_gateway_app -->|"discovers services"| node_eureka_app
node_gateway_app -->|"routes to"| node_user_service_app
node_gateway_app -->|"routes to"| node_activity_service_app
node_gateway_app -->|"routes to"| node_ai_service_app
node_configserver_app -->|"configures"| node_user_service_app
node_configserver_app -->|"configures"| node_activity_service_app
node_configserver_app -->|"configures"| node_ai_service_app
node_configserver_app -->|"configures"| node_gateway_app
node_user_service_app -->|"exposes"| node_user_controller
node_user_service_app -->|"persists"| node_user_model
node_activity_service_app -->|"exposes"| node_activity_controller
node_activity_service_app -->|"validates"| node_activity_validation
node_activity_service_app -->|"persists"| node_activity_model
node_activity_service_app -.->|"publishes events"| node_ai_service_app
node_ai_service_app -->|"exposes"| node_ai_controller
node_ai_service_app -->|"consumes"| node_ai_listener
node_ai_service_app -->|"uses"| node_ai_gemini
node_ai_listener -.->|"receives from"| node_activity_service_app

click node_fitness_app_frontend "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/fitness-app-frontend"
click node_frontend_api "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/fitness-app-frontend/src/services/api.js"
click node_frontend_auth "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/fitness-app-frontend/src/store/authSlice.js"
click node_gateway_app "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/gateway"
click node_gateway_security "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/gateway/src/main/java/com/fitness/gateway/SecurityConfig.java"
click node_gateway_sync "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java"
click node_gateway_user_client "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/gateway/src/main/java/com/fitness/gateway/user/WebClientConfig.java"
click node_eureka_app "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/eureka"
click node_configserver_app "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/configserver"
click node_user_service_app "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/userservice"
click node_user_controller "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/userservice/src/main/java/com/fitness/userservice/controller/UserController.java"
click node_user_model "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/userservice/src/main/java/com/fitness/userservice/model/User.java"
click node_activity_service_app "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/activityservice"
click node_activity_controller "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java"
click node_activity_validation "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java"
click node_activity_model "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/activityservice/src/main/java/com/fitness/activityservice/model/Activity.java"
click node_ai_service_app "https://github.com/embarkxofficial/fitness-app-microservices/tree/main/aiservice"
click node_ai_controller "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java"
click node_ai_listener "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java"
click node_ai_gemini "https://github.com/embarkxofficial/fitness-app-microservices/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.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_fitness_app_frontend,node_frontend_api,node_frontend_auth toneBlue
class node_gateway_app,node_gateway_security,node_gateway_sync,node_gateway_user_client toneAmber
class node_eureka_app,node_configserver_app toneMint
class node_user_service_app,node_user_controller,node_user_model,node_activity_service_app,node_activity_controller,node_activity_validation,node_activity_model,node_ai_service_app,node_ai_controller,node_ai_listener,node_ai_gemini toneRose
```

## Components

### Frontend

React single-page client and UI state

- [React App](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/fitness-app-frontend): spa · Vite/React client with activity UI and auth state · `fitness-app-frontend`
- [API Client](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/fitness-app-frontend/src/services/api.js): frontend-http · Browser API boundary used by the SPA · `fitness-app-frontend/src/services/api.js`
- [Auth Slice](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/fitness-app-frontend/src/store/authSlice.js): redux-auth · Redux auth state and identity wiring · `fitness-app-frontend/src/store/authSlice.js`

### Edge

Gateway and security boundary

- [Gateway](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/gateway): api-gateway · Main external HTTP entrypoint for backend traffic · `gateway`
- [Security](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/gateway/src/main/java/com/fitness/gateway/SecurityConfig.java): security-config · Authentication and authorization configuration · `gateway/src/main/java/com/fitness/gateway/SecurityConfig.java`
- [User Sync](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java): identity-filter · Keycloak-backed user synchronization at the edge · `gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java`
- [User Client](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/gateway/src/main/java/com/fitness/gateway/user/WebClientConfig.java): webclient-user · HTTP client and user-facing edge service helpers · `gateway/src/main/java/com/fitness/gateway/user/WebClientConfig.java`

### Platform

Discovery and centralized configuration

- [Eureka](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/eureka): service-discovery · Service registration and discovery registry · `eureka`
- [Config Server](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/configserver): central-config · Centralized runtime configuration for services · `configserver`

### Domain Services

Independent backend services for users, activities, and AI

- [User Service](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/userservice): user-domain-service · Owns registration, users, and roles · `userservice`
- [User API](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/userservice/src/main/java/com/fitness/userservice/controller/UserController.java): rest-controller · User registration and profile endpoints · `userservice/src/main/java/com/fitness/userservice/controller/UserController.java`
- [User Model](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/userservice/src/main/java/com/fitness/userservice/model/User.java): domain-model · User and role persistence model · `userservice/src/main/java/com/fitness/userservice/model/User.java`
- [Activity Service](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/activityservice): activity-domain-service · Owns fitness activity records and validation · `activityservice`
- [Activity API](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java): rest-controller · Activity CRUD and submission endpoints · `activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java`
- [User Check](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java): service-validation · Validates activity requests against user data · `activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java`
- [Activity Model](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/activityservice/src/main/java/com/fitness/activityservice/model/Activity.java): domain-model · Activity and activity type persistence model · `activityservice/src/main/java/com/fitness/activityservice/model/Activity.java`
- [AI Service](https://github.com/embarkxofficial/fitness-app-microservices/tree/main/aiservice): recommendation-service · Consumes activity events and produces recommendations · `aiservice`
- [Recommendation API](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java): rest-controller · Endpoints for stored recommendations · `aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java`
- [Event Listener](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java): rabbitmq-consumer · Consumes activity messages for downstream AI processing · `aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java`
- [Gemini AI](https://github.com/embarkxofficial/fitness-app-microservices/blob/main/aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java): ai-adapter · Gemini-backed analysis and generation adapter · `aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java`

## Connections

- React App → API Client: uses · SPA calls backend through a single client boundary
- React App → Auth Slice: stores auth · UI state includes authentication and user session data
- API Client → Gateway: requests · Frontend traffic is sent to the gateway entrypoint
- Auth Slice → Security: supports login · Auth state aligns with gateway security handling
- Gateway → Security: enforces · Gateway applies security policies to inbound requests
- Gateway → User Sync: syncs user · Gateway bridges external identity into backend user state
- Gateway → User Client: calls downstream · Gateway can invoke internal services through HTTP clients
- Gateway → Eureka: discovers services · Gateway resolves backend service locations via discovery
- Gateway → User Service: routes to · User-related traffic is forwarded to the owning service
- Gateway → Activity Service: routes to · Activity traffic is forwarded to the activity service
- Gateway → AI Service: routes to · Recommendation traffic is forwarded to the AI service
- Config Server → User Service: configures · Central config provides service-specific settings
- Config Server → Activity Service: configures · Central config provides service-specific settings
- Config Server → AI Service: configures · Central config provides service-specific settings
- Config Server → Gateway: configures · Central config provides gateway settings
- User Service → User API: exposes · User service publishes its REST API
- User Service → User Model: persists · User service owns its domain model and storage
- Activity Service → Activity API: exposes · Activity service publishes its REST API
- Activity Service → User Check: validates · Activity submissions are checked against user state
- Activity Service → Activity Model: persists · Activity service owns activity domain objects
- Activity Service → AI Service: publishes events · Activity changes can flow asynchronously to AI processing
- AI Service → Recommendation API: exposes · Recommendation service publishes its REST API
- AI Service → Event Listener: consumes · AI service listens for activity messages from the broker
- AI Service → Gemini AI: uses · AI service delegates analysis to Gemini integration
- Event Listener → Activity Service: receives from · Listener handles activity-derived events from upstream services
