# ash1998/expense-tracker architecture

> Architecture diagram of the GitHub repository ash1998/expense-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ash1998/expense-tracker
- Repository: https://github.com/ash1998/expense-tracker

## Overview

##### Project type and purpose
- This is a self-hosted, full-stack web application for personal expense tracking.
- The Flask backend serves dynamic pages and REST endpoints; the frontend is a responsive UI built with Bootstrap, Chart.js and custom CSS/JS.
- Data is managed locally on disk (CSV/JSON per user) with pandas, avoiding any cloud dependencies.

##### File structure
Top-level components:
- app.py – main Flask application with route definitions and request handlers
- data/ – per-user data storage (CSV for transactions, JSON for settings)
- templates/ – Jinja2 HTML views (login, dashboard, analysis, settings, import/export, etc.)
- static/ – CSS (style.css), JS (main.js), images
- scripts/ – environment/config initialization for Windows, macOS, Unix; examples of .env and config.yaml
- requirements.txt – Python dependencies
- .env.example & config.yaml.example – environment and default settings
- docs/ – project documentation and screenshots

##### README for additional insights
- The README confirms a Flask-Login authentication layer, Flask-WTF forms, pandas for data manipulation, PyYAML for user config, Chart.js for interactive charts.
- It describes key features: authentication, CRUD for expenses, dashboard, analysis charts, settings, import/export, dark mode, responsive design.
- It notes MVC-style separation (routes, templates, static assets, and data logic).

