# competitivecoder1240/pitwall architecture

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

- Interactive diagram: https://gitdiagram.com/competitivecoder1240/pitwall
- Repository: https://github.com/competitivecoder1240/pitwall

## Overview

PitWall answers F1 regulation, telemetry, and race-strategy questions through a streamed chat workflow: the web client sends a query to the FastAPI service, which orchestrates retrieval/calculation, synthesizes a response, and streams it back. The README documents the main agent stages and cloud capabilities; sampled backend excerpts confirm orchestration, strategy-tool invocation, and database behavior. Retrieval internals and the citation guardrail are represented at the documented level because their implementation details were not fully excerpted.

Main entry points: [`backend/db.py`](https://github.com/competitivecoder1240/pitwall/blob/master/backend/db.py) (Database access), [`backend/api.py`](https://github.com/competitivecoder1240/pitwall/blob/master/backend/api.py) (FastAPI endpoints), [`backend/graph.py`](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py) (StateGraph orchestration), [`frontend-next/hooks/useSSEChat.ts`](https://github.com/competitivecoder1240/pitwall/blob/master/frontend-next/hooks/useSSEChat.ts) (SSE chat hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_webchat["Chat interface<br/>[page.tsx]"]
  node_ssehook["SSE chat hook<br/>[useSSEChat.ts]"]
end

subgraph group_service["API and identity"]
  node_api["FastAPI endpoints<br/>[api.py]"]
  node_identity["Authentication<br/>[auth.py]"]
  node_dbaccess["Database access<br/>[db.py]"]
end

subgraph group_agent["Agent workflow"]
  node_orchestrator["StateGraph orchestration<br/>[graph.py]"]
  node_router["Intent router<br/>[graph.py]"]
  node_strategy["Strategy calculator<br/>[tools.py]"]
  node_models["Hybrid ML models<br/>[tools.py]"]
  node_synthesis["Response synthesis<br/>[graph.py]"]
  node_guardrail["Citation guardrail<br/>[graph.py]"]
end

subgraph group_knowledge["Knowledge and data"]
  node_regulations["Regulation retrieval<br/>[graph.py]"]
  node_hybrid["Hybrid search<br/>[graph.py]"]
  node_knowledgegraph["Regulation graph<br/>[graph.py]"]
  node_telemetryquery["Telemetry queries<br/>[tools.py]"]
  node_telemetrystore[("Telemetry database<br/>[db.py]")]
end

subgraph group_telemetry["Telemetry pipeline"]
  node_telemetryextract["Telemetry extraction"]
  node_modeltraining["Model training"]
end

node_user(("Engineer"))
node_llm{{"Gemini inference"}}
node_vectorstore[("Pinecone")]
node_bm25[("BM25 corpus")]
node_supabase[("Supabase PostgreSQL")]

node_user -->|"asks"| node_webchat
node_webchat -->|"uses"| node_ssehook
node_ssehook -->|"streams query"| node_api
node_api -->|"invokes"| node_orchestrator
node_api -->|"authenticates"| node_identity
node_identity -->|"checks users"| node_dbaccess
node_api -->|"reads/writes sessions"| node_dbaccess
node_orchestrator -->|"dispatches"| node_router
node_router -->|"routes query"| node_regulations
node_router -->|"routes query"| node_telemetryquery
node_router -->|"routes query"| node_strategy
node_regulations -->|"retrieves context"| node_hybrid
node_regulations -->|"traverses graph"| node_knowledgegraph
node_hybrid -->|"semantic search"| node_vectorstore
node_hybrid -->|"keyword search"| node_bm25
node_telemetryquery -->|"queries"| node_dbaccess
node_dbaccess -->|"reads/writes"| node_telemetrystore
node_strategy -->|"loads predictions"| node_models
node_orchestrator -->|"invokes calculator"| node_strategy
node_orchestrator -->|"synthesizes context"| node_synthesis
node_synthesis -->|"generates response"| node_llm
node_synthesis -->|"verifies citations"| node_guardrail
node_guardrail -->|"streams result"| node_ssehook
node_telemetryextract -->|"populates"| node_telemetrystore
node_modeltraining -.->|"trains artifacts"| node_models
node_dbaccess -->|"uses when configured"| node_supabase

click node_webchat "https://github.com/competitivecoder1240/pitwall/blob/master/frontend-next/app/page.tsx"
click node_ssehook "https://github.com/competitivecoder1240/pitwall/blob/master/frontend-next/hooks/useSSEChat.ts"
click node_api "https://github.com/competitivecoder1240/pitwall/blob/master/backend/api.py"
click node_identity "https://github.com/competitivecoder1240/pitwall/blob/master/backend/auth.py"
click node_dbaccess "https://github.com/competitivecoder1240/pitwall/blob/master/backend/db.py"
click node_orchestrator "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_router "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_regulations "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_hybrid "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_knowledgegraph "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_telemetryquery "https://github.com/competitivecoder1240/pitwall/blob/master/backend/tools.py"
click node_strategy "https://github.com/competitivecoder1240/pitwall/blob/master/backend/tools.py"
click node_models "https://github.com/competitivecoder1240/pitwall/blob/master/backend/tools.py"
click node_synthesis "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_guardrail "https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py"
click node_telemetrystore "https://github.com/competitivecoder1240/pitwall/blob/master/backend/db.py"
click node_telemetryextract "https://github.com/competitivecoder1240/pitwall/blob/master/scripts/extract_telemetry.py"
click node_modeltraining "https://github.com/competitivecoder1240/pitwall/blob/master/scripts/train_hybrid_model.py"

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_webchat,node_ssehook toneBlue
class node_api,node_identity,node_dbaccess,node_vectorstore,node_bm25,node_supabase toneAmber
class node_orchestrator,node_router,node_strategy,node_models,node_synthesis,node_guardrail toneMint
class node_regulations,node_hybrid,node_knowledgegraph,node_telemetryquery,node_telemetrystore toneRose
class node_telemetryextract,node_modeltraining,node_user,node_llm toneIndigo
```

## Components

### Chat client

- [Chat interface](https://github.com/competitivecoder1240/pitwall/blob/master/frontend-next/app/page.tsx): `frontend-next/app/page.tsx`
- [SSE chat hook](https://github.com/competitivecoder1240/pitwall/blob/master/frontend-next/hooks/useSSEChat.ts): `frontend-next/hooks/useSSEChat.ts`

### API and identity

- [FastAPI endpoints](https://github.com/competitivecoder1240/pitwall/blob/master/backend/api.py): `backend/api.py`
- [Authentication](https://github.com/competitivecoder1240/pitwall/blob/master/backend/auth.py): `backend/auth.py`
- [Database access](https://github.com/competitivecoder1240/pitwall/blob/master/backend/db.py): `backend/db.py`

### Agent workflow

- [StateGraph orchestration](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`
- [Intent router](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`
- [Strategy calculator](https://github.com/competitivecoder1240/pitwall/blob/master/backend/tools.py): `backend/tools.py`
- [Hybrid ML models](https://github.com/competitivecoder1240/pitwall/blob/master/backend/tools.py): `backend/tools.py`
- [Response synthesis](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`
- [Citation guardrail](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`

### Knowledge and data

- [Regulation retrieval](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`
- [Hybrid search](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`
- [Regulation graph](https://github.com/competitivecoder1240/pitwall/blob/master/backend/graph.py): `backend/graph.py`
- [Telemetry queries](https://github.com/competitivecoder1240/pitwall/blob/master/backend/tools.py): `backend/tools.py`
- [Telemetry database](https://github.com/competitivecoder1240/pitwall/blob/master/backend/db.py): `backend/db.py`

### Telemetry pipeline

- [Telemetry extraction](https://github.com/competitivecoder1240/pitwall/blob/master/scripts/extract_telemetry.py): `scripts/extract_telemetry.py`
- [Model training](https://github.com/competitivecoder1240/pitwall/blob/master/scripts/train_hybrid_model.py): `scripts/train_hybrid_model.py`

### Other components

- **Engineer**
- **Gemini inference**
- **Pinecone**
- **BM25 corpus**
- **Supabase PostgreSQL**

## Connections

- Engineer → Chat interface: asks (evidence: `README.md`)
- Chat interface → SSE chat hook: uses (evidence: `README.md`)
- SSE chat hook → FastAPI endpoints: streams query (evidence: `README.md`)
- FastAPI endpoints → StateGraph orchestration: invokes (evidence: `backend/api.py`)
- FastAPI endpoints → Authentication: authenticates (evidence: `backend/api.py`)
- Authentication → Database access: checks users (evidence: `backend/auth.py`)
- FastAPI endpoints → Database access: reads/writes sessions (evidence: `backend/api.py`)
- StateGraph orchestration → Intent router: dispatches (evidence: `README.md`)
- Intent router → Regulation retrieval: routes query (evidence: `README.md`)
- Intent router → Telemetry queries: routes query (evidence: `README.md`)
- Intent router → Strategy calculator: routes query (evidence: `README.md`)
- Regulation retrieval → Hybrid search: retrieves context (evidence: `README.md`)
- Regulation retrieval → Regulation graph: traverses graph (evidence: `backend/graph.py`)
- Hybrid search → Pinecone: semantic search (evidence: `README.md`)
- Hybrid search → BM25 corpus: keyword search (evidence: `README.md`)
- Telemetry queries → Database access: queries (evidence: `backend/tools.py`)
- Database access → Telemetry database: reads/writes (evidence: `backend/db.py`)
- Strategy calculator → Hybrid ML models: loads predictions (evidence: `backend/tools.py`)
- StateGraph orchestration → Strategy calculator: invokes calculator (evidence: `backend/graph.py`)
- StateGraph orchestration → Response synthesis: synthesizes context (evidence: `README.md`)
- Response synthesis → Gemini inference: generates response (evidence: `README.md`)
- Response synthesis → Citation guardrail: verifies citations (evidence: `README.md`)
- Citation guardrail → SSE chat hook: streams result (evidence: `README.md`)
- Telemetry extraction → Telemetry database: populates (evidence: `scripts/extract_telemetry.py`)
- Model training → Hybrid ML models: trains artifacts
- Database access → Supabase PostgreSQL: uses when configured (evidence: `backend/db.py`)
