# sjoshua06/blueprints architecture

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

- Interactive diagram: https://gitdiagram.com/sjoshua06/blueprints
- Repository: https://github.com/sjoshua06/blueprints

## Overview

#### Purpose and entry points
SupplyShield is a supply-chain risk platform: supplier-risk scoring, inventory stockout forecasting, BOM/receipt reconciliation, and compatible-part discovery. The browser application starts at `frontend/src/main.jsx` and routes through `frontend/src/App.jsx`. FastAPI is the backend gateway at `backend/main.py`, run as `uvicorn main:app`.

#### UI and API boundary
React/Vite pages present workflow-specific dashboards and uploads, while shared client code sends authenticated API requests to FastAPI. Primary UI surfaces include `frontend/src/pages/SetupPage.jsx`, `frontend/src/pages/BomAnalysis.jsx`, and `frontend/src/pages/FinalRiskDashboard.jsx`. The boundary is centralized in `frontend/src/services/api.js`; Supabase browser-session handling is in `frontend/src/services/auth.js`.

#### Backend route domains
FastAPI splits the system by supply-chain concern rather than a single monolith:
- Setup/data-ingestion workflow: `backend/api/setup_routes.py`
- Supplier and risk analysis: `backend/api/supplier_router.py`, `backend/api/risk_routes.py`, `backend/api/internal_risk_routes.py`
- BOM and shipping workflows: `backend/api/bom_routes.py`, `backend/api/shipping_routes.py`
- Aggregated decision/dashboard results: `backend/api/dashboard_router.py`, `backend/api/final_risk.py`

Routes validate request/response contracts through Pydantic schemas such as `backend/schemas/risk_schema.py` and `backend/schemas/project_schema.py`.

#### Data isolation and persistence
Supabase/PostgreSQL is the system’s relational persistence layer for supplier, component, and inventory data. Backend database access is organized through `backend/db/supabase_client.py` and `backend/db/database.py`. Token-based authentication is enforced at the API boundary via `backend/auth/dependencies.py`; the frontend uses Supabase credentials rather than directly owning backend authorization logic.

#### Setup and risk-scoring pipeline
Initial uploaded operational data is processed by `backend/services/setup_pipeline.py`, creating the foundation for downstream supplier and inventory analysis. Supplier/internal risk services combine operational records with predictive scoring: `backend/services/risk_predictor.py` and `backend/services/internal_risk_service.py`. The repository includes persisted model artifacts—`backend/services/risk_model.pkl`, `backend/services/feature_columns.pkl`, and encoders—indicating local model inference is a material runtime dependency, alongside the documented Hugging Face model access configuration.

#### Forecasting and inventory decisions
Inventory history is converted to time-series projections by Prophet in `backend/services/prophet_forecast_service.py`. Forecast-oriented pages, notably `frontend/src/pages/InventoryDash.jsx` and `frontend/src/pages/InventoryRisk.jsx`, render inventory risk and forecast outcomes; `frontend/src/components/ProphetChart.jsx` is the dedicated chart presentation boundary. This stage turns persisted demand/inventory history into 90-day stockout and reorder decision inputs.

#### BOM reconciliation and compatibility search
The BOM path ingests BOMs and receipts, parses them, and identifies missing or mismatched components through `backend/services/bom_parser.py`, `backend/services/receipt_parser.py`, and `backend/services/receipt_checker.py`. For substitutes, part specifications are loaded and converted into searchable vectors by `backend/services/spec_loader.py` and `backend/services/vector_builder.py`; FAISS index management/search occurs in `backend/services/faiss_manager.py` and `backend/services/vector_search.py`. Results are exposed to the BOM UI through `backend/api/bom_routes.py`.

