# josshua-dsa/neo-horcrox-project architecture

> Architecture diagram of the GitHub repository josshua-dsa/neo-horcrox-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josshua-dsa/neo-horcrox-project
- Repository: https://github.com/josshua-dsa/neo-horcrox-project

## Overview

Neo Horcrox is a web-based supply-chain decision-support application. Stakeholders use the dashboard to inspect filtered operational metrics, choose a ranked product candidate, and view its profile and trend; the profile supplies context for demand forecasting and optional late-shipment risk prediction. The FastAPI backend serves these domain capabilities, with PostgreSQL for order data and risk-prediction logs, and CSV/JSON/model artifacts for fallback analytics, supplier rankings, and model serving. The README documents these major capabilities; links for unsampled frontend and model-loading internals are limited to documented behavior.

Main entry points: [`app/backend/main.py`](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/main.py) (FastAPI app), [`app/backend/routes/risk_predict_routes.py`](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/risk_predict_routes.py) (Risk routes), [`app/frontend/src/js/api.js`](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/api.js) (API client), [`app/backend/routes/supplier_selection_routes.py`](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/supplier_selection_routes.py) (Supplier routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend_api["API client<br/>[api.js]"]
  node_dashboard_ui["Dashboard UI<br/>[dashboardPage.js]"]
  node_supplier_ui["Supplier selection UI"]
  node_profile_ui["Product profile UI"]
  node_profile_logic["Profile logic"]
end

subgraph group_api["API layer"]
  node_app_entry["FastAPI app<br/>[main.py]"]
  node_dashboard_routes["Dashboard routes"]
  node_supplier_routes["Supplier routes"]
  node_forecast_routes["Forecast routes<br/>[forecast_routes.py]"]
  node_risk_routes["Risk routes"]
  node_order_service["Order and risk logs<br/>[order_service.py]"]
  node_database_layer["Database manager<br/>[database.py]"]
end

subgraph group_analytics["Decision analytics"]
  node_dashboard_service["Dashboard aggregation"]
  node_supplier_service["Supplier ranking"]
  node_dashboard_dataset["Dashboard dataset"]
end

subgraph group_serving["Model serving"]
  node_forecast_service["Demand forecast"]
  node_risk_service["Risk prediction"]
  node_model_registry["Model registry<br/>[model_registry.py]"]
end

node_stakeholder(("Stakeholder"))
node_browser(("Browser"))
node_postgres[("PostgreSQL")]
node_artifacts["Data and model artifacts"]

node_stakeholder -->|"uses"| node_browser
node_browser -->|"opens dashboard"| node_dashboard_ui
node_browser -->|"selects product"| node_supplier_ui
node_supplier_ui -->|"requests candidates"| node_frontend_api
node_dashboard_ui -->|"requests metrics"| node_frontend_api
node_profile_ui -->|"renders profile"| node_profile_logic
node_profile_logic -->|"requests forecast"| node_frontend_api
node_frontend_api -->|"REST requests"| node_app_entry
node_app_entry -->|"dispatches"| node_dashboard_routes
node_app_entry -->|"dispatches"| node_supplier_routes
node_app_entry -->|"dispatches"| node_forecast_routes
node_app_entry -->|"dispatches"| node_risk_routes
node_dashboard_routes -->|"queries"| node_dashboard_service
node_dashboard_service -->|"queries"| node_database_layer
node_dashboard_service -.->|"CSV fallback"| node_dashboard_dataset
node_database_layer -->|"reads and writes"| node_postgres
node_supplier_routes -->|"queries"| node_supplier_service
node_supplier_service -->|"reads rankings"| node_artifacts
node_supplier_service -->|"reads product data"| node_dashboard_dataset
node_supplier_routes -->|"returns product detail"| node_profile_ui
node_forecast_routes -->|"predicts"| node_forecast_service
node_forecast_service -->|"uses loaded model"| node_model_registry
node_model_registry -->|"loads models"| node_artifacts
node_risk_routes -->|"predicts"| node_risk_service
node_risk_service -->|"uses loaded model"| node_model_registry
node_risk_routes -->|"logs predictions"| node_order_service
node_risk_routes -->|"reads prediction logs"| node_order_service
node_order_service -->|"stores and queries"| node_database_layer

click node_frontend_api "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/api.js"
click node_dashboard_ui "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/pages/dashboardPage.js"
click node_supplier_ui "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/pages/suplier_selectionPage.js"
click node_profile_ui "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/pages/product_profilingPage.js"
click node_profile_logic "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/product-profiling.js"
click node_app_entry "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/main.py"
click node_dashboard_routes "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/dashboard_routes.py"
click node_supplier_routes "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/supplier_selection_routes.py"
click node_forecast_routes "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/forecast_routes.py"
click node_risk_routes "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/risk_predict_routes.py"
click node_dashboard_service "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/dashboard_service.py"
click node_supplier_service "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/supplier_selection_service.py"
click node_dashboard_dataset "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/dashboard_dataset.py"
click node_forecast_service "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/forecast_service.py"
click node_risk_service "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/risk_predict_service.py"
click node_model_registry "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/core/model_registry.py"
click node_order_service "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/order_service.py"
click node_database_layer "https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/core/database.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_frontend_api,node_dashboard_ui,node_supplier_ui,node_profile_ui,node_profile_logic,node_browser toneBlue
class node_app_entry,node_dashboard_routes,node_supplier_routes,node_forecast_routes,node_risk_routes,node_order_service,node_database_layer,node_postgres toneAmber
class node_dashboard_service,node_supplier_service,node_dashboard_dataset toneMint
class node_forecast_service,node_risk_service,node_model_registry toneRose
class node_stakeholder,node_artifacts toneIndigo
```

## Components

### Web experience

- [API client](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/api.js): `app/frontend/src/js/api.js`
- [Dashboard UI](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/pages/dashboardPage.js): `app/frontend/src/js/pages/dashboardPage.js`
- [Supplier selection UI](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/pages/suplier_selectionPage.js): `app/frontend/src/js/pages/suplier_selectionPage.js`
- [Product profile UI](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/pages/product_profilingPage.js): `app/frontend/src/js/pages/product_profilingPage.js`
- [Profile logic](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/frontend/src/js/product-profiling.js): `app/frontend/src/js/product-profiling.js`

### API layer

- [FastAPI app](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/main.py): `app/backend/main.py`
- [Dashboard routes](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/dashboard_routes.py): `app/backend/routes/dashboard_routes.py`
- [Supplier routes](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/supplier_selection_routes.py): `app/backend/routes/supplier_selection_routes.py`
- [Forecast routes](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/forecast_routes.py): `app/backend/routes/forecast_routes.py`
- [Risk routes](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/routes/risk_predict_routes.py): `app/backend/routes/risk_predict_routes.py`
- [Order and risk logs](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/order_service.py): `app/backend/services/order_service.py`
- [Database manager](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/core/database.py): `app/backend/core/database.py`

### Decision analytics

- [Dashboard aggregation](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/dashboard_service.py): `app/backend/services/dashboard_service.py`
- [Supplier ranking](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/supplier_selection_service.py): `app/backend/services/supplier_selection_service.py`
- [Dashboard dataset](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/dashboard_dataset.py): `app/backend/services/dashboard_dataset.py`

### Model serving

- [Demand forecast](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/forecast_service.py): `app/backend/services/forecast_service.py`
- [Risk prediction](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/services/risk_predict_service.py): `app/backend/services/risk_predict_service.py`
- [Model registry](https://github.com/josshua-dsa/neo-horcrox-project/blob/main/app/backend/core/model_registry.py): `app/backend/core/model_registry.py`

### Other components

- **Stakeholder**
- **Browser**
- **PostgreSQL**
- **Data and model artifacts**

## Connections

- Stakeholder → Browser: uses
- Browser → Dashboard UI: opens dashboard
- Browser → Supplier selection UI: selects product
- Supplier selection UI → API client: requests candidates
- Dashboard UI → API client: requests metrics
- Product profile UI → Profile logic: renders profile
- Profile logic → API client: requests forecast
- API client → FastAPI app: REST requests
- FastAPI app → Dashboard routes: dispatches
- FastAPI app → Supplier routes: dispatches
- FastAPI app → Forecast routes: dispatches
- FastAPI app → Risk routes: dispatches
- Dashboard routes → Dashboard aggregation: queries
- Dashboard aggregation → Database manager: queries
- Dashboard aggregation → Dashboard dataset: CSV fallback
- Database manager → PostgreSQL: reads and writes
- Supplier routes → Supplier ranking: queries
- Supplier ranking → Data and model artifacts: reads rankings
- Supplier ranking → Dashboard dataset: reads product data
- Supplier routes → Product profile UI: returns product detail
- Forecast routes → Demand forecast: predicts
- Demand forecast → Model registry: uses loaded model
- Model registry → Data and model artifacts: loads models
- Risk routes → Risk prediction: predicts
- Risk prediction → Model registry: uses loaded model
- Risk routes → Order and risk logs: logs predictions
- Risk routes → Order and risk logs: reads prediction logs
- Order and risk logs → Database manager: stores and queries