How martamateu/smart-tco-calculator works
Project type and purpose
• This is a full-stack “Smart TCO Calculator” for semiconductor materials:
• Frontend: React + TypeScript app (Vite) hosted on GitHub Pages
• Backend: FastAPI service in Python, containerized (Docker) and deployed to Google Cloud Run
• Purpose: Real-time and static data aggregation, TCO calculations, ML model inference, AI/RAG explanations
File structure
• Top-level dirs:
• backend/ → FastAPI code, data sources, ML models, services, routers, utilities, deployment scripts
• components/, contexts/, locales/, services/ → React UI components, i18n, API client
• data/ → static markdown, PDF assets for citations/docs
• config files: Dockerfile, app.yaml, .github/workflows/deploy.yml, tsconfig.json, vite.config.ts, package.json
• Patterns:
• Backend follows layered architecture: routers (API endpoints) → services (business logic) → data_access → data/models
• Data pipeline automated via Cloud Scheduler + scheduler-triggered admin endpoints
• ML inference via a trained Random Forest (tco_random_forest.pkl)
• RAG knowledge base loader + retriever
Key architecture points from README
• Cloud Run hosts FastAPI, reads from Cloud Storage (GCS) bucket for cache & static data
• Cloud Scheduler jobs trigger price/material refresh endpoints
• Frontend fetches from backend’s public API (/api/materials, /api/regions, /api/predict, etc.)
• CI/CD: GitHub Actions deploys React app to GH Pages, backend deployed via gcloud
• External systems: ENTSO-E API, EIA API, Materials Project API, Google Gemini AI
Final recommendations
• Be detailed: break out major routers (e.g., /api/predict, /api/explain, /api/admin) or group by feature
• Asynchronous flows (scheduler, background ML training, data extraction scripts)