# benildavid/knockout architecture

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

- Interactive diagram: https://gitdiagram.com/benildavid/knockout
- Repository: https://github.com/benildavid/knockout

## Overview

Knockout is a self-hosted tournament-management application with accounts, event operations, and a virtual-points prediction competition. Participants and staff use the web app to register and manage entrants, generate and operate brackets, submit or approve results, and—separately—place predictions and settle outcomes. The API routes these workflows through identity, community/event, tournament, and prediction logic to persistent state. README documents additional account security, team, scheduling, reporting, and deployment capabilities; those are represented where their owning source is identifiable. Edges reflect shown calls or documented behavior; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`apps/api/src/storage.ts`](https://github.com/benildavid/knockout/blob/main/apps/api/src/storage.ts) (State repository), [`apps/web/src/components/Bracket.tsx`](https://github.com/benildavid/knockout/blob/main/apps/web/src/components/Bracket.tsx) (Bracket view), [`apps/api/src/community.ts`](https://github.com/benildavid/knockout/blob/main/apps/api/src/community.ts) (Membership and operations), [`apps/api/src/tournaments.ts`](https://github.com/benildavid/knockout/blob/main/apps/api/src/tournaments.ts) (Tournament engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Tournament workspace<br/>[App.tsx]"]
  node_predictionui["Prediction workspace<br/>[Phase2.tsx]"]
  node_webclient["API client<br/>[api.ts]"]
  node_bracketview["Bracket view<br/>[Bracket.tsx]"]
  node_bracketmotion["Animated bracket"]
  node_bracketwheel["Bracket wheel<br/>[knockout-wheel.tsx]"]
  node_tooltip["Tooltip positioning<br/>[use-position.ts]"]
end

subgraph group_api["API and domain"]
  node_apiroutes["HTTP and event routes<br/>[app.ts]"]
  node_identity["Accounts and access<br/>[identity.ts]"]
  node_community["Membership and operations<br/>[community.ts]"]
  node_tournaments["Tournament engine<br/>[tournaments.ts]"]
  node_predictions["Prediction ledger logic<br/>[predictions.ts]"]
end

subgraph group_state["Persistence and contracts"]
  node_contracts["Shared domain contracts<br/>[index.ts]"]
  node_phasetypes["Account and ledger types<br/>[phase-types.ts]"]
  node_repository["State repository<br/>[storage.ts]"]
end

subgraph group_services["External services"]
  node_postgres[("PostgreSQL")]
  node_localfile["Local JSON state"]
  node_email["SMTP email"]
  node_bracketsengine["brackets-manager"]
end

node_participant(("Participants and staff"))

node_participant -->|"uses"| node_webapp
node_webapp -.->|"requests API"| node_webclient
node_predictionui -.->|"requests API"| node_webclient
node_webapp -->|"renders"| node_bracketview
node_predictionui -->|"renders"| node_bracketview
node_bracketview -->|"renders"| node_bracketmotion
node_bracketview -->|"loads"| node_bracketwheel
node_bracketview -.->|"positions tooltips"| node_tooltip
node_apiroutes -->|"installs"| node_identity
node_apiroutes -->|"installs"| node_community
node_apiroutes -->|"mutates as"| node_community
node_apiroutes -->|"reads and writes"| node_repository
node_apiroutes -->|"uses"| node_tournaments
node_identity -.->|"persists accounts"| node_repository
node_community -->|"checks permissions"| node_identity
node_community -.->|"writes state"| node_repository
node_community -->|"uses tournament rules"| node_tournaments
node_community -.->|"coordinates outcomes"| node_predictions
node_tournaments -->|"uses engine storage"| node_repository
node_tournaments -->|"manages brackets"| node_bracketsengine
node_predictions -->|"updates ledger"| node_repository
node_predictions -->|"reads match state"| node_tournaments
node_repository -.->|"stores state"| node_postgres
node_repository -->|"stores state"| node_localfile
node_repository -->|"uses state types"| node_phasetypes
node_webapp -->|"uses shared types"| node_contracts
node_predictionui -->|"uses shared types"| node_contracts
node_bracketview -->|"uses match types"| node_contracts
node_tournaments -->|"uses domain types"| node_contracts
node_identity -->|"projects public user"| node_phasetypes
node_identity -.->|"sends verification mail"| node_email

click node_webapp "https://github.com/benildavid/knockout/blob/main/apps/web/src/App.tsx"
click node_predictionui "https://github.com/benildavid/knockout/blob/main/apps/web/src/Phase2.tsx"
click node_webclient "https://github.com/benildavid/knockout/blob/main/apps/web/src/api.ts"
click node_bracketview "https://github.com/benildavid/knockout/blob/main/apps/web/src/components/Bracket.tsx"
click node_bracketmotion "https://github.com/benildavid/knockout/blob/main/apps/web/src/components/motion/knockout-bracket.tsx"
click node_bracketwheel "https://github.com/benildavid/knockout/blob/main/apps/web/src/components/motion/knockout-wheel.tsx"
click node_tooltip "https://github.com/benildavid/knockout/blob/main/apps/web/src/components/motion/tooltip/use-position.ts"
click node_contracts "https://github.com/benildavid/knockout/blob/main/packages/contracts/src/index.ts"
click node_apiroutes "https://github.com/benildavid/knockout/blob/main/apps/api/src/app.ts"
click node_identity "https://github.com/benildavid/knockout/blob/main/apps/api/src/identity.ts"
click node_community "https://github.com/benildavid/knockout/blob/main/apps/api/src/community.ts"
click node_tournaments "https://github.com/benildavid/knockout/blob/main/apps/api/src/tournaments.ts"
click node_predictions "https://github.com/benildavid/knockout/blob/main/apps/api/src/predictions.ts"
click node_phasetypes "https://github.com/benildavid/knockout/blob/main/apps/api/src/phase-types.ts"
click node_repository "https://github.com/benildavid/knockout/blob/main/apps/api/src/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_webapp,node_predictionui,node_webclient,node_bracketview,node_bracketmotion,node_bracketwheel,node_tooltip toneBlue
class node_apiroutes,node_identity,node_community,node_tournaments,node_predictions toneAmber
class node_contracts,node_phasetypes,node_repository toneMint
class node_postgres,node_localfile,node_email,node_bracketsengine toneRose
class node_participant toneIndigo
```

## Components

### Web application

- [Tournament workspace](https://github.com/benildavid/knockout/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Prediction workspace](https://github.com/benildavid/knockout/blob/main/apps/web/src/Phase2.tsx): `apps/web/src/Phase2.tsx`
- [API client](https://github.com/benildavid/knockout/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Bracket view](https://github.com/benildavid/knockout/blob/main/apps/web/src/components/Bracket.tsx): `apps/web/src/components/Bracket.tsx`
- [Animated bracket](https://github.com/benildavid/knockout/blob/main/apps/web/src/components/motion/knockout-bracket.tsx): `apps/web/src/components/motion/knockout-bracket.tsx`
- [Bracket wheel](https://github.com/benildavid/knockout/blob/main/apps/web/src/components/motion/knockout-wheel.tsx): `apps/web/src/components/motion/knockout-wheel.tsx`
- [Tooltip positioning](https://github.com/benildavid/knockout/blob/main/apps/web/src/components/motion/tooltip/use-position.ts): `apps/web/src/components/motion/tooltip/use-position.ts`

### API and domain

- [HTTP and event routes](https://github.com/benildavid/knockout/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Accounts and access](https://github.com/benildavid/knockout/blob/main/apps/api/src/identity.ts): `apps/api/src/identity.ts`
- [Membership and operations](https://github.com/benildavid/knockout/blob/main/apps/api/src/community.ts): `apps/api/src/community.ts`
- [Tournament engine](https://github.com/benildavid/knockout/blob/main/apps/api/src/tournaments.ts): `apps/api/src/tournaments.ts`
- [Prediction ledger logic](https://github.com/benildavid/knockout/blob/main/apps/api/src/predictions.ts): `apps/api/src/predictions.ts`

### Persistence and contracts

- [Shared domain contracts](https://github.com/benildavid/knockout/blob/main/packages/contracts/src/index.ts): `packages/contracts/src/index.ts`
- [Account and ledger types](https://github.com/benildavid/knockout/blob/main/apps/api/src/phase-types.ts): `apps/api/src/phase-types.ts`
- [State repository](https://github.com/benildavid/knockout/blob/main/apps/api/src/storage.ts): `apps/api/src/storage.ts`

### External services

- **PostgreSQL**
- **Local JSON state**
- **SMTP email**
- **brackets-manager**

### Other components

- **Participants and staff**

## Connections

- Participants and staff → Tournament workspace: uses (evidence: `README.md`)
- Tournament workspace → API client: requests API (evidence: `apps/web/src/App.tsx`)
- Prediction workspace → API client: requests API (evidence: `apps/web/src/Phase2.tsx`)
- Tournament workspace → Bracket view: renders (evidence: `apps/web/src/App.tsx`)
- Prediction workspace → Bracket view: renders (evidence: `apps/web/src/Phase2.tsx`)
- Bracket view → Animated bracket: renders (evidence: `apps/web/src/components/Bracket.tsx`)
- Bracket view → Bracket wheel: loads (evidence: `apps/web/src/components/Bracket.tsx`)
- Bracket view → Tooltip positioning: positions tooltips
- HTTP and event routes → Accounts and access: installs (evidence: `apps/api/src/app.ts`)
- HTTP and event routes → Membership and operations: installs (evidence: `apps/api/src/app.ts`)
- HTTP and event routes → Membership and operations: mutates as (evidence: `apps/api/src/app.ts`)
- HTTP and event routes → State repository: reads and writes (evidence: `apps/api/src/app.ts`)
- HTTP and event routes → Tournament engine: uses (evidence: `apps/api/src/app.ts`)
- Accounts and access → State repository: persists accounts (evidence: `apps/api/src/identity.ts`)
- Membership and operations → Accounts and access: checks permissions (evidence: `apps/api/src/community.ts`)
- Membership and operations → State repository: writes state (evidence: `apps/api/src/community.ts`)
- Membership and operations → Tournament engine: uses tournament rules (evidence: `apps/api/src/community.ts`)
- Membership and operations → Prediction ledger logic: coordinates outcomes (evidence: `apps/api/src/community.ts`)
- Tournament engine → State repository: uses engine storage (evidence: `apps/api/src/tournaments.ts`)
- Tournament engine → brackets-manager: manages brackets (evidence: `apps/api/src/tournaments.ts`)
- Prediction ledger logic → State repository: updates ledger (evidence: `apps/api/src/predictions.ts`)
- Prediction ledger logic → Tournament engine: reads match state (evidence: `apps/api/src/predictions.ts`)
- State repository → PostgreSQL: stores state
- State repository → Local JSON state: stores state (evidence: `apps/api/src/storage.ts`)
- State repository → Account and ledger types: uses state types (evidence: `apps/api/src/storage.ts`)
- Tournament workspace → Shared domain contracts: uses shared types (evidence: `apps/web/src/App.tsx`)
- Prediction workspace → Shared domain contracts: uses shared types (evidence: `apps/web/src/Phase2.tsx`)
- Bracket view → Shared domain contracts: uses match types (evidence: `apps/web/src/components/Bracket.tsx`)
- Tournament engine → Shared domain contracts: uses domain types (evidence: `apps/api/src/tournaments.ts`)
- Accounts and access → Account and ledger types: projects public user (evidence: `apps/api/src/identity.ts`)
- Accounts and access → SMTP email: sends verification mail
