# sandeepkr24/forzahelper architecture

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

- Interactive diagram: https://gitdiagram.com/sandeepkr24/forzahelper
- Repository: https://github.com/sandeepkr24/forzahelper

## Overview

ForzaHelper is a browser-based Forza Horizon 6 car explorer, comparison tool, and conversational Car Finder. The main workflow sends a user’s structured or natural-language filters through the API; chat requests are extracted and validated, interpreted under an explicit tolerance policy, then evaluated by deterministic parameterized queries against PostgreSQL. Results and any labelled alternatives return to the browser. The graph includes documented browse, detail, compare, metadata, and suggestion capabilities. Relationships are cited to the README or source excerpts/index; unsampled implementation details are not inferred.

Main entry points: [`src/forzahelper/api.py`](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/api.py) (HTTP API), [`src/forzahelper/chat/orchestrator.py`](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/chat/orchestrator.py) (Chat turn orchestration), [`src/forzahelper/search.py`](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/search.py) (Car search and query builder), [`src/forzahelper/models.py`](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/models.py) (Request and response models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_browser["Web interface<br/>[index.html]"]
end

subgraph group_api["API and contracts"]
  node_api_app["HTTP API<br/>[api.py]"]
  node_contracts["Request and response models<br/>[models.py]"]
  node_settings["Application settings<br/>[config.py]"]
end

subgraph group_finder["Search and interpretation"]
  node_chat_flow["Chat turn orchestration<br/>[orchestrator.py]"]
  node_extract["Filter extraction<br/>[extraction.py]"]
  node_interpret["Tolerance and alternatives<br/>[interpret.py]"]
  node_search["Car search and query builder<br/>[search.py]"]
end

subgraph group_data["Data access"]
  node_pool["Database connection pool<br/>[db.py]"]
  node_cars_view[("cars_api view")]
end

node_driver(("Car shopper"))
node_language_model["Anthropic model"]
node_postgres[("PostgreSQL")]

node_driver -->|"uses"| node_browser
node_browser -->|"requests data"| node_api_app
node_api_app -->|"validates"| node_contracts
node_api_app -->|"routes browse and car operations"| node_search
node_api_app -->|"dispatches chat"| node_chat_flow
node_api_app -->|"reads settings"| node_settings
node_chat_flow -->|"extracts filters"| node_extract
node_chat_flow -->|"validates filters"| node_contracts
node_chat_flow -->|"applies policy"| node_interpret
node_chat_flow -->|"runs search"| node_search
node_extract -->|"returns filters"| node_contracts
node_extract -.->|"invokes optionally"| node_language_model
node_interpret -->|"checks alternatives"| node_search
node_search -->|"builds results"| node_contracts
node_search -->|"executes queries"| node_pool
node_pool -->|"configures connections"| node_settings
node_pool -->|"queries"| node_postgres
node_postgres -->|"serves car data"| node_cars_view

click node_browser "https://github.com/sandeepkr24/forzahelper/blob/master/ui/index.html"
click node_api_app "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/api.py"
click node_contracts "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/models.py"
click node_settings "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/config.py"
click node_chat_flow "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/chat/orchestrator.py"
click node_extract "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/chat/extraction.py"
click node_interpret "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/interpret.py"
click node_search "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/search.py"
click node_pool "https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/db.py"
click node_cars_view "https://github.com/sandeepkr24/forzahelper/blob/master/db/02_cars_api_view.sql"

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_browser toneBlue
class node_api_app,node_contracts,node_settings,node_postgres toneAmber
class node_chat_flow,node_extract,node_interpret,node_search toneMint
class node_pool,node_cars_view toneRose
class node_driver,node_language_model toneIndigo
```

## Components

### Browser experience

- [Web interface](https://github.com/sandeepkr24/forzahelper/blob/master/ui/index.html): `ui/index.html`

### API and contracts

- [HTTP API](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/api.py): `src/forzahelper/api.py`
- [Request and response models](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/models.py): `src/forzahelper/models.py`
- [Application settings](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/config.py): `src/forzahelper/config.py`

### Search and interpretation

- [Chat turn orchestration](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/chat/orchestrator.py): `src/forzahelper/chat/orchestrator.py`
- [Filter extraction](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/chat/extraction.py): `src/forzahelper/chat/extraction.py`
- [Tolerance and alternatives](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/interpret.py): `src/forzahelper/interpret.py`
- [Car search and query builder](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/search.py): `src/forzahelper/search.py`

### Data access

- [Database connection pool](https://github.com/sandeepkr24/forzahelper/blob/master/src/forzahelper/db.py): `src/forzahelper/db.py`
- [cars_api view](https://github.com/sandeepkr24/forzahelper/blob/master/db/02_cars_api_view.sql): `db/02_cars_api_view.sql`

### Other components

- **Car shopper**
- **Anthropic model**
- **PostgreSQL**

## Connections

- Car shopper → Web interface: uses (evidence: `README.md`)
- Web interface → HTTP API: requests data (evidence: `README.md`)
- HTTP API → Request and response models: validates (evidence: `src/forzahelper/api.py`)
- HTTP API → Car search and query builder: routes browse and car operations (evidence: `src/forzahelper/api.py`)
- HTTP API → Chat turn orchestration: dispatches chat (evidence: `src/forzahelper/api.py`)
- HTTP API → Application settings: reads settings (evidence: `src/forzahelper/api.py`)
- Chat turn orchestration → Filter extraction: extracts filters (evidence: `src/forzahelper/chat/orchestrator.py`)
- Chat turn orchestration → Request and response models: validates filters (evidence: `src/forzahelper/chat/orchestrator.py`)
- Chat turn orchestration → Tolerance and alternatives: applies policy (evidence: `src/forzahelper/chat/orchestrator.py`)
- Chat turn orchestration → Car search and query builder: runs search (evidence: `src/forzahelper/chat/orchestrator.py`)
- Filter extraction → Request and response models: returns filters (evidence: `src/forzahelper/chat/extraction.py`)
- Filter extraction → Anthropic model: invokes optionally (evidence: `README.md`)
- Tolerance and alternatives → Car search and query builder: checks alternatives (evidence: `src/forzahelper/interpret.py`)
- Car search and query builder → Request and response models: builds results (evidence: `src/forzahelper/search.py`)
- Car search and query builder → Database connection pool: executes queries (evidence: `src/forzahelper/search.py`)
- Database connection pool → Application settings: configures connections (evidence: `src/forzahelper/db.py`)
- Database connection pool → PostgreSQL: queries (evidence: `README.md`)
- PostgreSQL → cars_api view: serves car data (evidence: `README.md`)
