# iampawan/pitchtank architecture

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

- Interactive diagram: https://gitdiagram.com/iampawan/pitchtank
- Repository: https://github.com/iampawan/pitchtank

## Overview

Pitch Tank is a browser-based startup-pitch and fictional investment simulation. A founder chooses live voice or the explicitly scripted preview, pitches for 60 seconds, answers investor questions, negotiates offers and counteroffers, then accepts a deal or ends the session. The Next.js experience presents the studio and sends actions through its session hook to FastAPI, which owns turn deadlines, validation and deal state. Live voice uses Agora; checkpoints and usage limits can persist through the deployment’s durable storage. Source excerpts are partial, so uncertain internal routing is omitted.

Main entry points: [`server/main.py`](https://github.com/iampawan/pitchtank/blob/main/server/main.py) (FastAPI session API), [`web/app/page.tsx`](https://github.com/iampawan/pitchtank/blob/main/web/app/page.tsx) (Studio interface), [`web/lib/useTank.ts`](https://github.com/iampawan/pitchtank/blob/main/web/lib/useTank.ts) (Session controller), [`server/agora_adapter.py`](https://github.com/iampawan/pitchtank/blob/main/server/agora_adapter.py) (Agora adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Studio experience"]
  node_page["Studio interface<br/>[page.tsx]"]
  node_stage["Investor stage<br/>[Stage.tsx]"]
  node_investors["Investor characters<br/>[Investor.tsx]"]
  node_proposal["Proposal form<br/>[ProposalForm.tsx]"]
  node_share["Sharing<br/>[sharing.ts]"]
  node_hook["Session controller<br/>[useTank.ts]"]
  node_api_client["API client<br/>[tank.ts]"]
  node_session_state["Snapshot utilities<br/>[session-state.ts]"]
end

subgraph group_game["Session and game"]
  node_fastapi["FastAPI session API<br/>[main.py]"]
  node_studio_api["Studio routes<br/>[studio_api.py]"]
  node_game_model["Game rules<br/>[session_model.py]"]
  node_moderator["Conversation moderation<br/>[moderator.py]"]
  node_limits["Usage limits<br/>[limits.py]"]
end

subgraph group_voice["Voice integration"]
  node_voice_client["Voice connection<br/>[voice.ts]"]
  node_agora_adapter["Agora adapter<br/>[agora_adapter.py]"]
end

subgraph group_persistence["Persistence and deployment"]
  node_store[("Session store<br/>[storage.py]")]
  node_worker["Cloudflare gateway<br/>[worker.ts]"]
  node_checkpoints[("Durable checkpoints<br/>[worker.ts]")]
end

node_founder(("Founder"))
node_agora{{"Agora voice services"}}

node_founder -->|"uses studio"| node_page
node_page -->|"renders scene"| node_stage
node_stage -->|"renders panel"| node_investors
node_page -->|"presents terms"| node_proposal
node_page -->|"starts actions"| node_hook
node_hook -->|"sends requests"| node_api_client
node_hook -->|"controls voice"| node_voice_client
node_hook -->|"checks revisions"| node_session_state
node_api_client -->|"calls API"| node_fastapi
node_fastapi -->|"includes routes"| node_studio_api
node_fastapi -->|"applies actions"| node_game_model
node_fastapi -->|"controls agents"| node_agora_adapter
node_agora_adapter -.->|"uses moderation"| node_moderator
node_agora_adapter -->|"connects agents"| node_agora
node_voice_client -->|"connects browser"| node_agora
node_fastapi -->|"saves checkpoints"| node_store
node_fastapi -->|"checks quotas"| node_limits
node_store -.->|"requests remote state"| node_worker
node_worker -->|"routes state"| node_checkpoints
node_worker -->|"forwards requests"| node_fastapi
node_founder -->|"shares app link"| node_share

click node_page "https://github.com/iampawan/pitchtank/blob/main/web/app/page.tsx"
click node_stage "https://github.com/iampawan/pitchtank/blob/main/web/components/Stage.tsx"
click node_investors "https://github.com/iampawan/pitchtank/blob/main/web/components/Investor.tsx"
click node_proposal "https://github.com/iampawan/pitchtank/blob/main/web/components/ProposalForm.tsx"
click node_share "https://github.com/iampawan/pitchtank/blob/main/web/lib/sharing.ts"
click node_hook "https://github.com/iampawan/pitchtank/blob/main/web/lib/useTank.ts"
click node_api_client "https://github.com/iampawan/pitchtank/blob/main/web/lib/tank.ts"
click node_session_state "https://github.com/iampawan/pitchtank/blob/main/web/lib/session-state.ts"
click node_fastapi "https://github.com/iampawan/pitchtank/blob/main/server/main.py"
click node_studio_api "https://github.com/iampawan/pitchtank/blob/main/server/studio_api.py"
click node_game_model "https://github.com/iampawan/pitchtank/blob/main/server/session_model.py"
click node_moderator "https://github.com/iampawan/pitchtank/blob/main/server/moderator.py"
click node_limits "https://github.com/iampawan/pitchtank/blob/main/server/limits.py"
click node_voice_client "https://github.com/iampawan/pitchtank/blob/main/web/lib/voice.ts"
click node_agora_adapter "https://github.com/iampawan/pitchtank/blob/main/server/agora_adapter.py"
click node_store "https://github.com/iampawan/pitchtank/blob/main/server/storage.py"
click node_worker "https://github.com/iampawan/pitchtank/blob/main/deployment/cloudflare/worker.ts"
click node_checkpoints "https://github.com/iampawan/pitchtank/blob/main/deployment/cloudflare/worker.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_page,node_stage,node_investors,node_proposal,node_share,node_hook,node_api_client,node_session_state toneBlue
class node_fastapi,node_studio_api,node_game_model,node_moderator,node_limits toneAmber
class node_voice_client,node_agora_adapter toneMint
class node_store,node_worker,node_checkpoints toneRose
class node_founder,node_agora toneIndigo
```

## Components

### Studio experience

- [Studio interface](https://github.com/iampawan/pitchtank/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Investor stage](https://github.com/iampawan/pitchtank/blob/main/web/components/Stage.tsx): `web/components/Stage.tsx`
- [Investor characters](https://github.com/iampawan/pitchtank/blob/main/web/components/Investor.tsx): `web/components/Investor.tsx`
- [Proposal form](https://github.com/iampawan/pitchtank/blob/main/web/components/ProposalForm.tsx): `web/components/ProposalForm.tsx`
- [Sharing](https://github.com/iampawan/pitchtank/blob/main/web/lib/sharing.ts): `web/lib/sharing.ts`
- [Session controller](https://github.com/iampawan/pitchtank/blob/main/web/lib/useTank.ts): `web/lib/useTank.ts`
- [API client](https://github.com/iampawan/pitchtank/blob/main/web/lib/tank.ts): `web/lib/tank.ts`
- [Snapshot utilities](https://github.com/iampawan/pitchtank/blob/main/web/lib/session-state.ts): `web/lib/session-state.ts`

### Session and game

- [FastAPI session API](https://github.com/iampawan/pitchtank/blob/main/server/main.py): `server/main.py`
- [Studio routes](https://github.com/iampawan/pitchtank/blob/main/server/studio_api.py): `server/studio_api.py`
- [Game rules](https://github.com/iampawan/pitchtank/blob/main/server/session_model.py): `server/session_model.py`
- [Conversation moderation](https://github.com/iampawan/pitchtank/blob/main/server/moderator.py): `server/moderator.py`
- [Usage limits](https://github.com/iampawan/pitchtank/blob/main/server/limits.py): `server/limits.py`

### Voice integration

- [Voice connection](https://github.com/iampawan/pitchtank/blob/main/web/lib/voice.ts): `web/lib/voice.ts`
- [Agora adapter](https://github.com/iampawan/pitchtank/blob/main/server/agora_adapter.py): `server/agora_adapter.py`

### Persistence and deployment

- [Session store](https://github.com/iampawan/pitchtank/blob/main/server/storage.py): `server/storage.py`
- [Cloudflare gateway](https://github.com/iampawan/pitchtank/blob/main/deployment/cloudflare/worker.ts): `deployment/cloudflare/worker.ts`
- [Durable checkpoints](https://github.com/iampawan/pitchtank/blob/main/deployment/cloudflare/worker.ts): `deployment/cloudflare/worker.ts`

### Other components

- **Founder**
- **Agora voice services**

## Connections

- Founder → Studio interface: uses studio
- Studio interface → Investor stage: renders scene
- Investor stage → Investor characters: renders panel
- Studio interface → Proposal form: presents terms
- Studio interface → Session controller: starts actions
- Session controller → API client: sends requests
- Session controller → Voice connection: controls voice
- Session controller → Snapshot utilities: checks revisions
- API client → FastAPI session API: calls API
- FastAPI session API → Studio routes: includes routes
- FastAPI session API → Game rules: applies actions
- FastAPI session API → Agora adapter: controls agents
- Agora adapter → Conversation moderation: uses moderation
- Agora adapter → Agora voice services: connects agents
- Voice connection → Agora voice services: connects browser
- FastAPI session API → Session store: saves checkpoints
- FastAPI session API → Usage limits: checks quotas
- Session store → Cloudflare gateway: requests remote state
- Cloudflare gateway → Durable checkpoints: routes state
- Cloudflare gateway → FastAPI session API: forwards requests
- Founder → Sharing: shares app link