How embarkxofficial/fitness-app-microservices works
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 Gateway · activityservice Activity Service · aiservice AI Service · configserver Config Server
Components 20
Frontend
React single-page client and UI state
- React App · Vite/React client with activity UI and auth state
fitness-app-frontend - API Client · Browser API boundary used by the SPA
fitness-app-frontend/src/services/api.js - Auth Slice · Redux auth state and identity wiring
fitness-app-frontend/src/store/authSlice.js
Edge
Gateway and security boundary
- Gateway · Main external HTTP entrypoint for backend traffic
gateway - Security · Authentication and authorization configuration
gateway/src/main/java/com/fitness/gateway/SecurityConfig.java - User Sync · Keycloak-backed user synchronization at the edge
gateway/src/main/java/com/fitness/gateway/KeycloakUserSyncFilter.java - User Client · HTTP client and user-facing edge service helpers
gateway/src/main/java/com/fitness/gateway/user/WebClientConfig.java
Platform
Discovery and centralized configuration
- Eureka · Service registration and discovery registry
eureka - Config Server · Centralized runtime configuration for services
configserver
Domain Services
Independent backend services for users, activities, and AI
- User Service · Owns registration, users, and roles
userservice - User API · User registration and profile endpoints
userservice/src/main/java/com/fitness/userservice/controller/UserController.java - User Model · User and role persistence model
userservice/src/main/java/com/fitness/userservice/model/User.java - Activity Service · Owns fitness activity records and validation
activityservice - Activity API · Activity CRUD and submission endpoints
activityservice/src/main/java/com/fitness/activityservice/controller/ActivityController.java - User Check · Validates activity requests against user data
activityservice/src/main/java/com/fitness/activityservice/service/UserValidationService.java - Activity Model · Activity and activity type persistence model
activityservice/src/main/java/com/fitness/activityservice/model/Activity.java - AI Service · Consumes activity events and produces recommendations
aiservice - Recommendation API · Endpoints for stored recommendations
aiservice/src/main/java/com/fitness/aiservice/controller/RecommendationController.java - Event Listener · Consumes activity messages for downstream AI processing
aiservice/src/main/java/com/fitness/aiservice/service/ActivityMessageListener.java - Gemini AI · Gemini-backed analysis and generation adapter
aiservice/src/main/java/com/fitness/aiservice/service/GeminiService.java
Connections 25
- 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