sjoshua06/blueprints

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.