# joaoptoaldo/analytics-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/joaoptoaldo/analytics-dashboard
- Repository: https://github.com/joaoptoaldo/analytics-dashboard

## Overview

This is a sales-analytics dashboard: users browse dashboard, analytics, reports, and product listings, with filters and periodic API refreshes; the backend serves aggregated metrics and product data from SQL storage. A separate protected endpoint synchronizes external products. The README documents additional analytics endpoints and deployment database options, but several routers and services were not sampled, so their internal calls are not expanded beyond indexed references.

Main entry points: [`backend/main.py`](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/main.py) (API routes), [`src/App.tsx`](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/App.tsx) (Route shell), [`backend/db.py`](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/db.py) (SQL database), [`hooks/use-dashboard.ts`](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/hooks/use-dashboard.ts) (Dashboard data hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard UI"]
  node_app["Route shell<br/>[App.tsx]"]
  node_dashboard["Dashboard view<br/>[Dashboard.tsx]"]
  node_analytics_view["Analytics view<br/>[Analytics.tsx]"]
  node_reports["Reports view<br/>[Reports.tsx]"]
  node_users_view["Users view<br/>[Users.tsx]"]
  node_settings["Settings view<br/>[Settings.tsx]"]
  node_data_hook["Dashboard data hook<br/>[use-dashboard.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and analytics"]
  node_api_routes["API routes<br/>[main.py]"]
  node_analytics_router["Analytics routes<br/>[analytics.py]"]
  node_analytics_service["Analytics calculations<br/>[analytics.py]"]
  node_metrics_engine["Revenue metric engine<br/>[metrics_engine.py]"]
  node_product_router["Product routes<br/>[products.py]"]
end

subgraph group_data["Product data"]
  node_product_service["Product queries<br/>[products.py]"]
  node_product_model["Product records<br/>[product.py]"]
  node_database[("SQL database<br/>[db.py]")]
end

subgraph group_sync["External synchronization"]
  node_external_router["External product routes<br/>[external.py]"]
  node_sync_router["Protected sync route<br/>[external_sync.py]"]
  node_external_service["External sync service<br/>[external.py]"]
end

node_user(("Dashboard user"))
node_external_source{{"External product source"}}

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_analytics_view
node_app -->|"routes to"| node_reports
node_app -->|"routes to"| node_users_view
node_app -->|"routes to"| node_settings
node_dashboard -->|"requests data"| node_data_hook
node_reports -->|"requests data"| node_data_hook
node_users_view -->|"requests data"| node_data_hook
node_data_hook -->|"fetches through"| node_api_client
node_api_client -->|"calls API"| node_api_routes
node_api_routes -->|"queries"| node_database
node_api_routes -->|"filters records"| node_product_model
node_api_routes -->|"registers routes"| node_analytics_router
node_api_routes -->|"registers routes"| node_product_router
node_api_routes -->|"registers routes"| node_external_router
node_api_routes -->|"registers routes"| node_sync_router
node_api_routes -->|"imports module"| node_metrics_engine
node_analytics_router -.->|"delegates to"| node_analytics_service
node_product_router -->|"delegates to"| node_product_service
node_product_service -->|"queries"| node_database
node_product_service -->|"queries"| node_product_model
node_metrics_engine -->|"opens session"| node_database
node_metrics_engine -->|"aggregates"| node_product_model
node_sync_router -->|"delegates to"| node_external_service
node_sync_router -->|"tracks sync state"| node_database
node_external_source -.->|"supplies products"| node_external_service
node_external_service -->|"writes products"| node_database

click node_app "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/App.tsx"
click node_dashboard "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/Dashboard.tsx"
click node_analytics_view "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Analytics.tsx"
click node_reports "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Reports.tsx"
click node_users_view "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Users.tsx"
click node_settings "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Settings.tsx"
click node_data_hook "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/hooks/use-dashboard.ts"
click node_api_client "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/lib/api.ts"
click node_api_routes "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/main.py"
click node_analytics_router "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/analytics.py"
click node_analytics_service "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/services/analytics.py"
click node_metrics_engine "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/metrics_engine.py"
click node_product_router "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/products.py"
click node_product_service "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/services/products.py"
click node_product_model "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/models/product.py"
click node_database "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/db.py"
click node_external_router "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/external.py"
click node_sync_router "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/external_sync.py"
click node_external_service "https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/services/external.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_app,node_dashboard,node_analytics_view,node_reports,node_users_view,node_settings,node_data_hook,node_api_client,node_user toneBlue
class node_api_routes,node_analytics_router,node_analytics_service,node_metrics_engine,node_product_router toneAmber
class node_product_service,node_product_model,node_database toneMint
class node_external_router,node_sync_router,node_external_service toneRose
class node_external_source toneIndigo
```

## Components

### Dashboard UI

- [Route shell](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/App.tsx): `src/App.tsx`
- [Dashboard view](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/Dashboard.tsx): `src/Dashboard.tsx`
- [Analytics view](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Analytics.tsx): `src/pages/Analytics.tsx`
- [Reports view](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Reports.tsx): `src/pages/Reports.tsx`
- [Users view](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Users.tsx): `src/pages/Users.tsx`
- [Settings view](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/src/pages/Settings.tsx): `src/pages/Settings.tsx`
- [Dashboard data hook](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/hooks/use-dashboard.ts): `hooks/use-dashboard.ts`
- [API client](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/lib/api.ts): `lib/api.ts`

### API and analytics

- [API routes](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/main.py): `backend/main.py`
- [Analytics routes](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/analytics.py): `backend/routers/analytics.py`
- [Analytics calculations](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/services/analytics.py): `backend/services/analytics.py`
- [Revenue metric engine](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/metrics_engine.py): `backend/metrics_engine.py`
- [Product routes](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/products.py): `backend/routers/products.py`

### Product data

- [Product queries](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/services/products.py): `backend/services/products.py`
- [Product records](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/models/product.py): `backend/models/product.py`
- [SQL database](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/db.py): `backend/db.py`

### External synchronization

- [External product routes](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/external.py): `backend/routers/external.py`
- [Protected sync route](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/routers/external_sync.py): `backend/routers/external_sync.py`
- [External sync service](https://github.com/joaoptoaldo/analytics-dashboard/blob/main/backend/services/external.py): `backend/services/external.py`

### Other components

- **Dashboard user**
- **External product source**

## Connections

- Dashboard user → Route shell: opens (evidence: `src/App.tsx`)
- Route shell → Dashboard view: routes to (evidence: `src/App.tsx`)
- Route shell → Analytics view: routes to (evidence: `src/App.tsx`)
- Route shell → Reports view: routes to (evidence: `src/App.tsx`)
- Route shell → Users view: routes to (evidence: `src/App.tsx`)
- Route shell → Settings view: routes to (evidence: `src/App.tsx`)
- Dashboard view → Dashboard data hook: requests data (evidence: `src/Dashboard.tsx`)
- Reports view → Dashboard data hook: requests data (evidence: `src/pages/Reports.tsx`)
- Users view → Dashboard data hook: requests data (evidence: `src/pages/Users.tsx`)
- Dashboard data hook → API client: fetches through (evidence: `hooks/use-dashboard.ts`)
- API client → API routes: calls API (evidence: `README.md`)
- API routes → SQL database: queries (evidence: `backend/main.py`)
- API routes → Product records: filters records (evidence: `backend/main.py`)
- API routes → Analytics routes: registers routes (evidence: `backend/main.py`)
- API routes → Product routes: registers routes (evidence: `backend/main.py`)
- API routes → External product routes: registers routes (evidence: `backend/main.py`)
- API routes → Protected sync route: registers routes (evidence: `backend/main.py`)
- API routes → Revenue metric engine: imports module (evidence: `backend/main.py`)
- Analytics routes → Analytics calculations: delegates to
- Product routes → Product queries: delegates to (evidence: `backend/routers/products.py`)
- Product queries → SQL database: queries (evidence: `backend/services/products.py`)
- Product queries → Product records: queries (evidence: `backend/services/products.py`)
- Revenue metric engine → SQL database: opens session (evidence: `backend/metrics_engine.py`)
- Revenue metric engine → Product records: aggregates (evidence: `backend/metrics_engine.py`)
- Protected sync route → External sync service: delegates to (evidence: `backend/routers/external_sync.py`)
- Protected sync route → SQL database: tracks sync state (evidence: `backend/routers/external_sync.py`)
- External product source → External sync service: supplies products
- External sync service → SQL database: writes products (evidence: `backend/services/external.py`)