# prsaveliy/chart-alchemy architecture

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

- Interactive diagram: https://gitdiagram.com/prsaveliy/chart-alchemy
- Repository: https://github.com/prsaveliy/chart-alchemy

## Overview

ChartAlchemy is a web application for creating and managing AI-generated, dataset-derived, and manually configured charts. Users can also register or sign in with email/password or Google. The frontend routes users to chart and account experiences; the backend exposes authenticated chart and account APIs, with chart generation and persistence handled by services and repositories. Dataset parsing and chart-option construction form a distinct internal stage. Source excerpts establish backend routing and service calls; frontend-to-API wiring and several integrations are not shown, so those relationships are left unasserted.

Main entry points: [`frontend/src/main.tsx`](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/main.tsx) (Page routing), [`backend/src/services/oauth.service.ts`](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/oauth.service.ts) (Google OAuth), [`frontend/src/pages/chart/new-chart.tsx`](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/new-chart.tsx) (Chart workflow), [`backend/src/app.ts`](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/app.ts) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web_routes["Page routing<br/>[main.tsx]"]
  node_dashboard["Chart dashboard<br/>[dashboard.tsx]"]
  node_new_chart["Chart workflow<br/>[new-chart.tsx]"]
  node_ai_chart_ui["AI chart UI<br/>[ai-chart.tsx]"]
  node_dataset_chart_ui["Dataset chart UI<br/>[dataset-chart.tsx]"]
  node_manual_chart_ui["Manual chart UI<br/>[manual-chart.tsx]"]
  node_chart_view["Chart view<br/>[chart.tsx]"]
  node_auth_ui["Account screens<br/>[signup.tsx]"]
  node_google_ui["Google sign-in UI<br/>[google-login.tsx]"]
end

subgraph group_api["Backend API"]
  node_api_app["API application<br/>[app.ts]"]
  node_chart_routes["Chart routes<br/>[chart.routes.ts]"]
  node_chart_controller["Chart controller"]
  node_auth_routes["Account routes<br/>[auth.routes.ts]"]
  node_auth_controller["Account controller<br/>[auth.controller.ts]"]
  node_oauth_controller["OAuth controller"]
end

subgraph group_charts["Chart generation"]
  node_chart_service["Chart service<br/>[chart.service.ts]"]
  node_dataset_service["Dataset processing"]
  node_gemini_service["AI generation<br/>[gemini.service.ts]"]
end

subgraph group_identity["Identity and accounts"]
  node_account_service["Account service<br/>[auth.service.ts]"]
  node_oauth_service["Google OAuth<br/>[oauth.service.ts]"]
  node_token_service["Token service"]
end

subgraph group_persistence["Persistence"]
  node_chart_repository["Chart repository"]
  node_user_repository["User repository<br/>[user.repository.ts]"]
end

node_person(("Chart user"))
node_database[("PostgreSQL")]
node_google["Google identity"]

node_person -.->|"uses"| node_web_routes
node_web_routes -->|"routes to"| node_dashboard
node_web_routes -->|"routes to"| node_new_chart
node_web_routes -->|"routes to"| node_chart_view
node_web_routes -->|"routes to"| node_auth_ui
node_new_chart -.->|"offers"| node_ai_chart_ui
node_new_chart -.->|"offers"| node_dataset_chart_ui
node_new_chart -.->|"offers"| node_manual_chart_ui
node_api_app -->|"registers"| node_chart_routes
node_api_app -->|"registers"| node_auth_routes
node_chart_routes -->|"dispatches"| node_chart_controller
node_auth_routes -->|"dispatches"| node_auth_controller
node_chart_controller -->|"calls"| node_chart_service
node_chart_controller -->|"calls"| node_dataset_service
node_chart_service -->|"uses"| node_chart_repository
node_chart_service -.->|"delegates generation"| node_gemini_service
node_auth_controller -->|"calls"| node_account_service
node_auth_controller -->|"uses"| node_token_service
node_account_service -->|"uses"| node_user_repository
node_account_service -->|"uses"| node_token_service
node_api_app -->|"registers OAuth routes"| node_oauth_controller
node_oauth_controller -->|"calls"| node_oauth_service
node_oauth_service -->|"exchanges code"| node_google
node_oauth_service -->|"looks up users"| node_user_repository
node_oauth_service -->|"reassigns charts"| node_chart_repository
node_oauth_service -->|"issues tokens"| node_token_service
node_chart_repository -.->|"reads and writes"| node_database
node_user_repository -.->|"reads and writes"| node_database