##### Detail without over-segmentation
- Route group (auth, expenses CRUD, analysis, import/export) as sub-components if desired.
- Every directory with distinct responsibilities is represented.
- Don’t omit the data folder and config files – they are core to the local storage model.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Web Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer" 
        direction TB
        Templates["Jinja2 Templates"]:::frontend
        subgraph "Templates (MVC View Layer)"
            direction TB
            Base["base.html"]:::frontend
            Login["login.html"]:::frontend
            Profile["profile.html"]:::frontend
            Dashboard["dashboard.html"]:::frontend
            Analysis["analysis.html"]:::frontend
            Expenses["expenses.html"]:::frontend
            ImportExport["import_export.html"]:::frontend
            Settings["settings.html"]:::frontend
            Contact["contact.html"]:::frontend
        end
        Static["Static Assets"]:::frontend
        subgraph "Static"
            direction TB
            CSS["css/style.css"]:::frontend
            JS["js/main.js"]:::frontend
            Images["img/"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        FlaskServer["Flask Web Server\n(app.py)"]:::backend
        Libraries["External Libraries & Frameworks"]:::backend
        subgraph "Libraries"
            direction TB
            Python["Python"]:::backend
            Flask["Flask"]:::backend
            AuthLib["Flask-Login"]:::backend
            FormLib["Flask-WTF"]:::backend
            Pandas["pandas"]:::backend
            YAML["PyYAML"]:::backend
            Dotenv["python-dotenv"]:::backend
            Bootstrap["Bootstrap"]:::frontend
            ChartJS["Chart.js"]:::frontend
            FontAwesome["Font Awesome"]:::frontend
            VanillaJS["Vanilla JS"]:::frontend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataStorage["data/"]:::data
        GitIgnoreData["data/.gitignore"]:::data
    end

    %% Config & Initialization
    subgraph "Configuration & Initialization"
        direction TB
        EnvExample[".env.example"]:::config
        YamlExample["config.yaml.example"]:::config
        subgraph "Init Scripts"
            direction TB
            MacInit["init_macos.sh"]:::config
            UnixInit["init_unix.sh"]:::config
            WinInit["init_windows.bat"]:::config
        end
    end

    %% Dependencies & Docs
    subgraph "Dependencies & Documentation"
        direction TB
        Requirements["requirements.txt"]:::docs
        ReadmeRoot["README.md"]:::docs
        DocsReadme["docs/readme.md"]:::docs
        Contributing["CONTRIBUTING.md"]:::docs
        Changelog["CHANGELOG.md"]:::docs
        License["LICENSE"]:::docs
        DocsImages["docs/images/"]:::docs
        GitIgnore[".gitignore"]:::docs
    end

    %% Connections
    Client -->|"HTTP GET/POST"| FlaskServer
    FlaskServer -->|"render templates"| Templates
    FlaskServer -->|"serve assets"| Static
    FlaskServer -->|"read/write CSV/JSON"| DataStorage
    FlaskServer -->|"load config"| EnvExample
    FlaskServer -->|"load config"| YamlExample
    MacInit -->|generates| EnvExample
    MacInit -->|generates| YamlExample
    UnixInit -->|generates| EnvExample
    UnixInit -->|generates| YamlExample
    WinInit -->|generates| EnvExample
    WinInit -->|generates| YamlExample

    %% Click Events
    click FlaskServer "https://github.com/ash1998/expense-tracker/blob/main/app.py"
    click Base "https://github.com/ash1998/expense-tracker/blob/main/templates/base.html"
    click Login "https://github.com/ash1998/expense-tracker/blob/main/templates/login.html"
    click Profile "https://github.com/ash1998/expense-tracker/blob/main/templates/profile.html"
    click Dashboard "https://github.com/ash1998/expense-tracker/blob/main/templates/dashboard.html"
    click Analysis "https://github.com/ash1998/expense-tracker/blob/main/templates/analysis.html"
    click Expenses "https://github.com/ash1998/expense-tracker/blob/main/templates/expenses.html"
    click ImportExport "https://github.com/ash1998/expense-tracker/blob/main/templates/import_export.html"
    click Settings "https://github.com/ash1998/expense-tracker/blob/main/templates/settings.html"
    click Contact "https://github.com/ash1998/expense-tracker/blob/main/templates/contact.html"
    click CSS "https://github.com/ash1998/expense-tracker/blob/main/static/css/style.css"
    click JS "https://github.com/ash1998/expense-tracker/blob/main/static/js/main.js"
    click Images "https://github.com/ash1998/expense-tracker/tree/main/static/img/"
    click DataStorage "https://github.com/ash1998/expense-tracker/tree/main/data/"
    click GitIgnoreData "https://github.com/ash1998/expense-tracker/blob/main/data/.gitignore"
    click EnvExample "https://github.com/ash1998/expense-tracker/blob/main/scripts/.env.example"
    click YamlExample "https://github.com/ash1998/expense-tracker/blob/main/scripts/config.yaml.example"
    click MacInit "https://github.com/ash1998/expense-tracker/blob/main/scripts/init_macos.sh"
    click UnixInit "https://github.com/ash1998/expense-tracker/blob/main/scripts/init_unix.sh"
    click WinInit "https://github.com/ash1998/expense-tracker/blob/main/scripts/init_windows.bat"
    click Requirements "https://github.com/ash1998/expense-tracker/blob/main/requirements.txt"
    click ReadmeRoot "https://github.com/ash1998/expense-tracker/blob/main/README.md"
    click DocsReadme "https://github.com/ash1998/expense-tracker/blob/main/docs/readme.md"
    click Contributing "https://github.com/ash1998/expense-tracker/blob/main/CONTRIBUTING.md"
    click Changelog "https://github.com/ash1998/expense-tracker/blob/main/CHANGELOG.md"
    click License "https://github.com/ash1998/expense-tracker/tree/main/LICENSE"
    click DocsImages "https://github.com/ash1998/expense-tracker/tree/main/docs/images/"
    click GitIgnore "https://github.com/ash1998/expense-tracker/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#3B7DD8,color:#000
    classDef backend fill:#DFF7D8,stroke:#2E8B57,color:#000
    classDef data fill:#FFE5B4,stroke:#E68A00,color:#000
    classDef config fill:#EEEEEE,stroke:#888888,color:#000
    classDef docs fill:#F2E5FF,stroke:#A64DFF,color:#000
    classDef external fill:#FFFFFF,stroke:#000000,color:#000,stroke-dasharray: 5 5
```
