# missgomezzz/dancesync_backend architecture

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

- Interactive diagram: https://gitdiagram.com/missgomezzz/dancesync_backend
- Repository: https://github.com/missgomezzz/dancesync_backend

## Overview

DanceSync is a multiplayer dance-battle backend. The principal workflow is: a frontend reaches the gateway, players join rooms and battle over HTTP/WebSocket, and completed matches are recorded by the users service. Battle play includes song selection, spectator chat and voting, live scoring, and timed word races; users-service also provides profiles and an auditable admin trail. The README documents service routing and persistence; sampled source confirms selected wiring, but many use-case and gateway internals were not inspected, so uncertain links are omitted.

Main entry points: [`battle-service/src/server.ts`](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/server.ts) (Battle server), [`api-gateway/src/main/java/com/dancesync/gateway/ApiGatewayApplication.java`](https://github.com/missgomezzz/dancesync_backend/blob/main/api-gateway/src/main/java/com/dancesync/gateway/ApiGatewayApplication.java) (Gateway entry), [`users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest`](https://github.com/missgomezzz/dancesync_backend/tree/main/users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest) (User and match API), [`battle-service/src/infrastructure/ws/socketHandlers.ts`](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/ws/socketHandlers.ts) (Socket events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_gateway_app["Gateway entry"]
  node_gateway_security["Auth and sessions"]
  node_gateway_audit["Gateway audit"]
  node_gateway_limits["Rate limiting"]
  node_gateway_health["Gateway health"]
end

subgraph group_battle["Real-time battles"]
  node_battle_server["Battle server<br/>[server.ts]"]
  node_http_routes["HTTP routes<br/>[routes.ts]"]
  node_socket_handlers["Socket events<br/>[socketHandlers.ts]"]
  node_room_usecases["Room commands"]
  node_battle_usecases["Battle commands"]
  node_song_selection["Song selection"]
  node_room_rules["Room rules<br/>[RoomService.ts]"]
  node_room_model["Room state<br/>[Room.ts]"]
  node_word_race["Word race<br/>[WordRace.ts]"]
  node_word_scheduler["Race scheduler"]
  node_match_result["Match results"]
end

subgraph group_records["Users and records"]
  node_users_rest["User and match API"]
  node_user_service["User services<br/>[UserService.java]"]
  node_match_service["Match service<br/>[MatchService.java]"]
  node_audit_ingest["Audit ingestion"]
  node_audit_service["Audit chain and queries<br/>[AuditService.java]"]
  node_admin_alerts["Admin alerts"]
  node_user_app["Users service"]
end

subgraph group_state["State and integrations"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_frontend(("Frontend"))

node_frontend -->|"sends HTTP/WebSocket"| node_gateway_app
node_gateway_app -->|"routes HTTP"| node_http_routes
node_gateway_app -->|"routes sockets"| node_socket_handlers
node_gateway_app -->|"routes user API"| node_user_app
node_battle_server -->|"mounts router"| node_http_routes
node_battle_server -.->|"configures sockets"| node_socket_handlers
node_http_routes -->|"executes room actions"| node_room_usecases
node_socket_handlers -->|"dispatches room events"| node_room_usecases
node_socket_handlers -->|"dispatches battle events"| node_battle_usecases
node_room_usecases -.->|"applies room rules"| node_room_rules
node_battle_usecases -.->|"updates battle state"| node_room_rules
node_room_rules -->|"computes room state"| node_room_model
node_room_rules -->|"checks song selection"| node_song_selection
node_battle_server -->|"configures timers"| node_word_scheduler
node_word_scheduler -.->|"schedules rounds"| node_word_race
node_battle_server -->|"wires match recording"| node_match_result
node_match_result -->|"publishes match result"| node_users_rest
node_users_rest -.->|"handles user requests"| node_user_service
node_users_rest -->|"handles match requests"| node_match_service
node_match_service -->|"persists matches"| node_postgres
node_user_service -->|"persists profiles"| node_postgres
node_users_rest -->|"accepts audit events"| node_audit_ingest
node_audit_ingest -->|"records events"| node_audit_service
node_audit_service -.->|"stores audit records"| node_postgres
node_admin_alerts -->|"verifies audit chain"| node_audit_service
node_battle_server -.->|"uses shared state"| node_redis
node_user_app -->|"connects via JDBC"| node_postgres

click node_gateway_app "https://github.com/missgomezzz/dancesync_backend/blob/main/api-gateway/src/main/java/com/dancesync/gateway/ApiGatewayApplication.java"
click node_gateway_security "https://github.com/missgomezzz/dancesync_backend/tree/main/api-gateway/src/main/java/com/dancesync/gateway/security"
click node_gateway_audit "https://github.com/missgomezzz/dancesync_backend/tree/main/api-gateway/src/main/java/com/dancesync/gateway/audit"
click node_gateway_limits "https://github.com/missgomezzz/dancesync_backend/tree/main/api-gateway/src/main/java/com/dancesync/gateway/ratelimit"
click node_gateway_health "https://github.com/missgomezzz/dancesync_backend/blob/main/api-gateway/src/main/java/com/dancesync/gateway/observability/ApiPortHealthController.java"
click node_battle_server "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/server.ts"
click node_http_routes "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/http/routes.ts"
click node_socket_handlers "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/ws/socketHandlers.ts"
click node_room_usecases "https://github.com/missgomezzz/dancesync_backend/tree/main/battle-service/src/application/usecases"
click node_battle_usecases "https://github.com/missgomezzz/dancesync_backend/tree/main/battle-service/src/application/usecases"
click node_song_selection "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/services/SongSelectionService.ts"
click node_room_rules "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/services/RoomService.ts"
click node_room_model "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/model/Room.ts"
click node_word_race "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/model/WordRace.ts"
click node_word_scheduler "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/scheduling/WordRaceScheduler.ts"
click node_match_result "https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/application/usecases/RecordMatchResult.ts"
click node_users_rest "https://github.com/missgomezzz/dancesync_backend/tree/main/users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest"
click node_user_service "https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/UserService.java"
click node_match_service "https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/MatchService.java"
click node_audit_ingest "https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest/admin/AuditIngestController.java"
click node_audit_service "https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/AuditService.java"
click node_admin_alerts "https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/AdminAlertsService.java"
click node_user_app "https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/UsersServiceApplication.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_gateway_app,node_gateway_security,node_gateway_audit,node_gateway_limits,node_gateway_health,node_frontend toneBlue
class node_battle_server,node_http_routes,node_socket_handlers,node_room_usecases,node_battle_usecases,node_song_selection,node_room_rules,node_room_model,node_word_race,node_word_scheduler,node_match_result toneAmber
class node_users_rest,node_user_service,node_match_service,node_audit_ingest,node_audit_service,node_admin_alerts,node_user_app toneMint
class node_postgres,node_redis toneRose
```

## Components

### API gateway

- [Gateway entry](https://github.com/missgomezzz/dancesync_backend/blob/main/api-gateway/src/main/java/com/dancesync/gateway/ApiGatewayApplication.java): `api-gateway/src/main/java/com/dancesync/gateway/ApiGatewayApplication.java`
- [Auth and sessions](https://github.com/missgomezzz/dancesync_backend/tree/main/api-gateway/src/main/java/com/dancesync/gateway/security): `api-gateway/src/main/java/com/dancesync/gateway/security`
- [Gateway audit](https://github.com/missgomezzz/dancesync_backend/tree/main/api-gateway/src/main/java/com/dancesync/gateway/audit): `api-gateway/src/main/java/com/dancesync/gateway/audit`
- [Rate limiting](https://github.com/missgomezzz/dancesync_backend/tree/main/api-gateway/src/main/java/com/dancesync/gateway/ratelimit): `api-gateway/src/main/java/com/dancesync/gateway/ratelimit`
- [Gateway health](https://github.com/missgomezzz/dancesync_backend/blob/main/api-gateway/src/main/java/com/dancesync/gateway/observability/ApiPortHealthController.java): `api-gateway/src/main/java/com/dancesync/gateway/observability/ApiPortHealthController.java`

### Real-time battles

- [Battle server](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/server.ts): `battle-service/src/server.ts`
- [HTTP routes](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/http/routes.ts): `battle-service/src/infrastructure/http/routes.ts`
- [Socket events](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/ws/socketHandlers.ts): `battle-service/src/infrastructure/ws/socketHandlers.ts`
- [Room commands](https://github.com/missgomezzz/dancesync_backend/tree/main/battle-service/src/application/usecases): `battle-service/src/application/usecases`
- [Battle commands](https://github.com/missgomezzz/dancesync_backend/tree/main/battle-service/src/application/usecases): `battle-service/src/application/usecases`
- [Song selection](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/services/SongSelectionService.ts): `battle-service/src/domain/services/SongSelectionService.ts`
- [Room rules](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/services/RoomService.ts): `battle-service/src/domain/services/RoomService.ts`
- [Room state](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/model/Room.ts): `battle-service/src/domain/model/Room.ts`
- [Word race](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/domain/model/WordRace.ts): `battle-service/src/domain/model/WordRace.ts`
- [Race scheduler](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/infrastructure/scheduling/WordRaceScheduler.ts): `battle-service/src/infrastructure/scheduling/WordRaceScheduler.ts`
- [Match results](https://github.com/missgomezzz/dancesync_backend/blob/main/battle-service/src/application/usecases/RecordMatchResult.ts): `battle-service/src/application/usecases/RecordMatchResult.ts`

### Users and records

- [User and match API](https://github.com/missgomezzz/dancesync_backend/tree/main/users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest): `users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest`
- [User services](https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/UserService.java): `users-service/src/main/java/com/dancesync/users/application/service/UserService.java`
- [Match service](https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/MatchService.java): `users-service/src/main/java/com/dancesync/users/application/service/MatchService.java`
- [Audit ingestion](https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest/admin/AuditIngestController.java): `users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest/admin/AuditIngestController.java`
- [Audit chain and queries](https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/AuditService.java): `users-service/src/main/java/com/dancesync/users/application/service/AuditService.java`
- [Admin alerts](https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/application/service/AdminAlertsService.java): `users-service/src/main/java/com/dancesync/users/application/service/AdminAlertsService.java`
- [Users service](https://github.com/missgomezzz/dancesync_backend/blob/main/users-service/src/main/java/com/dancesync/users/UsersServiceApplication.java): `users-service/src/main/java/com/dancesync/users/UsersServiceApplication.java`

### State and integrations

- **PostgreSQL**
- **Redis**

### Other components

- **Frontend**

## Connections

- Frontend → Gateway entry: sends HTTP/WebSocket
- Gateway entry → HTTP routes: routes HTTP
- Gateway entry → Socket events: routes sockets
- Gateway entry → Users service: routes user API
- Battle server → HTTP routes: mounts router (evidence: `battle-service/src/server.ts`)
- Battle server → Socket events: configures sockets (evidence: `battle-service/src/server.ts`)
- HTTP routes → Room commands: executes room actions (evidence: `battle-service/src/infrastructure/http/routes.ts`)
- Socket events → Room commands: dispatches room events (evidence: `battle-service/src/infrastructure/ws/socketHandlers.ts`)
- Socket events → Battle commands: dispatches battle events (evidence: `battle-service/src/infrastructure/ws/socketHandlers.ts`)
- Room commands → Room rules: applies room rules (evidence: `battle-service/src/application/usecases/AwardWordBonus.ts`)
- Battle commands → Room rules: updates battle state (evidence: `battle-service/src/application/usecases/AwardWordBonus.ts`)
- Room rules → Room state: computes room state (evidence: `battle-service/src/domain/services/RoomService.ts`)
- Room rules → Song selection: checks song selection (evidence: `battle-service/src/domain/services/RoomService.ts`)
- Battle server → Race scheduler: configures timers (evidence: `battle-service/src/server.ts`)
- Race scheduler → Word race: schedules rounds
- Battle server → Match results: wires match recording (evidence: `battle-service/src/server.ts`)
- Match results → User and match API: publishes match result
- User and match API → User services: handles user requests
- User and match API → Match service: handles match requests (evidence: `users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest/MatchController.java`)
- Match service → PostgreSQL: persists matches
- User services → PostgreSQL: persists profiles
- User and match API → Audit ingestion: accepts audit events (evidence: `users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest/admin/AuditIngestController.java`)
- Audit ingestion → Audit chain and queries: records events (evidence: `users-service/src/main/java/com/dancesync/users/infrastructure/adapter/in/rest/admin/AuditIngestController.java`)
- Audit chain and queries → PostgreSQL: stores audit records
- Admin alerts → Audit chain and queries: verifies audit chain (evidence: `users-service/src/main/java/com/dancesync/users/application/service/AdminAlertsService.java`)
- Battle server → Redis: uses shared state
- Users service → PostgreSQL: connects via JDBC
