# dnosoro/openstore architecture

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

- Interactive diagram: https://gitdiagram.com/dnosoro/openstore
- Repository: https://github.com/dnosoro/openstore

## Overview

OpenStore is a data analytics application with a CSV-to-PostgreSQL data path and a web dashboard for both monthly revenue and natural-language analytics queries. The query endpoint generates SQL through OpenRouter, validates it, executes it, and returns rows for display; other endpoints expose prebuilt analytics views. The pipeline modules also implement raw-data checks and raw-to-staging transformations, but the sampled sources do not establish how those jobs are orchestrated or how core transformations consume staging data. No README content was provided.

Main entry points: [`src/api/main.py`](https://github.com/dnosoro/openstore/blob/main/src/api/main.py) (FastAPI Routes), [`src/ingestion/upload_to_seaweed.py`](https://github.com/dnosoro/openstore/blob/main/src/ingestion/upload_to_seaweed.py) (CSV Uploader), [`src/loading/load_to_postgres.py`](https://github.com/dnosoro/openstore/blob/main/src/loading/load_to_postgres.py) (Raw Loader), [`src/api/llm_service.py`](https://github.com/dnosoro/openstore/blob/main/src/api/llm_service.py) (SQL Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data Ingestion"]
  node_csv_sources(("CSV Sources"))
  node_uploader["CSV Uploader"]
  node_seaweed[("SeaweedFS")]
  node_raw_loader["Raw Loader"]
end

subgraph group_prep["Data Preparation"]
  node_quality["Raw Data Checks<br/>[validate_data.py]"]
  node_staging["Staging Transforms"]
  node_core_transform["Core Transforms<br/>[core_transform.py]"]
end

subgraph group_serve["Analytics Serving"]
  node_views["Analytics Views<br/>[create_views.py]"]
  node_api["FastAPI Routes<br/>[main.py]"]
  node_llm["SQL Generation<br/>[llm_service.py]"]
  node_guardrails["SQL Guardrails<br/>[guardrails.py]"]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Analytics Dashboard<br/>[page.tsx]"]
end

node_postgres[("PostgreSQL")]
node_openrouter["OpenRouter"]
node_browser(("Dashboard User"))

node_csv_sources -->|"supplies CSVs"| node_uploader
node_uploader -->|"uploads files"| node_seaweed
node_seaweed -->|"serves CSVs"| node_raw_loader
node_raw_loader -->|"writes raw tables"| node_postgres
node_quality -->|"reads raw tables"| node_postgres
node_staging -->|"reads raw; writes staging"| node_postgres
node_views -->|"creates analytics views"| node_postgres
node_api -->|"requests SQL"| node_llm
node_llm -->|"requests completion"| node_openrouter
node_api -->|"validates and executes"| node_guardrails
node_guardrails -->|"runs safe query"| node_postgres
node_api -->|"queries analytics views"| node_postgres
node_browser -->|"uses dashboard"| node_dashboard
node_dashboard -->|"fetches analytics"| node_api

click node_uploader "https://github.com/dnosoro/openstore/blob/main/src/ingestion/upload_to_seaweed.py"
click node_raw_loader "https://github.com/dnosoro/openstore/blob/main/src/loading/load_to_postgres.py"
click node_quality "https://github.com/dnosoro/openstore/blob/main/src/quality/validate_data.py"
click node_staging "https://github.com/dnosoro/openstore/blob/main/src/transform/staging_transform.py"
click node_core_transform "https://github.com/dnosoro/openstore/blob/main/src/transform/core_transform.py"
click node_views "https://github.com/dnosoro/openstore/blob/main/src/analytics/create_views.py"
click node_api "https://github.com/dnosoro/openstore/blob/main/src/api/main.py"
click node_llm "https://github.com/dnosoro/openstore/blob/main/src/api/llm_service.py"
click node_guardrails "https://github.com/dnosoro/openstore/blob/main/src/api/guardrails.py"
click node_dashboard "https://github.com/dnosoro/openstore/blob/main/frontend/src/app/page.tsx"

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_csv_sources,node_uploader,node_seaweed,node_raw_loader,node_browser toneBlue
class node_quality,node_staging,node_core_transform,node_postgres toneAmber
class node_views,node_api,node_llm,node_guardrails,node_openrouter toneMint
class node_dashboard toneRose
```

## Components

### Data Ingestion

- **CSV Sources**
- [CSV Uploader](https://github.com/dnosoro/openstore/blob/main/src/ingestion/upload_to_seaweed.py): `src/ingestion/upload_to_seaweed.py`
- **SeaweedFS**
- [Raw Loader](https://github.com/dnosoro/openstore/blob/main/src/loading/load_to_postgres.py): `src/loading/load_to_postgres.py`

### Data Preparation

- [Raw Data Checks](https://github.com/dnosoro/openstore/blob/main/src/quality/validate_data.py): `src/quality/validate_data.py`
- [Staging Transforms](https://github.com/dnosoro/openstore/blob/main/src/transform/staging_transform.py): `src/transform/staging_transform.py`
- [Core Transforms](https://github.com/dnosoro/openstore/blob/main/src/transform/core_transform.py): `src/transform/core_transform.py`

### Analytics Serving

- [Analytics Views](https://github.com/dnosoro/openstore/blob/main/src/analytics/create_views.py): `src/analytics/create_views.py`
- [FastAPI Routes](https://github.com/dnosoro/openstore/blob/main/src/api/main.py): `src/api/main.py`
- [SQL Generation](https://github.com/dnosoro/openstore/blob/main/src/api/llm_service.py): `src/api/llm_service.py`
- [SQL Guardrails](https://github.com/dnosoro/openstore/blob/main/src/api/guardrails.py): `src/api/guardrails.py`

### Dashboard

- [Analytics Dashboard](https://github.com/dnosoro/openstore/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`

### Other components

- **PostgreSQL**
- **OpenRouter**
- **Dashboard User**

## Connections

- CSV Sources → CSV Uploader: supplies CSVs (evidence: `src/ingestion/upload_to_seaweed.py`)
- CSV Uploader → SeaweedFS: uploads files (evidence: `src/ingestion/upload_to_seaweed.py`)
- SeaweedFS → Raw Loader: serves CSVs (evidence: `src/loading/load_to_postgres.py`)
- Raw Loader → PostgreSQL: writes raw tables (evidence: `src/loading/load_to_postgres.py`)
- Raw Data Checks → PostgreSQL: reads raw tables (evidence: `src/quality/validate_data.py`)
- Staging Transforms → PostgreSQL: reads raw; writes staging (evidence: `src/transform/staging_transform.py`)
- Analytics Views → PostgreSQL: creates analytics views (evidence: `src/analytics/create_views.py`)
- FastAPI Routes → SQL Generation: requests SQL (evidence: `src/api/main.py`)
- SQL Generation → OpenRouter: requests completion (evidence: `src/api/llm_service.py`)
- FastAPI Routes → SQL Guardrails: validates and executes (evidence: `src/api/main.py`)
- SQL Guardrails → PostgreSQL: runs safe query (evidence: `src/api/guardrails.py`)
- FastAPI Routes → PostgreSQL: queries analytics views (evidence: `src/api/main.py`)
- Dashboard User → Analytics Dashboard: uses dashboard (evidence: `frontend/src/app/page.tsx`)
- Analytics Dashboard → FastAPI Routes: fetches analytics (evidence: `frontend/src/app/page.tsx`)
