# meyyappan-al/student_budget_analytics architecture

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

- Interactive diagram: https://gitdiagram.com/meyyappan-al/student_budget_analytics
- Repository: https://github.com/meyyappan-al/student_budget_analytics

## Overview

Student Budget Analytics cleans survey data, derives financial measures, validates and loads the result into PostgreSQL, then exposes checked analytics through a deterministic plain-English assistant. The main workflow is documented in the README; source excerpts additionally confirm pipeline orchestration, quality verification and database-loading responsibilities. Assistant capabilities are implemented in one script, so several nodes share its path. Relationships for unsampled schema and analytics-view definitions are shown only where the README documents them.

Main entry points: [`src/pipeline.py`](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/pipeline.py) (Pipeline runner), [`ai/assistant.py`](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py) (Question parser), [`Data/processed/transformed_student_budget.csv`](https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/processed/transformed_student_budget.csv) (Analysis dataset), [`src/data_loader.py`](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/data_loader.py) (CSV loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_cleaner["Survey cleaning<br/>[cleaner.py]"]
  node_cleaned["Cleaned dataset"]
  node_transformer["Metric transformation<br/>[transformer.py]"]
  node_transformed["Analysis dataset"]
end

subgraph group_load["Quality and storage"]
  node_pipeline["Pipeline runner<br/>[pipeline.py]"]
  node_quality["Quality checks<br/>[data_quality.py]"]
  node_loader["CSV loader<br/>[data_loader.py]"]
  node_database["Database access<br/>[database.py]"]
  node_schema["Table schema<br/>[schema.sql]"]
end

subgraph group_analytics["Assistant analytics"]
  node_view["Analytics view<br/>[analytics.sql]"]
  node_intent["Question parser<br/>[assistant.py]"]
  node_guard["SQL safety guard<br/>[assistant.py]"]
  node_query["Query execution<br/>[assistant.py]"]
  node_offline["CSV query engine<br/>[assistant.py]"]
  node_insights["Dataset insights<br/>[assistant.py]"]
  node_explainer["Failure and quality explanations<br/>[assistant.py]"]
end

subgraph group_interface["User interfaces"]
  node_cli["Assistant commands<br/>[assistant.py]"]
  node_chat["Interactive chat<br/>[assistant.py]"]
  node_http["HTTP interface<br/>[assistant.py]"]
end

node_analyst(("Analyst"))
node_raw["Survey workbook"]
node_postgres[("PostgreSQL")]
node_answer["Answer"]

node_pipeline -->|"runs cleaning"| node_cleaner
node_raw -->|"reads workbook"| node_cleaner
node_cleaner -->|"writes CSV"| node_cleaned
node_pipeline -->|"runs transformation"| node_transformer
node_cleaned -->|"reads cleaned data"| node_transformer
node_transformer -->|"writes metrics"| node_transformed
node_pipeline -->|"runs quality gate"| node_quality
node_quality -->|"checks dataset"| node_transformed
node_pipeline -->|"runs load stage"| node_loader
node_loader -->|"loads CSV"| node_transformed
node_pipeline -->|"applies schema"| node_database
node_database -->|"executes DDL"| node_schema
node_loader -->|"bulk loads"| node_postgres
node_schema -->|"defines table"| node_postgres
node_view -->|"defines view"| node_postgres
node_analyst -->|"asks question"| node_cli
node_analyst -->|"starts session"| node_chat
node_analyst -->|"sends request"| node_http
node_cli -->|"parses question"| node_intent
node_chat -->|"parses question"| node_intent
node_http -->|"routes question"| node_intent
node_intent -->|"validates SQL"| node_guard
node_guard -->|"permits query"| node_query
node_query -->|"queries view"| node_view
node_query -->|"executes SELECT"| node_postgres
node_intent -->|"selects offline mode"| node_offline
node_offline -->|"reads CSV"| node_transformed
node_cli -->|"requests insights"| node_insights
node_cli -->|"explains findings"| node_explainer
node_analyst -.->|"submits log or report"| node_explainer
node_query -.->|"returns results"| node_answer
node_offline -.->|"returns results"| node_answer
node_insights -.->|"reports overview"| node_answer
node_explainer -.->|"explains findings"| node_answer
node_answer -.->|"presents answer"| node_analyst

click node_raw "https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/Student%20Budget%20Analytics%20Raw%20Data.xlsx"
click node_cleaner "https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/cleaner.py"
click node_cleaned "https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/processed/cleaned_student_budget.csv"
click node_transformer "https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/transformer.py"
click node_transformed "https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/processed/transformed_student_budget.csv"
click node_pipeline "https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/pipeline.py"
click node_quality "https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/data_quality.py"
click node_loader "https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/data_loader.py"
click node_database "https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/database.py"
click node_schema "https://github.com/meyyappan-al/student_budget_analytics/blob/main/sql/schema.sql"
click node_view "https://github.com/meyyappan-al/student_budget_analytics/blob/main/sql/analytics.sql"
click node_intent "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_guard "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_query "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_offline "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_insights "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_explainer "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_cli "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_chat "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py"
click node_http "https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.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_cleaner,node_cleaned,node_transformer,node_transformed toneBlue
class node_pipeline,node_quality,node_loader,node_database,node_schema,node_postgres toneAmber
class node_view,node_intent,node_guard,node_query,node_offline,node_insights,node_explainer toneMint
class node_cli,node_chat,node_http toneRose
class node_analyst,node_answer toneIndigo
class node_raw toneTeal
```

## Components

### Data preparation

- [Survey cleaning](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/cleaner.py): `src/cleaner.py`
- [Cleaned dataset](https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/processed/cleaned_student_budget.csv): `Data/processed/cleaned_student_budget.csv`
- [Metric transformation](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/transformer.py): `src/transformer.py`
- [Analysis dataset](https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/processed/transformed_student_budget.csv): `Data/processed/transformed_student_budget.csv`

### Quality and storage

- [Pipeline runner](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/pipeline.py): `src/pipeline.py`
- [Quality checks](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/data_quality.py): `src/data_quality.py`
- [CSV loader](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/data_loader.py): `src/data_loader.py`
- [Database access](https://github.com/meyyappan-al/student_budget_analytics/blob/main/src/database.py): `src/database.py`
- [Table schema](https://github.com/meyyappan-al/student_budget_analytics/blob/main/sql/schema.sql): `sql/schema.sql`

### Assistant analytics

- [Analytics view](https://github.com/meyyappan-al/student_budget_analytics/blob/main/sql/analytics.sql): `sql/analytics.sql`
- [Question parser](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [SQL safety guard](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [Query execution](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [CSV query engine](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [Dataset insights](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [Failure and quality explanations](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`

### User interfaces

- [Assistant commands](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [Interactive chat](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`
- [HTTP interface](https://github.com/meyyappan-al/student_budget_analytics/blob/main/ai/assistant.py): `ai/assistant.py`

### Other components

- **Analyst**
- [Survey workbook](https://github.com/meyyappan-al/student_budget_analytics/blob/main/Data/Student%20Budget%20Analytics%20Raw%20Data.xlsx): `Data/Student Budget Analytics Raw Data.xlsx`
- **PostgreSQL**
- **Answer**

## Connections

- Pipeline runner → Survey cleaning: runs cleaning (evidence: `README.md`)
- Survey workbook → Survey cleaning: reads workbook (evidence: `README.md`)
- Survey cleaning → Cleaned dataset: writes CSV (evidence: `README.md`)
- Pipeline runner → Metric transformation: runs transformation (evidence: `README.md`)
- Cleaned dataset → Metric transformation: reads cleaned data (evidence: `README.md`)
- Metric transformation → Analysis dataset: writes metrics (evidence: `README.md`)
- Pipeline runner → Quality checks: runs quality gate (evidence: `src/pipeline.py`)
- Quality checks → Analysis dataset: checks dataset (evidence: `README.md`)
- Pipeline runner → CSV loader: runs load stage (evidence: `src/pipeline.py`)
- CSV loader → Analysis dataset: loads CSV (evidence: `README.md`)
- Pipeline runner → Database access: applies schema (evidence: `src/pipeline.py`)
- Database access → Table schema: executes DDL (evidence: `README.md`)
- CSV loader → PostgreSQL: bulk loads (evidence: `README.md`)
- Table schema → PostgreSQL: defines table (evidence: `README.md`)
- Analytics view → PostgreSQL: defines view (evidence: `README.md`)
- Analyst → Assistant commands: asks question (evidence: `README.md`)
- Analyst → Interactive chat: starts session (evidence: `README.md`)
- Analyst → HTTP interface: sends request (evidence: `README.md`)
- Assistant commands → Question parser: parses question (evidence: `README.md`)
- Interactive chat → Question parser: parses question (evidence: `README.md`)
- HTTP interface → Question parser: routes question (evidence: `README.md`)
- Question parser → SQL safety guard: validates SQL (evidence: `README.md`)
- SQL safety guard → Query execution: permits query (evidence: `README.md`)
- Query execution → Analytics view: queries view (evidence: `README.md`)
- Query execution → PostgreSQL: executes SELECT (evidence: `README.md`)
- Question parser → CSV query engine: selects offline mode (evidence: `README.md`)
- CSV query engine → Analysis dataset: reads CSV (evidence: `README.md`)
- Assistant commands → Dataset insights: requests insights (evidence: `README.md`)
- Assistant commands → Failure and quality explanations: explains findings (evidence: `README.md`)
- Analyst → Failure and quality explanations: submits log or report
- Query execution → Answer: returns results
- CSV query engine → Answer: returns results
- Dataset insights → Answer: reports overview
- Failure and quality explanations → Answer: explains findings
- Answer → Analyst: presents answer
