# kazes5/soccer architecture

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

- Interactive diagram: https://gitdiagram.com/kazes5/soccer
- Repository: https://github.com/kazes5/soccer

## Overview

Soccer Carpool Coordinator helps youth soccer teams organize rides by scheduling sessions and pickup points, assigning shift responsibilities, coordinating swaps, and notifying members. The web client is the primary interface; the Fastify API handles authentication and team workflows against PostgreSQL, while Redis-backed workers support reminders and notification delivery. The README also identifies shared Zod contracts and design tokens. Several API route families and background subsystems are documented or indexed but not excerpted, so their individual internal call relationships are not asserted.

Main entry points: [`apps/api/src/app.ts`](https://github.com/kazes5/soccer/blob/main/apps/api/src/app.ts) (HTTP API), [`apps/web/src/app`](https://github.com/kazes5/soccer/tree/main/apps/web/src/app) (Web experience), [`apps/api/src/routes/sessions.ts`](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/sessions.ts) (Session scheduling), [`apps/api/src/routes/notifications.ts`](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/notifications.ts) (Notification APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Team client"]
  node_web["Web experience"]
  node_schedule_ui["Schedule and shifts<br/>[page.tsx]"]
  node_home_ui["Team home<br/>[page.tsx]"]
  node_swap_ui["Swap requests<br/>[page.tsx]"]
  node_notification_ui["Notifications<br/>[page.tsx]"]
  node_admin_ui["Team administration"]
  node_system_ui["System administration<br/>[page.tsx]"]
  node_chat_ui["AI chat"]
end

subgraph group_api["API service"]
  node_api_entry["HTTP API<br/>[app.ts]"]
  node_authentication["Authentication<br/>[auth.ts]"]
  node_session_auth["Session validation<br/>[auth.ts]"]
  node_session_workflows["Session scheduling<br/>[sessions.ts]"]
  node_shift_workflows["Shift claims<br/>[shifts.ts]"]
  node_swap_workflows["Swap coordination<br/>[swap-requests.ts]"]
  node_team_members["Teams and members<br/>[teams.ts]"]
  node_invites["Team invitations<br/>[invites.ts]"]
  node_admin_routes["Team settings"]
  node_notifications["Notification APIs<br/>[notifications.ts]"]
  node_chat_api["Chat actions<br/>[chat.ts]"]
  node_audit["Audit records<br/>[audit-logs.ts]"]
  node_system_routes["System operations<br/>[system.ts]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_async["Background delivery"]
  node_redis["Redis queues<br/>[queues.ts]"]
  node_worker["Job worker<br/>[index.ts]"]
  node_scheduled_tasks["Scheduled tasks<br/>[scheduled-task.ts]"]
  node_outbox_worker["Notification outbox<br/>[outbox.ts]"]
  node_push_delivery["Push delivery<br/>[push-delivery.ts]"]
end

subgraph group_shared["Shared packages"]
  node_contracts["Shared contracts"]
  node_tokens["Design tokens"]
  node_mobile_locale["Mobile locale support<br/>[locale-storage.ts]"]
end

node_member(("Team member"))

node_member -->|"uses"| node_web
node_web -.->|"calls"| node_api_entry
node_api_entry -->|"registers"| node_session_auth
node_api_entry -->|"registers"| node_authentication
node_api_entry -->|"registers"| node_session_workflows
node_api_entry -->|"registers"| node_shift_workflows
node_api_entry -->|"registers"| node_swap_workflows
node_api_entry -->|"registers"| node_team_members
node_api_entry -->|"registers"| node_invites
node_api_entry -->|"registers"| node_notifications
node_api_entry -->|"registers"| node_chat_api
node_api_entry -->|"registers"| node_system_routes
node_api_entry -->|"registers"| node_admin_routes
node_session_workflows -->|"reads and writes"| node_postgres
node_session_workflows -->|"records events"| node_notifications
node_session_workflows -.->|"schedules reminders"| node_redis
node_session_auth -->|"validates sessions"| node_postgres
node_authentication -->|"manages credentials"| node_postgres
node_admin_routes -.->|"manages settings"| node_postgres
node_notifications -.->|"reads notifications"| node_postgres
node_chat_api -.->|"uses team data"| node_postgres
node_chat_api -.->|"dispatches actions"| node_notifications
node_worker -.->|"runs processors"| node_scheduled_tasks
node_worker -.->|"runs processors"| node_outbox_worker
node_scheduled_tasks -.->|"consumes jobs"| node_redis
node_outbox_worker -.->|"consumes jobs"| node_redis
node_outbox_worker -.->|"delivers pushes"| node_push_delivery
node_push_delivery -.->|"sends notifications"| node_member
node_schedule_ui -.->|"requests schedules"| node_api_entry
node_home_ui -.->|"loads team overview"| node_api_entry
node_swap_ui -.->|"requests swaps"| node_api_entry
node_notification_ui -.->|"loads notifications"| node_api_entry
node_admin_ui -.->|"manages team"| node_api_entry
node_system_ui -.->|"manages system"| node_api_entry
node_chat_ui -.->|"sends chat"| node_api_entry
node_web -.->|"shares types"| node_contracts
node_api_entry -.->|"validates payloads"| node_contracts
node_web -.->|"uses styles"| node_tokens
node_mobile_locale -.->|"persists locale"| node_member

click node_web "https://github.com/kazes5/soccer/tree/main/apps/web/src/app"
click node_schedule_ui "https://github.com/kazes5/soccer/blob/main/apps/web/src/app/schedule/page.tsx"
click node_home_ui "https://github.com/kazes5/soccer/blob/main/apps/web/src/app/home/page.tsx"
click node_swap_ui "https://github.com/kazes5/soccer/blob/main/apps/web/src/app/swaps/page.tsx"
click node_notification_ui "https://github.com/kazes5/soccer/blob/main/apps/web/src/app/notifications/page.tsx"
click node_admin_ui "https://github.com/kazes5/soccer/tree/main/apps/web/src/app/admin"
click node_system_ui "https://github.com/kazes5/soccer/blob/main/apps/web/src/app/system/page.tsx"
click node_chat_ui "https://github.com/kazes5/soccer/tree/main/apps/web/src/components/chat"
click node_api_entry "https://github.com/kazes5/soccer/blob/main/apps/api/src/app.ts"
click node_authentication "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/auth.ts"
click node_session_auth "https://github.com/kazes5/soccer/blob/main/apps/api/src/plugins/auth.ts"
click node_session_workflows "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/sessions.ts"
click node_shift_workflows "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/shifts.ts"
click node_swap_workflows "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/swap-requests.ts"
click node_team_members "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/teams.ts"
click node_invites "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/invites.ts"
click node_admin_routes "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/schedule-templates.ts"
click node_notifications "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/notifications.ts"
click node_chat_api "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/chat.ts"
click node_audit "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/audit-logs.ts"
click node_system_routes "https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/system.ts"
click node_redis "https://github.com/kazes5/soccer/blob/main/apps/api/src/lib/queues.ts"
click node_worker "https://github.com/kazes5/soccer/blob/main/apps/api/src/worker/index.ts"
click node_scheduled_tasks "https://github.com/kazes5/soccer/blob/main/apps/api/src/worker/processors/scheduled-task.ts"
click node_outbox_worker "https://github.com/kazes5/soccer/blob/main/apps/api/src/worker/processors/outbox.ts"
click node_push_delivery "https://github.com/kazes5/soccer/blob/main/apps/api/src/lib/push-delivery.ts"
click node_contracts "https://github.com/kazes5/soccer/tree/main/packages/contracts/src"
click node_tokens "https://github.com/kazes5/soccer/tree/main/packages/ui-tokens/src"
click node_mobile_locale "https://github.com/kazes5/soccer/blob/main/apps/mobile/src/lib/locale-storage.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_web,node_schedule_ui,node_home_ui,node_swap_ui,node_notification_ui,node_admin_ui,node_system_ui,node_chat_ui toneBlue
class node_api_entry,node_authentication,node_session_auth,node_session_workflows,node_shift_workflows,node_swap_workflows,node_team_members,node_invites,node_admin_routes,node_notifications,node_chat_api,node_audit,node_system_routes,node_postgres toneAmber
class node_redis,node_worker,node_scheduled_tasks,node_outbox_worker,node_push_delivery toneMint
class node_contracts,node_tokens,node_mobile_locale toneRose
class node_member toneIndigo
```

## Components

### Team client

- [Web experience](https://github.com/kazes5/soccer/tree/main/apps/web/src/app): `apps/web/src/app`
- [Schedule and shifts](https://github.com/kazes5/soccer/blob/main/apps/web/src/app/schedule/page.tsx): `apps/web/src/app/schedule/page.tsx`
- [Team home](https://github.com/kazes5/soccer/blob/main/apps/web/src/app/home/page.tsx): `apps/web/src/app/home/page.tsx`
- [Swap requests](https://github.com/kazes5/soccer/blob/main/apps/web/src/app/swaps/page.tsx): `apps/web/src/app/swaps/page.tsx`
- [Notifications](https://github.com/kazes5/soccer/blob/main/apps/web/src/app/notifications/page.tsx): `apps/web/src/app/notifications/page.tsx`
- [Team administration](https://github.com/kazes5/soccer/tree/main/apps/web/src/app/admin): `apps/web/src/app/admin`
- [System administration](https://github.com/kazes5/soccer/blob/main/apps/web/src/app/system/page.tsx): `apps/web/src/app/system/page.tsx`
- [AI chat](https://github.com/kazes5/soccer/tree/main/apps/web/src/components/chat): `apps/web/src/components/chat`

### API service

- [HTTP API](https://github.com/kazes5/soccer/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Session validation](https://github.com/kazes5/soccer/blob/main/apps/api/src/plugins/auth.ts): `apps/api/src/plugins/auth.ts`
- [Session scheduling](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/sessions.ts): `apps/api/src/routes/sessions.ts`
- [Shift claims](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/shifts.ts): `apps/api/src/routes/shifts.ts`
- [Swap coordination](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/swap-requests.ts): `apps/api/src/routes/swap-requests.ts`
- [Teams and members](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/teams.ts): `apps/api/src/routes/teams.ts`
- [Team invitations](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/invites.ts): `apps/api/src/routes/invites.ts`
- [Team settings](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/schedule-templates.ts): `apps/api/src/routes/schedule-templates.ts`
- [Notification APIs](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/notifications.ts): `apps/api/src/routes/notifications.ts`
- [Chat actions](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/chat.ts): `apps/api/src/routes/chat.ts`
- [Audit records](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/audit-logs.ts): `apps/api/src/routes/audit-logs.ts`
- [System operations](https://github.com/kazes5/soccer/blob/main/apps/api/src/routes/system.ts): `apps/api/src/routes/system.ts`
- **PostgreSQL**

### Background delivery

- [Redis queues](https://github.com/kazes5/soccer/blob/main/apps/api/src/lib/queues.ts): `apps/api/src/lib/queues.ts`
- [Job worker](https://github.com/kazes5/soccer/blob/main/apps/api/src/worker/index.ts): `apps/api/src/worker/index.ts`
- [Scheduled tasks](https://github.com/kazes5/soccer/blob/main/apps/api/src/worker/processors/scheduled-task.ts): `apps/api/src/worker/processors/scheduled-task.ts`
- [Notification outbox](https://github.com/kazes5/soccer/blob/main/apps/api/src/worker/processors/outbox.ts): `apps/api/src/worker/processors/outbox.ts`
- [Push delivery](https://github.com/kazes5/soccer/blob/main/apps/api/src/lib/push-delivery.ts): `apps/api/src/lib/push-delivery.ts`

### Shared packages

- [Shared contracts](https://github.com/kazes5/soccer/tree/main/packages/contracts/src): `packages/contracts/src`
- [Design tokens](https://github.com/kazes5/soccer/tree/main/packages/ui-tokens/src): `packages/ui-tokens/src`
- [Mobile locale support](https://github.com/kazes5/soccer/blob/main/apps/mobile/src/lib/locale-storage.ts): `apps/mobile/src/lib/locale-storage.ts`

### Other components

- **Team member**

## Connections

- Team member → Web experience: uses (evidence: `README.md`)
- Web experience → HTTP API: calls
- HTTP API → Session validation: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Authentication: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Session scheduling: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Shift claims: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Swap coordination: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Teams and members: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Team invitations: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Notification APIs: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Chat actions: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → System operations: registers (evidence: `apps/api/src/app.ts`)
- HTTP API → Team settings: registers (evidence: `apps/api/src/app.ts`)
- Session scheduling → PostgreSQL: reads and writes (evidence: `apps/api/src/routes/sessions.ts`)
- Session scheduling → Notification APIs: records events (evidence: `apps/api/src/routes/sessions.ts`)
- Session scheduling → Redis queues: schedules reminders (evidence: `apps/api/src/routes/sessions.ts`)
- Session validation → PostgreSQL: validates sessions (evidence: `apps/api/src/plugins/auth.ts`)
- Authentication → PostgreSQL: manages credentials (evidence: `apps/api/src/routes/auth.ts`)
- Team settings → PostgreSQL: manages settings
- Notification APIs → PostgreSQL: reads notifications
- Chat actions → PostgreSQL: uses team data
- Chat actions → Notification APIs: dispatches actions
- Job worker → Scheduled tasks: runs processors
- Job worker → Notification outbox: runs processors
- Scheduled tasks → Redis queues: consumes jobs
- Notification outbox → Redis queues: consumes jobs
- Notification outbox → Push delivery: delivers pushes
- Push delivery → Team member: sends notifications
- Schedule and shifts → HTTP API: requests schedules
- Team home → HTTP API: loads team overview
- Swap requests → HTTP API: requests swaps
- Notifications → HTTP API: loads notifications
- Team administration → HTTP API: manages team
- System administration → HTTP API: manages system
- AI chat → HTTP API: sends chat
- Web experience → Shared contracts: shares types
- HTTP API → Shared contracts: validates payloads
- Web experience → Design tokens: uses styles
- Mobile locale support → Team member: persists locale
