TeamSync Core (NutriFlow)

Verification-first work orchestration: Spring Boot microservices, MariaDB 10.11, OIDC (Keycloak or any issuer aligned with ms-gestionUser), Angular 17, STOMP WebSockets.

Maven reactor (all services)

From the repository root:

mvn clean install -DskipTests

Modules: teamsync-common, ms-team-orchestration, ms-task-engine, ms-verification, ms-gamification, ms-realtime, ms-score-engine.

Prerequisites

• Java 17, Maven 3.9+
• Node 18+ (for Angular)
• Docker (optional): MariaDB 10.11 + Keycloak via docker-compose.dev.yml (see below). Align JWT issuer-uri with your realm (foodnexus in this repo’s default config, or override to nutriflow if you import that realm).

Infrastructure

docker compose -f docker-compose.dev.yml up -d

Port 3333 already in use on the host: set MARIADB_HOST_PORT in a .env at the project root to another free port, run compose again, then use jdbc:mariadb://localhost:<port>/teamsync (e.g. SPRING_DATASOURCE_URL).

If you previously used a different MariaDB data directory or the old multi-database compose, drop volumes first (e.g. docker compose -f docker-compose.dev.yml down -v) so MariaDB initializes cleanly.

Creates MariaDB 10.11 on localhost (default host port 3333; overridable with MARIADB_HOST_PORT). User/password nutriflow / nutriflow; root password root. Single database: teamsync. The teamsync-core profile (see compose) exposes the app on 8123 by default.

Identity: Point every service and the Angular app at the same Keycloak (or OIDC) issuer as ms-gestionUser (realm foodnexus in the neighbor doc). Override the default issuer with Spring’s env var, for example:
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=https://your-keycloak/realms/foodnexus
Optional reference realm export for manual import into Keycloak: docker/keycloak/foodnexus-realm.json.

User service (external)

ms-gestionUser is not in this repo. Integration pattern (Eureka, forwarded JWT, issuer alignment, /me/update, errors) is NEIGHBOR-INTEGRATION.md. A short Feign-focused summary lives in SERVICE.md.

• With Eureka (default for ms-team-orchestration): register ms-gestionUser in the same registry; Feign calls the logical service id (no hard-coded localhost:8087).
• Without Eureka: run TeamSync with --spring.profiles.active=local to point Feign at http://localhost:8087.

Optional Keycloak protocol mapper: emit foodnexus_user_id, nutriflow_user_id, or internal_user_id (numeric internal id) so task APIs align with DB user ids (JwtUserId in ms-task-engine checks these in order).

Eureka

cd eureka-server && mvn spring-boot:run

ms-team-orchestration registers with Eureka by default and resolves ms-gestionUser through the load balancer. Other services can stay Eureka-optional unless you add Feign targets for them.

Microservices

Service	Port	Database
ms-team-orchestration	8088	team_orchestration
ms-task-engine	8089	task_engine
ms-verification	8090	verification
ms-gamification	8091	gamification
ms-realtime	8092	(none)
ms-score-engine	8093	score_engine

Start order (typical): Eureka → MariaDB → ms-gestionUser (+ shared Keycloak) → ms-score-engine → gamification → team orchestration → task engine → verification → realtime → Angular.

ms-score-engine (skill & balance)

• REST: GET /api/skills, GET /api/project-types, GET /api/members/{userId}/skills?teamId=, PUT /api/members/{userId}/skills/self?teamId=, POST /api/members/{userId}/skills/update?teamId= (called by ms-verification after a pass), GET /api/teams/{teamId}/balance?projectType=, GET /api/teams/{teamId}/suggestions?projectType=&limit=.
• Uses X-Internal-Key / teamsync.internal.api-key when ms-team-orchestration exposes GET /api/internal/teams/{teamId}/member-ids for member lists.
• ms-team-orchestration can delegate dashboard balance to the score service when teamsync.score-engine.enabled=true (default) and it calls http://localhost:8093 (see application.yml / Feign ms-score-engine).

cd ms-gamification && mvn spring-boot:run
cd ms-team-orchestration && mvn spring-boot:run
# ... etc.

OAuth2: each service defaults to issuer-uri: http://localhost:8180/realms/foodnexus as a placeholder — it must match the issuer configured on ms-gestionUser in your environment (override via SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI or per-service application.yml). For local work without JWT, set teamsync.security.oauth2-enabled=false (tests use this automatically).

Swagger UI (where springdoc is on the classpath): /swagger-ui.html.

Team balance (two paths)

• ms-score-engine (canonical, project-typed): uses project_skill_requirements and stored member_skills. Critical skills need at least one member at (\ge 80); balanced skills use lower standard deviation across members as a positive signal; weak balanced skills are those with team average (< 60). Final score is (0.4 \cdot c + 0.35 \cdot (1-normStd) + 0.25 \cdot coverageRatio) in ([0,1]), persisted to team_balance_history.
• Legacy heuristic in ms-team-orchestration: if the score service is down or teamsync.score-engine.enabled=false, the previous NutriFlow six-dimension spread model in BalanceCalculator is used (see that class and SuggestionService there forgoal-based heuristics).

SDG methodology (UI)

SdgImpactService on the frontend exposes demo aggregates (food waste kg, meals from points, CO₂, partnerships). Replace with API-backed rollups when task and org endpoints expose verified completion metadata. The SDGBarComponent is fixed on all main routes and explains per-screen contribution via native tooltips.

Angular frontend

cd frontend
npm install
npm start

Dev server: http://localhost:4200. proxy.conf.json routes /api/* to the microservice ports above. Set frontend/src/environments/environment.ts keycloakUrl / realm / clientId to your Keycloak. The dev import uses cis-front on port 8180 (see docker/keycloak/README.md).

WebSocket (STOMP)

• SockJS endpoint: http://localhost:8092/ws
• Topics: /topic/teams/{teamId}/leaderboard, /tasks, /balance; queue: /queue/users/{userId}/notifications
• HTTP triggers: POST /api/realtime/teams/{teamId}/leaderboard (etc.) on ms-realtime

Tests

cd ms-team-orchestration && mvn test
cd ms-gamification && mvn test

Deliverables status

Core paths for teams, tasks, verification (HTTP + manual), gamification (skills, leaderboard, task-verified hook), realtime push API, Eureka-ready clients, Flyway schemas + badge seed, and Angular shell with SDG bar, Keycloak, team list/create/dashboard, and Chart.js radar are in place. Extend DB/CLI verification strategies, AI feedback, and richer Angular modules (board, task detail editor, full leaderboard WS) as needed for production.