#### External services and material runtimes
The platform requires Python 3.10+, FastAPI, SQLAlchemy, scikit-learn/joblib model loading, Prophet, and FAISS, defined from `backend/requirements.txt`. Its web runtime is React/Vite from `frontend/package.json`; Recharts supports decision visualizations. Supabase supplies authentication and PostgreSQL-backed storage. Environment configuration also references Hugging Face credentials/repository access for risk-model deployment.

Main entry points: [`backend/api/setup_routes.py`](https://github.com/sjoshua06/blueprints/blob/main/backend/api/setup_routes.py) (Workflow routes), [`backend/db/supabase_client.py`](https://github.com/sjoshua06/blueprints/blob/main/backend/db/supabase_client.py) (Supabase PostgreSQL), [`frontend/src/services/api.js`](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/services/api.js) (Authenticated API client), [`backend/main.py`](https://github.com/sjoshua06/blueprints/blob/main/backend/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser App"]
  node_react_app["React/Vite app<br/>web client<br/>[App.jsx]"]
  node_setup_ui["Setup workflow<br/>UI page<br/>[SetupPage.jsx]"]
  node_bom_ui["BOM analysis<br/>UI page<br/>[BomAnalysis.jsx]"]
  node_risk_ui["Risk dashboards<br/>UI pages"]
  node_api_client["Authenticated API client<br/>client boundary<br/>[api.js]"]
  node_supabase_auth_client["Supabase session<br/>browser auth<br/>[auth.js]"]
  node_prophet_chart["Forecast chart<br/>UI component<br/>[ProphetChart.jsx]"]
end

subgraph group_api["FastAPI Gateway"]
  node_fastapi{{"FastAPI application<br/>API gateway<br/>[main.py]"}}
  node_route_domains["Workflow routes<br/>route modules<br/>[setup_routes.py]"]
  node_schemas["Pydantic contracts<br/>API schemas<br/>[risk_schema.py]"]
  node_api_auth["Token enforcement<br/>auth dependency<br/>[dependencies.py]"]
end

subgraph group_services["Analysis Services"]
  node_setup_pipeline["Setup ingestion pipeline<br/>data pipeline<br/>[setup_pipeline.py]"]
  node_risk_scoring["Risk scoring<br/>ML inference<br/>[risk_predictor.py]"]
  node_forecasting["Prophet forecasting<br/>time-series service"]
  node_bom_reconciliation["BOM reconciliation<br/>parsing service<br/>[receipt_checker.py]"]
  node_compatibility_search["Part compatibility search<br/>vector search<br/>[vector_search.py]"]
  node_model_artifacts["Persisted risk model<br/>model artifacts<br/>[risk_model.pkl]"]
end

subgraph group_data["Data &amp; Identity"]
  node_supabase_postgres[("Supabase PostgreSQL<br/>relational store<br/>[supabase_client.py]")]
end

subgraph group_external["External Runtimes"]
  node_huggingface["Hugging Face access<br/>model service"]
end

node_react_app -->|"renders"| node_setup_ui
node_react_app -->|"renders"| node_bom_ui
node_react_app -->|"renders"| node_risk_ui
node_setup_ui -->|"uploads via"| node_api_client
node_bom_ui -->|"queries via"| node_api_client
node_risk_ui -->|"queries via"| node_api_client
node_risk_ui -->|"displays forecasts"| node_prophet_chart
node_supabase_auth_client -->|"supplies session token"| node_api_client
node_api_client -->|"authenticated requests"| node_fastapi
node_fastapi -->|"enforces tokens"| node_api_auth
node_api_auth -->|"validates identity"| node_supabase_postgres
node_fastapi -->|"validates contracts"| node_schemas
node_fastapi -->|"mounts domains"| node_route_domains
node_route_domains -->|"ingests setup data"| node_setup_pipeline
node_route_domains -->|"runs risk analysis"| node_risk_scoring
node_route_domains -->|"requests forecasts"| node_forecasting
node_route_domains -->|"reconciles BOMs"| node_bom_reconciliation
node_route_domains -->|"finds substitutes"| node_compatibility_search
node_setup_pipeline -->|"stores operational data"| node_supabase_postgres
node_risk_scoring -->|"reads operational records"| node_supabase_postgres
node_risk_scoring -->|"loads model"| node_model_artifacts
node_risk_scoring -.->|"uses configured access"| node_huggingface
node_forecasting -->|"reads inventory history"| node_supabase_postgres
node_bom_reconciliation -->|"reads and writes components"| node_supabase_postgres
node_compatibility_search -->|"loads part specifications"| node_supabase_postgres

click node_react_app "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/App.jsx"
click node_setup_ui "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/pages/SetupPage.jsx"
click node_bom_ui "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/pages/BomAnalysis.jsx"
click node_risk_ui "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/pages/FinalRiskDashboard.jsx"
click node_api_client "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/services/api.js"
click node_supabase_auth_client "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/services/auth.js"
click node_fastapi "https://github.com/sjoshua06/blueprints/blob/main/backend/main.py"
click node_route_domains "https://github.com/sjoshua06/blueprints/blob/main/backend/api/setup_routes.py"
click node_schemas "https://github.com/sjoshua06/blueprints/blob/main/backend/schemas/risk_schema.py"
click node_api_auth "https://github.com/sjoshua06/blueprints/blob/main/backend/auth/dependencies.py"
click node_setup_pipeline "https://github.com/sjoshua06/blueprints/blob/main/backend/services/setup_pipeline.py"
click node_risk_scoring "https://github.com/sjoshua06/blueprints/blob/main/backend/services/risk_predictor.py"
click node_forecasting "https://github.com/sjoshua06/blueprints/blob/main/backend/services/prophet_forecast_service.py"
click node_bom_reconciliation "https://github.com/sjoshua06/blueprints/blob/main/backend/services/receipt_checker.py"
click node_compatibility_search "https://github.com/sjoshua06/blueprints/blob/main/backend/services/vector_search.py"
click node_supabase_postgres "https://github.com/sjoshua06/blueprints/blob/main/backend/db/supabase_client.py"
click node_model_artifacts "https://github.com/sjoshua06/blueprints/blob/main/backend/services/risk_model.pkl"
click node_prophet_chart "https://github.com/sjoshua06/blueprints/blob/main/frontend/src/components/ProphetChart.jsx"

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_react_app,node_setup_ui,node_bom_ui,node_risk_ui,node_api_client,node_supabase_auth_client,node_prophet_chart toneBlue
class node_fastapi,node_route_domains,node_schemas,node_api_auth toneAmber
class node_setup_pipeline,node_risk_scoring,node_forecasting,node_bom_reconciliation,node_compatibility_search,node_model_artifacts toneMint
class node_supabase_postgres toneRose
class node_huggingface toneIndigo
```

## Components

### Browser App

- [React/Vite app](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/App.jsx): web client · Routes workflow dashboards and uploads. · `frontend/src/App.jsx`
- [Setup workflow](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/pages/SetupPage.jsx): UI page · `frontend/src/pages/SetupPage.jsx`
- [BOM analysis](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/pages/BomAnalysis.jsx): UI page · `frontend/src/pages/BomAnalysis.jsx`
- [Risk dashboards](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/pages/FinalRiskDashboard.jsx): UI pages · Supplier, final-risk, and inventory decision views. · `frontend/src/pages/FinalRiskDashboard.jsx`
- [Authenticated API client](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/services/api.js): client boundary · `frontend/src/services/api.js`
- [Supabase session](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/services/auth.js): browser auth · `frontend/src/services/auth.js`
- [Forecast chart](https://github.com/sjoshua06/blueprints/blob/main/frontend/src/components/ProphetChart.jsx): UI component · `frontend/src/components/ProphetChart.jsx`

### FastAPI Gateway

- [FastAPI application](https://github.com/sjoshua06/blueprints/blob/main/backend/main.py): API gateway · Authenticated backend entry point. · `backend/main.py`
- [Workflow routes](https://github.com/sjoshua06/blueprints/blob/main/backend/api/setup_routes.py): route modules · Setup, supplier/risk, BOM/shipping, and dashboard endpoints. · `backend/api/setup_routes.py`
- [Pydantic contracts](https://github.com/sjoshua06/blueprints/blob/main/backend/schemas/risk_schema.py): API schemas · `backend/schemas/risk_schema.py`
- [Token enforcement](https://github.com/sjoshua06/blueprints/blob/main/backend/auth/dependencies.py): auth dependency · `backend/auth/dependencies.py`

### Analysis Services

- [Setup ingestion pipeline](https://github.com/sjoshua06/blueprints/blob/main/backend/services/setup_pipeline.py): data pipeline · Processes uploaded operational data for downstream analysis. · `backend/services/setup_pipeline.py`
- [Risk scoring](https://github.com/sjoshua06/blueprints/blob/main/backend/services/risk_predictor.py): ML inference · Combines operational records with supplier and internal risk models. · `backend/services/risk_predictor.py`
- [Prophet forecasting](https://github.com/sjoshua06/blueprints/blob/main/backend/services/prophet_forecast_service.py): time-series service · Produces 90-day stockout and reorder inputs. · `backend/services/prophet_forecast_service.py`
- [BOM reconciliation](https://github.com/sjoshua06/blueprints/blob/main/backend/services/receipt_checker.py): parsing service · Parses BOMs and receipts to find missing or mismatched components. · `backend/services/receipt_checker.py`
- [Part compatibility search](https://github.com/sjoshua06/blueprints/blob/main/backend/services/vector_search.py): vector search · Builds and searches FAISS vectors for substitute parts. · `backend/services/vector_search.py`
- [Persisted risk model](https://github.com/sjoshua06/blueprints/blob/main/backend/services/risk_model.pkl): model artifacts · Local scikit-learn model, feature columns, and encoders. · `backend/services/risk_model.pkl`

### Data & Identity

- [Supabase PostgreSQL](https://github.com/sjoshua06/blueprints/blob/main/backend/db/supabase_client.py): relational store · Persists supplier, component, inventory, and operational records. · `backend/db/supabase_client.py`

### External Runtimes

- **Hugging Face access**: model service · Configured model repository access for risk-model deployment.

## Connections

- React/Vite app → Setup workflow: renders
- React/Vite app → BOM analysis: renders
- React/Vite app → Risk dashboards: renders
- Setup workflow → Authenticated API client: uploads via
- BOM analysis → Authenticated API client: queries via
- Risk dashboards → Authenticated API client: queries via
- Risk dashboards → Forecast chart: displays forecasts
- Supabase session → Authenticated API client: supplies session token
- Authenticated API client → FastAPI application: authenticated requests
- FastAPI application → Token enforcement: enforces tokens
- Token enforcement → Supabase PostgreSQL: validates identity
- FastAPI application → Pydantic contracts: validates contracts
- FastAPI application → Workflow routes: mounts domains
- Workflow routes → Setup ingestion pipeline: ingests setup data
- Workflow routes → Risk scoring: runs risk analysis
- Workflow routes → Prophet forecasting: requests forecasts
- Workflow routes → BOM reconciliation: reconciles BOMs
- Workflow routes → Part compatibility search: finds substitutes
- Setup ingestion pipeline → Supabase PostgreSQL: stores operational data
- Risk scoring → Supabase PostgreSQL: reads operational records
- Risk scoring → Persisted risk model: loads model
- Risk scoring → Hugging Face access: uses configured access
- Prophet forecasting → Supabase PostgreSQL: reads inventory history
- BOM reconciliation → Supabase PostgreSQL: reads and writes components
- Part compatibility search → Supabase PostgreSQL: loads part specifications