# wsu-4110/garageiq architecture

> Architecture diagram of the GitHub repository wsu-4110/garageiq, 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/wsu-4110/garageiq
- Repository: https://github.com/wsu-4110/garageiq

## Overview

GarageIQ is a vehicle-garage web app with a React frontend and a FastAPI backend. The visible user workflow is sign-in, viewing a garage, editing vehicle/build/maintenance information, and saving profile changes to Firestore. The backend also initializes a separate advice service that retrieves vehicle-scoped modification and guide knowledge and generates grounded answers. README capabilities include future build planning and compatibility recommendations; the current frontend implements build logs and maintenance, while shop finding is explicitly unavailable in the shown UI. Backend wiring is clearer than frontend-to-backend advice traffic in the excerpts, so that link is omitted.

Main entry points: [`backend/app/main.py`](https://github.com/wsu-4110/garageiq/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/pages/GaragePages.jsx`](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/GaragePages.jsx) (Build and maintenance), [`frontend/src/App.jsx`](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/App.jsx) (React app and routes), [`frontend/src/pages/Dashboard.jsx`](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/Dashboard.jsx) (Garage dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Garage interface"]
  node_app["React app and routes<br/>[App.jsx]"]
  node_dashboard["Garage dashboard<br/>[Dashboard.jsx]"]
  node_garagepages["Build and maintenance<br/>[GaragePages.jsx]"]
  node_advisorui["Advice page<br/>[Advisor.jsx]"]
end

subgraph group_profile["Account and garage data"]
  node_auth["Auth context<br/>[AuthContext.jsx]"]
  node_authhook["Auth hook<br/>[useAuth.js]"]
  node_profilehook["Profile subscription<br/>[useUserProfile.js]"]
  node_profiledata["Profile persistence<br/>[userProfile.js]"]
  node_vehicledata["Vehicle data helpers<br/>[vehicleData.js]"]
  node_maint["Maintenance rules"]
  node_firebase["Firebase client<br/>[firebase.js]"]
end

subgraph group_backend["FastAPI services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_vehicleapi["Vehicle API<br/>[vehicles.py]"]
  node_adviceapi["Advice API<br/>[advice.py]"]
  node_vehicles["Vehicle store<br/>[vehicles.py]"]
  node_advisor["Advisor service<br/>[service.py]"]
end

subgraph group_knowledge["Advice knowledge"]
  node_retriever["Knowledge retriever<br/>[retriever.py]"]
  node_embedder["Text embedder<br/>[embeddings.py]"]
  node_generator["Answer generator<br/>[generate.py]"]
  node_loader["Knowledge loader<br/>[loader.py]"]
  node_hierarchy["Fitment hierarchy<br/>[hierarchy.py]"]
end

node_driver(("Driver"))
node_firestore[("Firestore")]
node_knowledgebase[("Mod and guide knowledge")]

node_driver -->|"uses"| node_app
node_app -->|"provides auth"| node_auth
node_authhook -->|"reads context"| node_auth
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_garagepages
node_app -->|"checks access"| node_authhook
node_auth -->|"uses auth client"| node_firebase
node_profilehook -->|"reads user"| node_authhook
node_profilehook -->|"subscribes"| node_profiledata
node_profiledata -->|"uses Firestore client"| node_firebase
node_firebase -.->|"reads and writes"| node_firestore
node_dashboard -->|"reads profile"| node_profilehook
node_dashboard -->|"uses vehicle data"| node_vehicledata
node_dashboard -->|"calculates reminders"| node_maint
node_garagepages -->|"reads profile"| node_profilehook
node_garagepages -->|"saves edits"| node_profiledata
node_garagepages -->|"builds updates"| node_vehicledata
node_garagepages -->|"calculates reminders"| node_maint
node_garagepages -->|"renders"| node_advisorui
node_api -->|"registers router"| node_vehicleapi
node_api -->|"registers router"| node_adviceapi
node_api -->|"loads knowledge"| node_loader
node_api -->|"builds embedder"| node_embedder
node_api -->|"constructs retriever"| node_retriever
node_api -->|"builds generator"| node_generator
node_api -->|"constructs service"| node_advisor
node_api -->|"builds store"| node_vehicles
node_vehicleapi -->|"uses store"| node_vehicles
node_adviceapi -->|"uses service"| node_advisor
node_advisor -->|"searches knowledge"| node_retriever
node_advisor -->|"generates answer"| node_generator
node_retriever -->|"embeds queries"| node_embedder
node_retriever -->|"consumes knowledge"| node_loader
node_loader -->|"resolves scope"| node_hierarchy
node_loader -.->|"loads datasets"| node_knowledgebase

click node_app "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/App.jsx"
click node_auth "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/context/AuthContext.jsx"
click node_authhook "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/hooks/useAuth.js"
click node_dashboard "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/Dashboard.jsx"
click node_garagepages "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/GaragePages.jsx"
click node_advisorui "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/Advisor.jsx"
click node_profilehook "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/hooks/useUserProfile.js"
click node_profiledata "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/userProfile.js"
click node_vehicledata "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/vehicleData.js"
click node_maint "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/maintenanceRules.js"
click node_firebase "https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/firebase.js"
click node_api "https://github.com/wsu-4110/garageiq/blob/main/backend/app/main.py"
click node_vehicleapi "https://github.com/wsu-4110/garageiq/blob/main/backend/app/api/vehicles.py"
click node_adviceapi "https://github.com/wsu-4110/garageiq/blob/main/backend/app/api/advice.py"
click node_vehicles "https://github.com/wsu-4110/garageiq/blob/main/backend/app/stores/vehicles.py"
click node_advisor "https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/service.py"
click node_retriever "https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/retriever.py"
click node_embedder "https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/embeddings.py"
click node_generator "https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/generate.py"
click node_loader "https://github.com/wsu-4110/garageiq/blob/main/backend/app/knowledge/loader.py"
click node_hierarchy "https://github.com/wsu-4110/garageiq/blob/main/backend/app/knowledge/hierarchy.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_app,node_dashboard,node_garagepages,node_advisorui toneBlue
class node_auth,node_authhook,node_profilehook,node_profiledata,node_vehicledata,node_maint,node_firebase,node_firestore,node_knowledgebase toneAmber
class node_api,node_vehicleapi,node_adviceapi,node_vehicles,node_advisor toneMint
class node_retriever,node_embedder,node_generator,node_loader,node_hierarchy toneRose
class node_driver toneIndigo
```

## Components

### Garage interface

- [React app and routes](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Garage dashboard](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Build and maintenance](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/GaragePages.jsx): `frontend/src/pages/GaragePages.jsx`
- [Advice page](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/pages/Advisor.jsx): `frontend/src/pages/Advisor.jsx`

### Account and garage data

- [Auth context](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Auth hook](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/hooks/useAuth.js): `frontend/src/hooks/useAuth.js`
- [Profile subscription](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/hooks/useUserProfile.js): `frontend/src/hooks/useUserProfile.js`
- [Profile persistence](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/userProfile.js): `frontend/src/lib/userProfile.js`
- [Vehicle data helpers](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/vehicleData.js): `frontend/src/lib/vehicleData.js`
- [Maintenance rules](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/maintenanceRules.js): `frontend/src/lib/maintenanceRules.js`
- [Firebase client](https://github.com/wsu-4110/garageiq/blob/main/frontend/src/lib/firebase.js): `frontend/src/lib/firebase.js`

### FastAPI services

- [FastAPI application](https://github.com/wsu-4110/garageiq/blob/main/backend/app/main.py): `backend/app/main.py`
- [Vehicle API](https://github.com/wsu-4110/garageiq/blob/main/backend/app/api/vehicles.py): `backend/app/api/vehicles.py`
- [Advice API](https://github.com/wsu-4110/garageiq/blob/main/backend/app/api/advice.py): `backend/app/api/advice.py`
- [Vehicle store](https://github.com/wsu-4110/garageiq/blob/main/backend/app/stores/vehicles.py): `backend/app/stores/vehicles.py`
- [Advisor service](https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/service.py): `backend/app/rag/service.py`

### Advice knowledge

- [Knowledge retriever](https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`
- [Text embedder](https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/embeddings.py): `backend/app/rag/embeddings.py`
- [Answer generator](https://github.com/wsu-4110/garageiq/blob/main/backend/app/rag/generate.py): `backend/app/rag/generate.py`
- [Knowledge loader](https://github.com/wsu-4110/garageiq/blob/main/backend/app/knowledge/loader.py): `backend/app/knowledge/loader.py`
- [Fitment hierarchy](https://github.com/wsu-4110/garageiq/blob/main/backend/app/knowledge/hierarchy.py): `backend/app/knowledge/hierarchy.py`

### Other components

- **Driver**
- **Firestore**
- **Mod and guide knowledge**

## Connections

- Driver → React app and routes: uses (evidence: `frontend/src/App.jsx`)
- React app and routes → Auth context: provides auth (evidence: `frontend/src/App.jsx`)
- Auth hook → Auth context: reads context (evidence: `frontend/src/hooks/useAuth.js`)
- React app and routes → Garage dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React app and routes → Build and maintenance: routes to (evidence: `frontend/src/App.jsx`)
- React app and routes → Auth hook: checks access (evidence: `frontend/src/App.jsx`)
- Auth context → Firebase client: uses auth client (evidence: `frontend/src/context/AuthContext.jsx`)
- Profile subscription → Auth hook: reads user (evidence: `frontend/src/hooks/useUserProfile.js`)
- Profile subscription → Profile persistence: subscribes (evidence: `frontend/src/hooks/useUserProfile.js`)
- Profile persistence → Firebase client: uses Firestore client (evidence: `frontend/src/lib/userProfile.js`)
- Firebase client → Firestore: reads and writes
- Garage dashboard → Profile subscription: reads profile (evidence: `frontend/src/pages/Dashboard.jsx`)
- Garage dashboard → Vehicle data helpers: uses vehicle data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Garage dashboard → Maintenance rules: calculates reminders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Build and maintenance → Profile subscription: reads profile (evidence: `frontend/src/pages/GaragePages.jsx`)
- Build and maintenance → Profile persistence: saves edits (evidence: `frontend/src/pages/GaragePages.jsx`)
- Build and maintenance → Vehicle data helpers: builds updates (evidence: `frontend/src/pages/GaragePages.jsx`)
- Build and maintenance → Maintenance rules: calculates reminders (evidence: `frontend/src/pages/GaragePages.jsx`)
- Build and maintenance → Advice page: renders (evidence: `frontend/src/pages/GaragePages.jsx`)
- FastAPI application → Vehicle API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Advice API: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Knowledge loader: loads knowledge (evidence: `backend/app/main.py`)
- FastAPI application → Text embedder: builds embedder (evidence: `backend/app/main.py`)
- FastAPI application → Knowledge retriever: constructs retriever (evidence: `backend/app/main.py`)
- FastAPI application → Answer generator: builds generator (evidence: `backend/app/main.py`)
- FastAPI application → Advisor service: constructs service (evidence: `backend/app/main.py`)
- FastAPI application → Vehicle store: builds store (evidence: `backend/app/main.py`)
- Vehicle API → Vehicle store: uses store (evidence: `backend/app/api/vehicles.py`)
- Advice API → Advisor service: uses service (evidence: `backend/app/api/advice.py`)
- Advisor service → Knowledge retriever: searches knowledge (evidence: `backend/app/rag/service.py`)
- Advisor service → Answer generator: generates answer (evidence: `backend/app/rag/service.py`)
- Knowledge retriever → Text embedder: embeds queries (evidence: `backend/app/rag/retriever.py`)
- Knowledge retriever → Knowledge loader: consumes knowledge (evidence: `backend/app/rag/retriever.py`)
- Knowledge loader → Fitment hierarchy: resolves scope (evidence: `backend/app/knowledge/loader.py`)
- Knowledge loader → Mod and guide knowledge: loads datasets