# vixvify/bangmod-guesser architecture

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

- Interactive diagram: https://gitdiagram.com/vixvify/bangmod-guesser
- Repository: https://github.com/vixvify/bangmod-guesser

## Overview

This is a Next.js location-guessing game with public play and administration. Players enter a game, inspect location imagery, submit timed map guesses, and review round scores and a final summary; the game service owns scoring and game-state operations. Admins manage locations and images, users, and dashboard reporting. The README also documents authentication, profiles, leaderboards, rate limiting, and Cloudflare R2 storage. Arrows are limited to relationships shown by excerpts, the source index, or README; several feature internals were not sampled.

Main entry points: [`src/container.ts`](https://github.com/vixvify/bangmod-guesser/blob/main/src/container.ts) (Service composition), [`src/app/api/locations`](https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/locations) (Location API), [`src/features/game/server/game.service.ts`](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/server/game.service.ts) (Game rules), [`src/features/locations/server/location.service.ts`](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/locations/server/location.service.ts) (Location management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Game play"]
  node_game_ui["Game screens<br/>[game-session.tsx]"]
  node_game_api["Game API"]
  node_game_service["Game rules<br/>[game.service.ts]"]
  node_game_repository[("Game persistence<br/>[game.repository.ts]")]
  node_game_scoring["Scoring and distance<br/>[game-scoring.ts]"]
end

subgraph group_identity["Identity and users"]
  node_auth_ui["Sign-in screens<br/>[auth-layout.tsx]"]
  node_auth_api["Session API"]
  node_auth_service["Authentication<br/>[auth.service.ts]"]
  node_user_admin["User administration<br/>[user.service.ts]"]
end

subgraph group_admin["Admin content"]
  node_location_ui["Location admin"]
  node_location_api["Location API"]
  node_location_service["Location management"]
  node_location_repository[("Location records")]
  node_image_service["Image storage service<br/>[image.service.ts]"]
end

subgraph group_insights["Player and admin insights"]
  node_dashboard["Admin dashboard"]
  node_leaderboard["Leaderboard"]
  node_profile["Player profile"]
end

subgraph group_platform["Application platform"]
  node_api_security["Route security<br/>[route.ts]"]
  node_validation["Request validation<br/>[validation.ts]"]
  node_response["API responses<br/>[api-response.ts]"]
  node_runtime_config["Runtime configuration<br/>[runtime.ts]"]
  node_composition["Service composition<br/>[container.ts]"]
end

node_player(("Player"))
node_r2[("Cloudflare R2")]
node_prisma[("PostgreSQL")]

node_player -->|"plays"| node_game_ui
node_game_ui -.->|"requests game"| node_game_api
node_game_api -->|"gets services"| node_composition
node_composition -->|"wires"| node_game_service
node_game_service -.->|"uses repository"| node_game_repository
node_game_service -->|"calculates scores"| node_game_scoring
node_game_service -.->|"selects locations"| node_location_repository
node_auth_ui -.->|"submits credentials"| node_auth_api
node_auth_api -->|"gets services"| node_composition
node_composition -->|"wires"| node_auth_service
node_location_ui -.->|"manages locations"| node_location_api
node_location_api -->|"gets service"| node_composition
node_composition -->|"wires"| node_location_service
node_location_service -->|"reads and writes"| node_location_repository
node_location_service -->|"uploads images"| node_image_service
node_composition -->|"wires"| node_image_service
node_image_service -.->|"stores images"| node_r2
node_dashboard -->|"gets service"| node_composition
node_composition -->|"wires services"| node_dashboard
node_leaderboard -->|"gets service"| node_composition
node_composition -->|"wires services"| node_leaderboard
node_profile -->|"gets service"| node_composition
node_composition -->|"wires services"| node_profile
node_api_security -->|"reads policy"| node_runtime_config
node_api_security -.->|"checks session"| node_auth_service
node_location_api -->|"guards routes"| node_api_security
node_location_api -->|"validates input"| node_validation
node_location_api -->|"formats output"| node_response
node_composition -.->|"repositories persist"| node_prisma

click node_game_ui "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/components/game-session.tsx"
click node_game_api "https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/games"
click node_game_service "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/server/game.service.ts"
click node_game_repository "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/server/game.repository.ts"
click node_game_scoring "https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/game-scoring.ts"
click node_auth_ui "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/auth/components/auth-layout.tsx"
click node_auth_api "https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/session"
click node_auth_service "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/auth/server/auth.service.ts"
click node_user_admin "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/users/server/user.service.ts"
click node_location_ui "https://github.com/vixvify/bangmod-guesser/tree/main/src/features/locations/components"
click node_location_api "https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/locations"
click node_location_service "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/locations/server/location.service.ts"
click node_location_repository "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/locations/server/location.repository.ts"
click node_image_service "https://github.com/vixvify/bangmod-guesser/blob/main/src/features/images/server/image.service.ts"
click node_dashboard "https://github.com/vixvify/bangmod-guesser/tree/main/src/features/dashboard"
click node_leaderboard "https://github.com/vixvify/bangmod-guesser/tree/main/src/features/leaderboard"
click node_profile "https://github.com/vixvify/bangmod-guesser/tree/main/src/features/profile"
click node_api_security "https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/security/route.ts"
click node_validation "https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/validation.ts"
click node_response "https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/api-response.ts"
click node_runtime_config "https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/config/runtime.ts"
click node_composition "https://github.com/vixvify/bangmod-guesser/blob/main/src/container.ts"

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_game_ui,node_game_api,node_game_service,node_game_repository,node_game_scoring toneBlue
class node_auth_ui,node_auth_api,node_auth_service,node_user_admin,node_r2,node_prisma toneAmber
class node_location_ui,node_location_api,node_location_service,node_location_repository,node_image_service toneMint
class node_dashboard,node_leaderboard,node_profile toneRose
class node_api_security,node_validation,node_response,node_runtime_config,node_composition,node_player toneIndigo
```

## Components

### Game play

- [Game screens](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/components/game-session.tsx): `src/features/game/components/game-session.tsx`
- [Game API](https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/games): `src/app/api/games`
- [Game rules](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/server/game.service.ts): `src/features/game/server/game.service.ts`
- [Game persistence](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/game/server/game.repository.ts): `src/features/game/server/game.repository.ts`
- [Scoring and distance](https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/game-scoring.ts): `src/shared/lib/game-scoring.ts`

### Identity and users

- [Sign-in screens](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/auth/components/auth-layout.tsx): `src/features/auth/components/auth-layout.tsx`
- [Session API](https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/session): `src/app/api/session`
- [Authentication](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/auth/server/auth.service.ts): `src/features/auth/server/auth.service.ts`
- [User administration](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/users/server/user.service.ts): `src/features/users/server/user.service.ts`

### Admin content

- [Location admin](https://github.com/vixvify/bangmod-guesser/tree/main/src/features/locations/components): `src/features/locations/components`
- [Location API](https://github.com/vixvify/bangmod-guesser/tree/main/src/app/api/locations): `src/app/api/locations`
- [Location management](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/locations/server/location.service.ts): `src/features/locations/server/location.service.ts`
- [Location records](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/locations/server/location.repository.ts): `src/features/locations/server/location.repository.ts`
- [Image storage service](https://github.com/vixvify/bangmod-guesser/blob/main/src/features/images/server/image.service.ts): `src/features/images/server/image.service.ts`

### Player and admin insights

- [Admin dashboard](https://github.com/vixvify/bangmod-guesser/tree/main/src/features/dashboard): `src/features/dashboard`
- [Leaderboard](https://github.com/vixvify/bangmod-guesser/tree/main/src/features/leaderboard): `src/features/leaderboard`
- [Player profile](https://github.com/vixvify/bangmod-guesser/tree/main/src/features/profile): `src/features/profile`

### Application platform

- [Route security](https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/security/route.ts): `src/shared/lib/security/route.ts`
- [Request validation](https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/validation.ts): `src/shared/lib/validation.ts`
- [API responses](https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/lib/api-response.ts): `src/shared/lib/api-response.ts`
- [Runtime configuration](https://github.com/vixvify/bangmod-guesser/blob/main/src/shared/config/runtime.ts): `src/shared/config/runtime.ts`
- [Service composition](https://github.com/vixvify/bangmod-guesser/blob/main/src/container.ts): `src/container.ts`

### Other components

- **Player**
- **Cloudflare R2**
- **PostgreSQL**

## Connections

- Player → Game screens: plays (evidence: `README.md`)
- Game screens → Game API: requests game
- Game API → Service composition: gets services (evidence: `src/app/api/games/route.ts`)
- Service composition → Game rules: wires (evidence: `src/container.ts`)
- Game rules → Game persistence: uses repository
- Game rules → Scoring and distance: calculates scores (evidence: `src/features/game/server/game.service.ts`)
- Game rules → Location records: selects locations
- Sign-in screens → Session API: submits credentials
- Session API → Service composition: gets services (evidence: `src/app/api/session/login/route.ts`)
- Service composition → Authentication: wires (evidence: `src/container.ts`)
- Location admin → Location API: manages locations
- Location API → Service composition: gets service (evidence: `src/app/api/locations/route.ts`)
- Service composition → Location management: wires (evidence: `src/container.ts`)
- Location management → Location records: reads and writes (evidence: `src/features/locations/server/location.service.ts`)
- Location management → Image storage service: uploads images (evidence: `src/features/locations/server/location.service.ts`)
- Service composition → Image storage service: wires (evidence: `src/container.ts`)
- Image storage service → Cloudflare R2: stores images (evidence: `README.md`)
- Admin dashboard → Service composition: gets service (evidence: `src/app/api/dashboard/route.ts`)
- Service composition → Admin dashboard: wires services (evidence: `src/container.ts`)
- Leaderboard → Service composition: gets service (evidence: `src/container.ts`)
- Service composition → Leaderboard: wires services (evidence: `src/container.ts`)
- Player profile → Service composition: gets service (evidence: `src/app/api/profile/route.ts`)
- Service composition → Player profile: wires services (evidence: `src/container.ts`)
- Route security → Runtime configuration: reads policy (evidence: `src/shared/lib/security/route.ts`)
- Route security → Authentication: checks session
- Location API → Route security: guards routes (evidence: `src/app/api/locations/route.ts`)
- Location API → Request validation: validates input (evidence: `src/app/api/locations/route.ts`)
- Location API → API responses: formats output (evidence: `src/app/api/locations/route.ts`)
- Service composition → PostgreSQL: repositories persist