# eltrueno/truenoproclubservices architecture

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

- Interactive diagram: https://gitdiagram.com/eltrueno/truenoproclubservices
- Repository: https://github.com/eltrueno/truenoproclubservices

## Overview

TPCS manages Pro Clubs across club websites and a shared account portal. A visitor browses club members, matches, statistics, achievements and Team of the Week (TOTW); the web client fetches club data from the REST API. In the background, the worker imports and normalizes EA match data, updates club and player records, computes achievements and aggregates, and publishes events for Discord announcements. Authentication, linked player identities and account settings are shared across clubs. The README documents these capabilities; some subsystem links below rely on that documentation because their source was not sampled.

Main entry points: [`apps/worker/src`](https://github.com/eltrueno/truenoproclubservices/tree/main/apps/worker/src) (Sync worker), [`apps/api/src/app.ts`](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/app.ts) (REST API), [`packages/shared/src/models/sharedDb.ts`](https://github.com/eltrueno/truenoproclubservices/blob/main/packages/shared/src/models/sharedDb.ts) (Shared MongoDB models), [`apps/api/src/routes/admin.ts`](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/admin.ts) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["Club and account frontends"]
  node_clubweb["Club website"]
  node_accounts["Account portal"]
end

subgraph group_api["Club REST API"]
  node_apiapp["REST API<br/>[app.ts]"]
  node_clubroutes["Club routes<br/>[club.ts]"]
  node_memberroutes["Member routes<br/>[members.ts]"]
  node_adminroutes["Admin routes<br/>[admin.ts]"]
  node_memberservice["Member services"]
  node_averages["Position averages"]
  node_mongodb[("Shared MongoDB models<br/>[sharedDb.ts]")]
end

subgraph group_identity["Authentication and identity"]
  node_authservice["Auth service"]
  node_twitchsync["Twitch sync<br/>[twitchService.ts]"]
end

subgraph group_processing["Sync and analytics"]
  node_worker["Sync worker"]
  node_matchdto["Match normalization<br/>[match.dto.ts]"]
  node_achievement["Achievement calculation"]
  node_totw["TOTW job<br/>[totw.service.ts]"]
end

subgraph group_events["Events and media"]
  node_rabbit["RabbitMQ events"]
  node_discord["Discord bot<br/>[rabbitmqHandler.js]"]
  node_renderer["Image renderer<br/>[imageCapture.ts]"]
end

node_visitor(("Club visitor"))
node_eaapi{{"EA Pro Clubs API"}}
node_r2[("Cloudflare R2")]

node_visitor -->|"browses"| node_clubweb
node_clubweb -->|"fetches club data"| node_apiapp
node_clubweb -->|"redirects for login"| node_accounts
node_accounts -->|"authenticates"| node_authservice
node_apiapp -->|"mounts routes"| node_clubroutes
node_apiapp -->|"mounts routes"| node_memberroutes
node_apiapp -->|"mounts routes"| node_adminroutes
node_clubroutes -->|"reads club data"| node_mongodb
node_memberroutes -->|"serves member data"| node_mongodb
node_adminroutes -->|"administers records"| node_mongodb
node_adminroutes -->|"delegates member edits"| node_memberservice
node_adminroutes -->|"uploads player images"| node_r2
node_worker -->|"fetches new matches"| node_eaapi
node_worker -->|"normalizes matches"| node_matchdto
node_worker -->|"updates club records"| node_mongodb
node_worker -->|"evaluates achievements"| node_achievement
node_worker -->|"runs weekly selection"| node_totw
node_worker -->|"publishes events"| node_rabbit
node_rabbit -->|"dispatches notifications"| node_discord
node_worker -->|"looks up linked accounts"| node_authservice
node_twitchsync -->|"syncs Twitch profile"| node_authservice
node_apiapp -->|"serves averages"| node_averages
node_worker -->|"stores computed averages"| node_mongodb
node_renderer -.->|"consumes render jobs"| node_rabbit

click node_clubweb "https://github.com/eltrueno/truenoproclubservices/tree/main/apps/web/src"
click node_accounts "https://github.com/eltrueno/truenoproclubservices/tree/main/apps/accounts-front/src"
click node_apiapp "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/app.ts"
click node_clubroutes "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/club.ts"
click node_memberroutes "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/members.ts"
click node_adminroutes "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/admin.ts"
click node_memberservice "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/services/clubMember.service.ts"
click node_averages "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/services/averageStats.service.ts"
click node_mongodb "https://github.com/eltrueno/truenoproclubservices/blob/main/packages/shared/src/models/sharedDb.ts"
click node_authservice "https://github.com/eltrueno/truenoproclubservices/tree/main/apps/auth/src"
click node_twitchsync "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/auth/src/services/twitchService.ts"
click node_worker "https://github.com/eltrueno/truenoproclubservices/tree/main/apps/worker/src"
click node_matchdto "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/worker/src/dtos/match.dto.ts"
click node_achievement "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/worker/src/services/achievement.service.ts"
click node_totw "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/worker/src/services/totw.service.ts"
click node_discord "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/discordbot/src/handlers/rabbitmqHandler.js"
click node_renderer "https://github.com/eltrueno/truenoproclubservices/blob/main/apps/imagerenderer/src/services/imageCapture.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_clubweb,node_accounts toneBlue
class node_apiapp,node_clubroutes,node_memberroutes,node_adminroutes,node_memberservice,node_averages,node_mongodb,node_r2 toneAmber
class node_authservice,node_twitchsync,node_eaapi toneMint
class node_worker,node_matchdto,node_achievement,node_totw toneRose
class node_rabbit,node_discord,node_renderer,node_visitor toneIndigo
```

## Components

### Club and account frontends

- [Club website](https://github.com/eltrueno/truenoproclubservices/tree/main/apps/web/src): `apps/web/src`
- [Account portal](https://github.com/eltrueno/truenoproclubservices/tree/main/apps/accounts-front/src): `apps/accounts-front/src`

### Club REST API

- [REST API](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Club routes](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/club.ts): `apps/api/src/routes/club.ts`
- [Member routes](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/members.ts): `apps/api/src/routes/members.ts`
- [Admin routes](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/routes/admin.ts): `apps/api/src/routes/admin.ts`
- [Member services](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/services/clubMember.service.ts): `apps/api/src/services/clubMember.service.ts`
- [Position averages](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/api/src/services/averageStats.service.ts): `apps/api/src/services/averageStats.service.ts`
- [Shared MongoDB models](https://github.com/eltrueno/truenoproclubservices/blob/main/packages/shared/src/models/sharedDb.ts): `packages/shared/src/models/sharedDb.ts`

### Authentication and identity

- [Auth service](https://github.com/eltrueno/truenoproclubservices/tree/main/apps/auth/src): `apps/auth/src`
- [Twitch sync](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/auth/src/services/twitchService.ts): `apps/auth/src/services/twitchService.ts`

### Sync and analytics

- [Sync worker](https://github.com/eltrueno/truenoproclubservices/tree/main/apps/worker/src): `apps/worker/src`
- [Match normalization](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/worker/src/dtos/match.dto.ts): `apps/worker/src/dtos/match.dto.ts`
- [Achievement calculation](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/worker/src/services/achievement.service.ts): `apps/worker/src/services/achievement.service.ts`
- [TOTW job](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/worker/src/services/totw.service.ts): `apps/worker/src/services/totw.service.ts`

### Events and media

- **RabbitMQ events**
- [Discord bot](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/discordbot/src/handlers/rabbitmqHandler.js): `apps/discordbot/src/handlers/rabbitmqHandler.js`
- [Image renderer](https://github.com/eltrueno/truenoproclubservices/blob/main/apps/imagerenderer/src/services/imageCapture.ts): `apps/imagerenderer/src/services/imageCapture.ts`

### Other components

- **Club visitor**
- **EA Pro Clubs API**
- **Cloudflare R2**

## Connections

- Club visitor → Club website: browses
- Club website → REST API: fetches club data
- Club website → Account portal: redirects for login
- Account portal → Auth service: authenticates
- REST API → Club routes: mounts routes (evidence: `apps/api/src/app.ts`)
- REST API → Member routes: mounts routes (evidence: `apps/api/src/app.ts`)
- REST API → Admin routes: mounts routes (evidence: `apps/api/src/app.ts`)
- Club routes → Shared MongoDB models: reads club data (evidence: `apps/api/src/routes/club.ts`)
- Member routes → Shared MongoDB models: serves member data (evidence: `apps/api/src/routes/members.ts`)
- Admin routes → Shared MongoDB models: administers records (evidence: `apps/api/src/routes/admin.ts`)
- Admin routes → Member services: delegates member edits
- Admin routes → Cloudflare R2: uploads player images
- Sync worker → EA Pro Clubs API: fetches new matches
- Sync worker → Match normalization: normalizes matches (evidence: `apps/worker/src/controllers/match.controller.ts`)
- Sync worker → Shared MongoDB models: updates club records
- Sync worker → Achievement calculation: evaluates achievements (evidence: `apps/worker/src/services/totw.service.ts`)
- Sync worker → TOTW job: runs weekly selection (evidence: `apps/worker/src/services/totw.service.ts`)
- Sync worker → RabbitMQ events: publishes events
- RabbitMQ events → Discord bot: dispatches notifications (evidence: `apps/discordbot/src/handlers/rabbitmqHandler.js`)
- Sync worker → Auth service: looks up linked accounts
- Twitch sync → Auth service: syncs Twitch profile (evidence: `apps/auth/src/services/twitchService.ts`)
- REST API → Position averages: serves averages
- Sync worker → Shared MongoDB models: stores computed averages (evidence: `apps/worker/src/services/averageStats.service.ts`)
- Image renderer → RabbitMQ events: consumes render jobs