click node_web_routes "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/main.tsx"
click node_dashboard "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/dashboard.tsx"
click node_new_chart "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/new-chart.tsx"
click node_ai_chart_ui "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/ai-chart.tsx"
click node_dataset_chart_ui "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/dataset-chart.tsx"
click node_manual_chart_ui "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/manual-chart.tsx"
click node_chart_view "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/chart.tsx"
click node_auth_ui "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/auth/signup.tsx"
click node_google_ui "https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/auth/google-login.tsx"
click node_api_app "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/app.ts"
click node_chart_routes "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/routes/chart.routes.ts"
click node_chart_controller "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/controllers/chart.controller.ts"
click node_auth_routes "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/routes/auth.routes.ts"
click node_auth_controller "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/controllers/auth.controller.ts"
click node_oauth_controller "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/controllers/oauth.controller.ts"
click node_chart_service "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/chart.service.ts"
click node_dataset_service "https://github.com/prsaveliy/chart-alchemy/tree/master/backend/src/services/dataset"
click node_gemini_service "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/gemini.service.ts"
click node_chart_repository "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/repositories/chart.repository.ts"
click node_account_service "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/auth.service.ts"
click node_oauth_service "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/oauth.service.ts"
click node_token_service "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/refreshToken.service.ts"
click node_user_repository "https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/repositories/user.repository.ts"

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_web_routes,node_dashboard,node_new_chart,node_ai_chart_ui,node_dataset_chart_ui,node_manual_chart_ui,node_chart_view,node_auth_ui,node_google_ui,node_person toneBlue
class node_api_app,node_chart_routes,node_chart_controller,node_auth_routes,node_auth_controller,node_oauth_controller,node_database toneAmber
class node_chart_service,node_dataset_service,node_gemini_service toneMint
class node_account_service,node_oauth_service,node_token_service toneRose
class node_chart_repository,node_user_repository,node_google toneIndigo
```

## Components

### Web application

- [Page routing](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Chart dashboard](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/dashboard.tsx): `frontend/src/pages/dashboard.tsx`
- [Chart workflow](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/new-chart.tsx): `frontend/src/pages/chart/new-chart.tsx`
- [AI chart UI](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/ai-chart.tsx): `frontend/src/pages/chart/ai-chart.tsx`
- [Dataset chart UI](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/dataset-chart.tsx): `frontend/src/pages/chart/dataset-chart.tsx`
- [Manual chart UI](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/manual-chart.tsx): `frontend/src/pages/chart/manual-chart.tsx`
- [Chart view](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/chart/chart.tsx): `frontend/src/pages/chart/chart.tsx`
- [Account screens](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/auth/signup.tsx): `frontend/src/pages/auth/signup.tsx`
- [Google sign-in UI](https://github.com/prsaveliy/chart-alchemy/blob/master/frontend/src/pages/auth/google-login.tsx): `frontend/src/pages/auth/google-login.tsx`

### Backend API

- [API application](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/app.ts): `backend/src/app.ts`
- [Chart routes](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/routes/chart.routes.ts): `backend/src/routes/chart.routes.ts`
- [Chart controller](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/controllers/chart.controller.ts): `backend/src/controllers/chart.controller.ts`
- [Account routes](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [Account controller](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/controllers/auth.controller.ts): `backend/src/controllers/auth.controller.ts`
- [OAuth controller](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/controllers/oauth.controller.ts): `backend/src/controllers/oauth.controller.ts`

### Chart generation

- [Chart service](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/chart.service.ts): `backend/src/services/chart.service.ts`
- [Dataset processing](https://github.com/prsaveliy/chart-alchemy/tree/master/backend/src/services/dataset): `backend/src/services/dataset`
- [AI generation](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/gemini.service.ts): `backend/src/services/gemini.service.ts`

### Identity and accounts

- [Account service](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [Google OAuth](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/oauth.service.ts): `backend/src/services/oauth.service.ts`
- [Token service](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/services/refreshToken.service.ts): `backend/src/services/refreshToken.service.ts`

### Persistence

- [Chart repository](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/repositories/chart.repository.ts): `backend/src/repositories/chart.repository.ts`
- [User repository](https://github.com/prsaveliy/chart-alchemy/blob/master/backend/src/repositories/user.repository.ts): `backend/src/repositories/user.repository.ts`

### Other components

- **Chart user**
- **PostgreSQL**
- **Google identity**

## Connections

- Chart user → Page routing: uses
- Page routing → Chart dashboard: routes to (evidence: `frontend/src/main.tsx`)
- Page routing → Chart workflow: routes to (evidence: `frontend/src/main.tsx`)
- Page routing → Chart view: routes to (evidence: `frontend/src/main.tsx`)
- Page routing → Account screens: routes to (evidence: `frontend/src/main.tsx`)
- Chart workflow → AI chart UI: offers
- Chart workflow → Dataset chart UI: offers
- Chart workflow → Manual chart UI: offers
- API application → Chart routes: registers (evidence: `backend/src/app.ts`)
- API application → Account routes: registers (evidence: `backend/src/app.ts`)
- Chart routes → Chart controller: dispatches (evidence: `backend/src/routes/chart.routes.ts`)
- Account routes → Account controller: dispatches (evidence: `backend/src/routes/auth.routes.ts`)
- Chart controller → Chart service: calls (evidence: `backend/src/controllers/chart.controller.ts`)
- Chart controller → Dataset processing: calls (evidence: `backend/src/controllers/chart.controller.ts`)
- Chart service → Chart repository: uses (evidence: `backend/src/services/chart.service.ts`)
- Chart service → AI generation: delegates generation
- Account controller → Account service: calls (evidence: `backend/src/controllers/auth.controller.ts`)
- Account controller → Token service: uses (evidence: `backend/src/controllers/auth.controller.ts`)
- Account service → User repository: uses (evidence: `backend/src/services/auth.service.ts`)
- Account service → Token service: uses (evidence: `backend/src/services/auth.service.ts`)
- API application → OAuth controller: registers OAuth routes (evidence: `backend/src/app.ts`)
- OAuth controller → Google OAuth: calls (evidence: `backend/src/controllers/oauth.controller.ts`)
- Google OAuth → Google identity: exchanges code (evidence: `backend/src/services/oauth.service.ts`)
- Google OAuth → User repository: looks up users (evidence: `backend/src/services/oauth.service.ts`)
- Google OAuth → Chart repository: reassigns charts (evidence: `backend/src/services/oauth.service.ts`)
- Google OAuth → Token service: issues tokens (evidence: `backend/src/services/oauth.service.ts`)
- Chart repository → PostgreSQL: reads and writes
- User repository → PostgreSQL: reads and writes
