# nealsz/smartbuild architecture

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

- Interactive diagram: https://gitdiagram.com/nealsz/smartbuild
- Repository: https://github.com/nealsz/smartbuild

## Overview

SmartBuild turns budget, workload, cooling and display preferences into compatible PC recommendations, or supports a guided component-by-component build. The result experience compares value and performance alternatives, supports swaps and reservations; staff manage tickets and inventory. The graph follows documented routes and sampled import/call references. Several frontend-to-API links and unsampled feature internals are based on the README rather than inspected implementation details.

Main entry points: [`backend/services/recommender.py`](https://github.com/nealsz/smartbuild/blob/main/backend/services/recommender.py) (Quick recommender), [`backend/main.py`](https://github.com/nealsz/smartbuild/blob/main/backend/main.py) (FastAPI routes), [`backend/services/builder_service.py`](https://github.com/nealsz/smartbuild/blob/main/backend/services/builder_service.py) (Guided build service), [`backend/services/supabase_service.py`](https://github.com/nealsz/smartbuild/blob/main/backend/services/supabase_service.py) (Component catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Build experience"]
  node_builder["PC builder<br/>[page.tsx]"]
  node_intake["Preference intake<br/>[page.tsx]"]
  node_guided["Guided assembly<br/>[page.tsx]"]
  node_comparison["Build comparison<br/>[page.tsx]"]
  node_reservation["Reservation form"]
  node_staff["Admin portal<br/>[page.tsx]"]
  node_inventory_ui["Inventory manager<br/>[AdminTable.tsx]"]
  node_ticket_ui["Ticket manager<br/>[TicketsTable.tsx]"]
end

subgraph group_api["API orchestration"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_inputs["Input validation<br/>[user_input.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_ticket_routes["Ticket routes<br/>[tickets.py]"]
end

subgraph group_recommend["Recommendation engine"]
  node_recommender["Quick recommender<br/>[recommender.py]"]
  node_guided_service["Guided build service<br/>[builder_service.py]"]
  node_selector["Component selector<br/>[selector.py]"]
  node_compat["Compatibility rules<br/>[compatibility.py]"]
  node_intent["Workload classifier"]
end

subgraph group_operations["Store operations"]
end

subgraph group_modeling["Model and data"]
  node_model_v4["Model training v4<br/>[train_model_v4.py]"]
  node_model_v3["Model training v3<br/>[train_model_v3.py]"]
  node_config["Hardware weights<br/>[config.py]"]
  node_catalog[("Component catalog")]
end

node_customer(("PC builder user"))
node_staff_actor(("Store staff"))

node_customer -->|"starts"| node_builder
node_builder -->|"enters preferences"| node_intake
node_customer -->|"chooses guided build"| node_guided
node_intake -->|"submits build request"| node_api
node_guided -->|"requests options"| node_api
node_guided -->|"finalizes selection"| node_api
node_api -->|"validates"| node_inputs
node_api -->|"generates build"| node_recommender
node_api -->|"gets options"| node_guided_service
node_api -->|"finalizes build"| node_guided_service
node_recommender -->|"classifies workload"| node_intent
node_recommender -->|"selects components"| node_selector
node_recommender -->|"checks build"| node_compat
node_guided_service -->|"validates compatibility"| node_compat
node_guided_service -->|"uses recommendation logic"| node_recommender
node_recommender -->|"uses model logic"| node_model_v4
node_selector -->|"checks candidates"| node_compat
node_recommender -->|"loads components"| node_catalog
node_guided_service -.->|"uses catalog data"| node_catalog
node_comparison -->|"opens reservation"| node_reservation
node_comparison -->|"requests build"| node_api
node_reservation -->|"creates ticket"| node_ticket_routes
node_staff_actor -->|"manages store"| node_staff
node_staff -->|"opens inventory"| node_inventory_ui
node_staff -->|"opens tickets"| node_ticket_ui
node_inventory_ui -->|"manages components"| node_admin_routes
node_ticket_ui -->|"manages reservations"| node_ticket_routes
node_admin_routes -->|"reads and updates"| node_catalog
node_ticket_routes -->|"adjusts stock"| node_catalog
node_model_v4 -->|"loads training data"| node_catalog
node_model_v3 -->|"loads training data"| node_catalog
node_recommender -->|"uses hardware weights"| node_config
node_guided_service -->|"uses budget shares"| node_config
node_compat -->|"uses compatibility settings"| node_config

click node_builder "https://github.com/nealsz/smartbuild/blob/main/client/src/app/page.tsx"
click node_intake "https://github.com/nealsz/smartbuild/blob/main/client/src/app/user-input/page.tsx"
click node_guided "https://github.com/nealsz/smartbuild/blob/main/client/src/app/guided-builder/page.tsx"
click node_comparison "https://github.com/nealsz/smartbuild/blob/main/client/src/app/build-result/page.tsx"
click node_reservation "https://github.com/nealsz/smartbuild/blob/main/client/src/app/build-result/StoreTicketModal.tsx"
click node_staff "https://github.com/nealsz/smartbuild/blob/main/client/src/app/admin/page.tsx"
click node_inventory_ui "https://github.com/nealsz/smartbuild/blob/main/client/src/app/admin/AdminTable.tsx"
click node_ticket_ui "https://github.com/nealsz/smartbuild/blob/main/client/src/app/admin/TicketsTable.tsx"
click node_api "https://github.com/nealsz/smartbuild/blob/main/backend/main.py"
click node_inputs "https://github.com/nealsz/smartbuild/blob/main/backend/schemas/user_input.py"
click node_admin_routes "https://github.com/nealsz/smartbuild/blob/main/backend/routers/admin.py"
click node_ticket_routes "https://github.com/nealsz/smartbuild/blob/main/backend/routers/tickets.py"
click node_recommender "https://github.com/nealsz/smartbuild/blob/main/backend/services/recommender.py"
click node_guided_service "https://github.com/nealsz/smartbuild/blob/main/backend/services/builder_service.py"
click node_selector "https://github.com/nealsz/smartbuild/blob/main/backend/services/selector.py"
click node_compat "https://github.com/nealsz/smartbuild/blob/main/backend/services/compatibility.py"
click node_intent "https://github.com/nealsz/smartbuild/blob/main/backend/services/intent_classifier.py"
click node_model_v4 "https://github.com/nealsz/smartbuild/blob/main/backend/model/train_model_v4.py"
click node_model_v3 "https://github.com/nealsz/smartbuild/blob/main/backend/model/train_model_v3.py"
click node_config "https://github.com/nealsz/smartbuild/blob/main/backend/config.py"
click node_catalog "https://github.com/nealsz/smartbuild/blob/main/backend/services/supabase_service.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_builder,node_intake,node_guided,node_comparison,node_reservation,node_staff,node_inventory_ui,node_ticket_ui,node_customer toneBlue
class node_api,node_inputs,node_admin_routes,node_ticket_routes toneAmber
class node_recommender,node_guided_service,node_selector,node_compat,node_intent toneMint
class node_model_v4,node_model_v3,node_config,node_catalog,node_staff_actor toneIndigo
```

## Components

### Build experience

- [PC builder](https://github.com/nealsz/smartbuild/blob/main/client/src/app/page.tsx): `client/src/app/page.tsx`
- [Preference intake](https://github.com/nealsz/smartbuild/blob/main/client/src/app/user-input/page.tsx): `client/src/app/user-input/page.tsx`
- [Guided assembly](https://github.com/nealsz/smartbuild/blob/main/client/src/app/guided-builder/page.tsx): `client/src/app/guided-builder/page.tsx`
- [Build comparison](https://github.com/nealsz/smartbuild/blob/main/client/src/app/build-result/page.tsx): `client/src/app/build-result/page.tsx`
- [Reservation form](https://github.com/nealsz/smartbuild/blob/main/client/src/app/build-result/StoreTicketModal.tsx): `client/src/app/build-result/StoreTicketModal.tsx`
- [Admin portal](https://github.com/nealsz/smartbuild/blob/main/client/src/app/admin/page.tsx): `client/src/app/admin/page.tsx`
- [Inventory manager](https://github.com/nealsz/smartbuild/blob/main/client/src/app/admin/AdminTable.tsx): `client/src/app/admin/AdminTable.tsx`
- [Ticket manager](https://github.com/nealsz/smartbuild/blob/main/client/src/app/admin/TicketsTable.tsx): `client/src/app/admin/TicketsTable.tsx`

### API orchestration

- [FastAPI routes](https://github.com/nealsz/smartbuild/blob/main/backend/main.py): `backend/main.py`
- [Input validation](https://github.com/nealsz/smartbuild/blob/main/backend/schemas/user_input.py): `backend/schemas/user_input.py`
- [Admin routes](https://github.com/nealsz/smartbuild/blob/main/backend/routers/admin.py): `backend/routers/admin.py`
- [Ticket routes](https://github.com/nealsz/smartbuild/blob/main/backend/routers/tickets.py): `backend/routers/tickets.py`

### Recommendation engine

- [Quick recommender](https://github.com/nealsz/smartbuild/blob/main/backend/services/recommender.py): `backend/services/recommender.py`
- [Guided build service](https://github.com/nealsz/smartbuild/blob/main/backend/services/builder_service.py): `backend/services/builder_service.py`
- [Component selector](https://github.com/nealsz/smartbuild/blob/main/backend/services/selector.py): `backend/services/selector.py`
- [Compatibility rules](https://github.com/nealsz/smartbuild/blob/main/backend/services/compatibility.py): `backend/services/compatibility.py`
- [Workload classifier](https://github.com/nealsz/smartbuild/blob/main/backend/services/intent_classifier.py): `backend/services/intent_classifier.py`

### Model and data

- [Model training v4](https://github.com/nealsz/smartbuild/blob/main/backend/model/train_model_v4.py): `backend/model/train_model_v4.py`
- [Model training v3](https://github.com/nealsz/smartbuild/blob/main/backend/model/train_model_v3.py): `backend/model/train_model_v3.py`
- [Hardware weights](https://github.com/nealsz/smartbuild/blob/main/backend/config.py): `backend/config.py`
- [Component catalog](https://github.com/nealsz/smartbuild/blob/main/backend/services/supabase_service.py): `backend/services/supabase_service.py`

### Other components

- **PC builder user**
- **Store staff**

## Connections

- PC builder user → PC builder: starts (evidence: `README.md`)
- PC builder → Preference intake: enters preferences (evidence: `README.md`)
- PC builder user → Guided assembly: chooses guided build (evidence: `README.md`)
- Preference intake → FastAPI routes: submits build request (evidence: `README.md`)
- Guided assembly → FastAPI routes: requests options (evidence: `README.md`)
- Guided assembly → FastAPI routes: finalizes selection (evidence: `README.md`)
- FastAPI routes → Input validation: validates (evidence: `backend/main.py`)
- FastAPI routes → Quick recommender: generates build (evidence: `backend/main.py`)
- FastAPI routes → Guided build service: gets options (evidence: `backend/main.py`)
- FastAPI routes → Guided build service: finalizes build (evidence: `backend/main.py`)
- Quick recommender → Workload classifier: classifies workload (evidence: `backend/services/recommender.py`)
- Quick recommender → Component selector: selects components (evidence: `backend/services/recommender.py`)
- Quick recommender → Compatibility rules: checks build (evidence: `backend/services/recommender.py`)
- Guided build service → Compatibility rules: validates compatibility (evidence: `backend/services/builder_service.py`)
- Guided build service → Quick recommender: uses recommendation logic (evidence: `backend/services/builder_service.py`)
- Quick recommender → Model training v4: uses model logic (evidence: `backend/services/recommender.py`)
- Component selector → Compatibility rules: checks candidates (evidence: `backend/services/selector.py`)
- Quick recommender → Component catalog: loads components (evidence: `backend/services/recommender.py`)
- Guided build service → Component catalog: uses catalog data
- Build comparison → Reservation form: opens reservation (evidence: `client/src/app/build-result/page.tsx`)
- Build comparison → FastAPI routes: requests build (evidence: `README.md`)
- Reservation form → Ticket routes: creates ticket (evidence: `README.md`)
- Store staff → Admin portal: manages store (evidence: `README.md`)
- Admin portal → Inventory manager: opens inventory (evidence: `client/src/app/admin/page.tsx`)
- Admin portal → Ticket manager: opens tickets (evidence: `client/src/app/admin/page.tsx`)
- Inventory manager → Admin routes: manages components (evidence: `README.md`)
- Ticket manager → Ticket routes: manages reservations (evidence: `README.md`)
- Admin routes → Component catalog: reads and updates (evidence: `backend/routers/admin.py`)
- Ticket routes → Component catalog: adjusts stock (evidence: `backend/routers/tickets.py`)
- Model training v4 → Component catalog: loads training data (evidence: `backend/model/train_model_v4.py`)
- Model training v3 → Component catalog: loads training data (evidence: `backend/model/train_model_v3.py`)
- Quick recommender → Hardware weights: uses hardware weights (evidence: `backend/services/recommender.py`)
- Guided build service → Hardware weights: uses budget shares (evidence: `backend/services/builder_service.py`)
- Compatibility rules → Hardware weights: uses compatibility settings (evidence: `backend/services/compatibility.py`)
