# jassv9/apex-forge-paddock architecture

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

- Interactive diagram: https://gitdiagram.com/jassv9/apex-forge-paddock
- Repository: https://github.com/jassv9/apex-forge-paddock
- Video tour (about a minute): https://gitdiagram.com/jassv9/apex-forge-paddock/video

## Overview

Paddock is a local-first vehicle-engineering platform: capture corner-pass data, ingest it, measure vehicle behavior, and present recorded sessions. The implemented workflow covers capture/ingest and measurement; experiments, diagnosis, sensitivity learning, and the optional Ghost Driver are documented future capabilities, not implemented components in this tree. Relationships among Go, Python, and the UI are shown only where the excerpts, SOURCE INDEX, or README support them; the capture agent and storage formats are documented but their implementation files are absent from the supplied tree.

Main entry points: [`engine/paddock_engine/features/session.py`](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/features/session.py) (Session features), [`core/internal/ingest`](https://github.com/jassv9/apex-forge-paddock/tree/main/core/internal/ingest) (Spool ingest), [`core/cmd/paddock/main.go`](https://github.com/jassv9/apex-forge-paddock/blob/main/core/cmd/paddock/main.go) (Core process), [`web/src/api/client.ts`](https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and ingest"]
  node_spool["Spool files"]
  node_ingest["Spool ingest"]
  node_parquet[("Raw samples")]
end

subgraph group_core["Core service"]
  node_coreapp["Core process<br/>[main.go]"]
  node_api["REST API"]
  node_sessionstore["Session reader<br/>[sessions.go]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_engine["Analysis engine"]
  node_engineapi["Engine HTTP API<br/>[app.py]"]
  node_sessionfeatures["Session features<br/>[session.py]"]
  node_passfeatures["Pass features<br/>[pass_features.py]"]
  node_samples["Parquet samples<br/>[samples.py]"]
  node_phases["Corner phases<br/>[segment.py]"]
  node_featuremodules["Feature calculations"]
  node_stats["Effect statistics<br/>[effects.py]"]
  node_statmodel["Mixed model<br/>[model.py]"]
end

subgraph group_web["Dashboard"]
  node_webapp["Dashboard app<br/>[App.tsx]"]
  node_sessionlist["Session list<br/>[SessionList.tsx]"]
  node_status["Core status<br/>[CoreStatus.tsx]"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_planned["Planned capabilities"]
  node_experiments["Experiments and verdicts"]
  node_diagnosis["Diagnosis"]
  node_sensitivity["Sensitivity profile"]
  node_ghost["Ghost Driver"]
end

node_driver(("Game capture"))

node_driver -->|"writes passes"| node_spool
node_spool -->|"tails files"| node_ingest
node_coreapp -->|"starts"| node_ingest
node_ingest -->|"writes passes"| node_postgres
node_ingest -->|"writes samples"| node_parquet
node_coreapp -->|"serves"| node_api
node_coreapp -->|"configures"| node_sessionstore
node_sessionstore -->|"reads sessions"| node_postgres
node_webapp -->|"renders"| node_sessionlist
node_webapp -->|"renders"| node_status
node_sessionlist -->|"fetches sessions"| node_client
node_status -->|"checks health"| node_client
node_client -->|"requests REST"| node_api
node_engineapi -->|"dispatches features"| node_sessionfeatures
node_sessionfeatures -->|"reads samples"| node_samples
node_sessionfeatures -->|"computes passes"| node_passfeatures
node_sessionfeatures -->|"uses corners"| node_phases
node_passfeatures -->|"uses calculations"| node_featuremodules
node_phases -->|"segments samples"| node_samples
node_stats -->|"fits model"| node_statmodel
node_stats -->|"reads samples"| node_samples
node_experiments -.->|"informs"| node_diagnosis
node_diagnosis -.->|"feeds learning"| node_sensitivity
node_experiments -.->|"requests analysis"| node_engineapi
node_ghost -.->|"may support"| node_experiments

click node_ingest "https://github.com/jassv9/apex-forge-paddock/tree/main/core/internal/ingest"
click node_coreapp "https://github.com/jassv9/apex-forge-paddock/blob/main/core/cmd/paddock/main.go"
click node_api "https://github.com/jassv9/apex-forge-paddock/tree/main/core/internal/api"
click node_sessionstore "https://github.com/jassv9/apex-forge-paddock/blob/main/core/internal/store/sessions.go"
click node_webapp "https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/App.tsx"
click node_sessionlist "https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/components/SessionList.tsx"
click node_status "https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/components/CoreStatus.tsx"
click node_client "https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/api/client.ts"
click node_engineapi "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/app.py"
click node_sessionfeatures "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/features/session.py"
click node_passfeatures "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/features/pass_features.py"
click node_samples "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/io/samples.py"
click node_phases "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/phases/segment.py"
click node_featuremodules "https://github.com/jassv9/apex-forge-paddock/tree/main/engine/paddock_engine/features"
click node_stats "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/stats/effects.py"
click node_statmodel "https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/stats/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_spool,node_ingest,node_parquet toneBlue
class node_coreapp,node_api,node_sessionstore,node_postgres toneAmber
class node_engineapi,node_sessionfeatures,node_passfeatures,node_samples,node_phases,node_featuremodules,node_stats,node_statmodel toneMint
class node_webapp,node_sessionlist,node_status,node_client toneRose
class node_experiments,node_diagnosis,node_sensitivity,node_ghost,node_driver toneIndigo
```

## Components

### Capture and ingest

- **Spool files**
- [Spool ingest](https://github.com/jassv9/apex-forge-paddock/tree/main/core/internal/ingest): `core/internal/ingest`
- **Raw samples**

### Core service

- [Core process](https://github.com/jassv9/apex-forge-paddock/blob/main/core/cmd/paddock/main.go): `core/cmd/paddock/main.go`
- [REST API](https://github.com/jassv9/apex-forge-paddock/tree/main/core/internal/api): `core/internal/api`
- [Session reader](https://github.com/jassv9/apex-forge-paddock/blob/main/core/internal/store/sessions.go): `core/internal/store/sessions.go`
- **PostgreSQL**

### Analysis engine

- [Engine HTTP API](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/app.py): `engine/paddock_engine/app.py`
- [Session features](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/features/session.py): `engine/paddock_engine/features/session.py`
- [Pass features](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/features/pass_features.py): `engine/paddock_engine/features/pass_features.py`
- [Parquet samples](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/io/samples.py): `engine/paddock_engine/io/samples.py`
- [Corner phases](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/phases/segment.py): `engine/paddock_engine/phases/segment.py`
- [Feature calculations](https://github.com/jassv9/apex-forge-paddock/tree/main/engine/paddock_engine/features): `engine/paddock_engine/features`
- [Effect statistics](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/stats/effects.py): `engine/paddock_engine/stats/effects.py`
- [Mixed model](https://github.com/jassv9/apex-forge-paddock/blob/main/engine/paddock_engine/stats/model.py): `engine/paddock_engine/stats/model.py`

### Dashboard

- [Dashboard app](https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Session list](https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/components/SessionList.tsx): `web/src/components/SessionList.tsx`
- [Core status](https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/components/CoreStatus.tsx): `web/src/components/CoreStatus.tsx`
- [API client](https://github.com/jassv9/apex-forge-paddock/blob/main/web/src/api/client.ts): `web/src/api/client.ts`

### Planned capabilities

- **Experiments and verdicts**
- **Diagnosis**
- **Sensitivity profile**
- **Ghost Driver**

### Other components

- **Game capture**

## Connections

- Game capture → Spool files: writes passes
- Spool files → Spool ingest: tails files
- Core process → Spool ingest: starts (evidence: `core/cmd/paddock/main.go`)
- Spool ingest → PostgreSQL: writes passes
- Spool ingest → Raw samples: writes samples
- Core process → REST API: serves (evidence: `core/cmd/paddock/main.go`)
- Core process → Session reader: configures (evidence: `core/cmd/paddock/main.go`)
- Session reader → PostgreSQL: reads sessions (evidence: `core/internal/store/sessions.go`)
- Dashboard app → Session list: renders (evidence: `web/src/App.tsx`)
- Dashboard app → Core status: renders (evidence: `web/src/App.tsx`)
- Session list → API client: fetches sessions (evidence: `web/src/components/SessionList.tsx`)
- Core status → API client: checks health (evidence: `web/src/components/CoreStatus.tsx`)
- API client → REST API: requests REST
- Engine HTTP API → Session features: dispatches features (evidence: `engine/paddock_engine/app.py`)
- Session features → Parquet samples: reads samples (evidence: `engine/paddock_engine/features/session.py`)
- Session features → Pass features: computes passes (evidence: `engine/paddock_engine/features/session.py`)
- Session features → Corner phases: uses corners (evidence: `engine/paddock_engine/features/session.py`)
- Pass features → Feature calculations: uses calculations (evidence: `engine/paddock_engine/features/pass_features.py`)
- Corner phases → Parquet samples: segments samples (evidence: `engine/paddock_engine/phases/segment.py`)
- Effect statistics → Mixed model: fits model (evidence: `engine/paddock_engine/stats/effects.py`)
- Effect statistics → Parquet samples: reads samples (evidence: `engine/paddock_engine/stats/effects.py`)
- Experiments and verdicts → Diagnosis: informs
- Diagnosis → Sensitivity profile: feeds learning
- Experiments and verdicts → Engine HTTP API: requests analysis
- Ghost Driver → Experiments and verdicts: may support