# mansi084/trendcast-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mansi084/trendcast-ai
- Repository: https://github.com/mansi084/trendcast-ai

## Overview

TrendCast AI turns seller sales history and contextual signals into SKU-level demand forecasts. Sellers upload sales or calendar data through the dashboard; the API stores it, and the upload watcher or scheduled batch pipeline prepares features, trains/selects models, generates forecasts, and publishes them for dashboard display. Signal producers collect weather, holidays, trends, macroeconomic, local-event, and opt-in marketplace data. The README documents the broad pipeline; sampled source confirms producer dispatch, Kafka ingestion, Supabase sales ingestion, API authentication, calendar parsing, and inference behavior, but not every subsystem’s wiring.

Main entry points: [`backend/app/routers`](https://github.com/mansi084/trendcast-ai/tree/main/backend/app/routers) (REST endpoints), [`frontend/src/app`](https://github.com/mansi084/trendcast-ai/tree/main/frontend/src/app) (Next.js dashboard), [`frontend/src/lib/api.ts`](https://github.com/mansi084/trendcast-ai/blob/main/frontend/src/lib/api.ts) (API client), [`pipeline/jobs/gold_features.py`](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/gold_features.py) (Gold features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Seller experience"]
  node_dashboard["Next.js dashboard"]
  node_ui_components["Forecast UI"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and data access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_api_routes["REST endpoints"]
  node_calendar_parser["Calendar parser<br/>[calendar_parser.py]"]
  node_supabase[("Supabase Postgres")]
end

subgraph group_signals["Signal collection"]
  node_producer_runner["Producer runner<br/>[runner.py]"]
  node_signal_producers["Signal producers"]
  node_kafka["Kafka topics"]
end

subgraph group_pipeline["Data pipeline"]
  node_upload_watcher["Upload watcher<br/>[watch_uploads.py]"]
  node_bronze["Bronze ingestion<br/>[bronze_ingest.py]"]
  node_bronze_supabase["Sales ingestion"]
  node_silver["Silver transforms"]
  node_gold["Gold features<br/>[gold_features.py]"]
  node_feature_transforms["Feature transforms<br/>[features.py]"]
  node_publish["Forecast publishing"]
end

subgraph group_forecasting["Forecasting"]
  node_training["Model training<br/>[train.py]"]
  node_backtest["Backtesting<br/>[backtest.py]"]
  node_inference["Batch inference<br/>[infer.py]"]
  node_model["Forecast models<br/>[forecaster.py]"]
end

node_seller(("Seller"))
node_supabase_auth["Supabase Auth"]
node_signal_sources["External signal feeds"]

node_seller -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_frontend_api
node_dashboard -->|"renders"| node_ui_components
node_dashboard -->|"authenticates"| node_supabase_auth
node_frontend_api -->|"calls API"| node_api_app
node_api_app -->|"dispatches"| node_api_routes
node_api_routes -->|"verifies tokens"| node_auth
node_auth -->|"checks signing keys"| node_supabase_auth
node_api_routes -->|"reads and writes"| node_supabase
node_api_routes -->|"parses calendars"| node_calendar_parser
node_seller -->|"uploads sales"| node_api_routes
node_upload_watcher -->|"polls uploads"| node_supabase
node_upload_watcher -->|"triggers pipeline"| node_bronze_supabase
node_supabase -->|"reads sales"| node_bronze_supabase
node_signal_sources -->|"provide signals"| node_signal_producers
node_producer_runner -->|"dispatches"| node_signal_producers
node_signal_producers -->|"publishes records"| node_kafka
node_producer_runner -->|"publishes health"| node_kafka
node_kafka -->|"streams records"| node_bronze
node_bronze -->|"writes bronze data"| node_silver
node_bronze_supabase -->|"writes bronze data"| node_silver
node_silver -->|"transforms data"| node_gold
node_gold -->|"builds features"| node_feature_transforms
node_gold -->|"supplies features"| node_training
node_training -->|"evaluates models"| node_backtest
node_training -->|"provides trained models"| node_inference
node_inference -->|"generates forecasts"| node_model
node_inference -->|"writes forecast rows"| node_publish
node_publish -->|"publishes forecasts"| node_supabase
node_frontend_api -->|"loads dashboard data"| node_supabase

click node_dashboard "https://github.com/mansi084/trendcast-ai/tree/main/frontend/src/app"
click node_ui_components "https://github.com/mansi084/trendcast-ai/tree/main/frontend/src/components"
click node_frontend_api "https://github.com/mansi084/trendcast-ai/blob/main/frontend/src/lib/api.ts"
click node_api_app "https://github.com/mansi084/trendcast-ai/blob/main/backend/app/main.py"
click node_auth "https://github.com/mansi084/trendcast-ai/blob/main/backend/app/auth.py"
click node_api_routes "https://github.com/mansi084/trendcast-ai/tree/main/backend/app/routers"
click node_calendar_parser "https://github.com/mansi084/trendcast-ai/blob/main/backend/app/services/calendar_parser.py"
click node_upload_watcher "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/watch_uploads.py"
click node_producer_runner "https://github.com/mansi084/trendcast-ai/blob/main/producers/runner.py"
click node_signal_producers "https://github.com/mansi084/trendcast-ai/tree/main/producers"
click node_bronze "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/bronze_ingest.py"
click node_bronze_supabase "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/bronze_ingest_supabase.py"
click node_silver "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/silver_transform.py"
click node_gold "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/gold_features.py"
click node_feature_transforms "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/transforms/features.py"
click node_training "https://github.com/mansi084/trendcast-ai/blob/main/ml/train.py"
click node_backtest "https://github.com/mansi084/trendcast-ai/blob/main/ml/backtest.py"
click node_inference "https://github.com/mansi084/trendcast-ai/blob/main/ml/infer.py"
click node_model "https://github.com/mansi084/trendcast-ai/blob/main/ml/forecaster.py"
click node_publish "https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/publish_to_supabase.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_dashboard,node_ui_components,node_frontend_api toneBlue
class node_api_app,node_auth,node_api_routes,node_calendar_parser,node_supabase toneAmber
class node_producer_runner,node_signal_producers,node_kafka toneMint
class node_upload_watcher,node_bronze,node_bronze_supabase,node_silver,node_gold,node_feature_transforms,node_publish toneRose
class node_training,node_backtest,node_inference,node_model,node_seller,node_supabase_auth,node_signal_sources toneIndigo
```

## Components

### Seller experience

- [Next.js dashboard](https://github.com/mansi084/trendcast-ai/tree/main/frontend/src/app): `frontend/src/app`
- [Forecast UI](https://github.com/mansi084/trendcast-ai/tree/main/frontend/src/components): `frontend/src/components`
- [API client](https://github.com/mansi084/trendcast-ai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and data access

- [FastAPI app](https://github.com/mansi084/trendcast-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [JWT authentication](https://github.com/mansi084/trendcast-ai/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [REST endpoints](https://github.com/mansi084/trendcast-ai/tree/main/backend/app/routers): `backend/app/routers`
- [Calendar parser](https://github.com/mansi084/trendcast-ai/blob/main/backend/app/services/calendar_parser.py): `backend/app/services/calendar_parser.py`
- **Supabase Postgres**

### Signal collection

- [Producer runner](https://github.com/mansi084/trendcast-ai/blob/main/producers/runner.py): `producers/runner.py`
- [Signal producers](https://github.com/mansi084/trendcast-ai/tree/main/producers): `producers`
- **Kafka topics**

### Data pipeline

- [Upload watcher](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/watch_uploads.py): `pipeline/watch_uploads.py`
- [Bronze ingestion](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/bronze_ingest.py): `pipeline/jobs/bronze_ingest.py`
- [Sales ingestion](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/bronze_ingest_supabase.py): `pipeline/jobs/bronze_ingest_supabase.py`
- [Silver transforms](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/silver_transform.py): `pipeline/jobs/silver_transform.py`
- [Gold features](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/gold_features.py): `pipeline/jobs/gold_features.py`
- [Feature transforms](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/transforms/features.py): `pipeline/transforms/features.py`
- [Forecast publishing](https://github.com/mansi084/trendcast-ai/blob/main/pipeline/jobs/publish_to_supabase.py): `pipeline/jobs/publish_to_supabase.py`

### Forecasting

- [Model training](https://github.com/mansi084/trendcast-ai/blob/main/ml/train.py): `ml/train.py`
- [Backtesting](https://github.com/mansi084/trendcast-ai/blob/main/ml/backtest.py): `ml/backtest.py`
- [Batch inference](https://github.com/mansi084/trendcast-ai/blob/main/ml/infer.py): `ml/infer.py`
- [Forecast models](https://github.com/mansi084/trendcast-ai/blob/main/ml/forecaster.py): `ml/forecaster.py`

### Other components

- **Seller**
- **Supabase Auth**
- **External signal feeds**

## Connections

- Seller → Next.js dashboard: uses
- Next.js dashboard → API client: requests data
- Next.js dashboard → Forecast UI: renders
- Next.js dashboard → Supabase Auth: authenticates
- API client → FastAPI app: calls API
- FastAPI app → REST endpoints: dispatches
- REST endpoints → JWT authentication: verifies tokens
- JWT authentication → Supabase Auth: checks signing keys
- REST endpoints → Supabase Postgres: reads and writes
- REST endpoints → Calendar parser: parses calendars
- Seller → REST endpoints: uploads sales
- Upload watcher → Supabase Postgres: polls uploads
- Upload watcher → Sales ingestion: triggers pipeline
- Supabase Postgres → Sales ingestion: reads sales
- External signal feeds → Signal producers: provide signals
- Producer runner → Signal producers: dispatches
- Signal producers → Kafka topics: publishes records
- Producer runner → Kafka topics: publishes health
- Kafka topics → Bronze ingestion: streams records
- Bronze ingestion → Silver transforms: writes bronze data
- Sales ingestion → Silver transforms: writes bronze data
- Silver transforms → Gold features: transforms data
- Gold features → Feature transforms: builds features
- Gold features → Model training: supplies features
- Model training → Backtesting: evaluates models
- Model training → Batch inference: provides trained models
- Batch inference → Forecast models: generates forecasts
- Batch inference → Forecast publishing: writes forecast rows
- Forecast publishing → Supabase Postgres: publishes forecasts
- API client → Supabase Postgres: loads dashboard data