# braydio/pynance architecture

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

- Interactive diagram: https://gitdiagram.com/braydio/pynance
- Repository: https://github.com/braydio/pynance

## Overview

##### Project type and purpose
- pyNance is a full-stack personal finance dashboard.
- Backend: Flask application exposing REST API endpoints for account linking, transaction sync, category logic, CSV export, and webhook handling.
- Frontend: Vue.js single-page application (SPA) that consumes the Flask API to render charts, tables, and settings.
- Integrations: Plaid and Teller external services for banking data.

##### File structure
Top-level separation
- /backend – Python Flask service
- /frontend – Vue.js app with Vite, Tailwind, and Cypress tests
- config files (.env templates, requirements.txt, package.json)

Backend modules
- app/config – environment, logging, paths, Plaid/Teller setup
- app/extensions – Flask & SQLAlchemy initialization
- app/models – database schema (SQLAlchemy models)
- app/sql – business logic for data read/write (account_logic.py, category_logic.py, etc.)
- app/helpers – SDK wrappers for Plaid/Teller and import utilities
- app/routes – Flask blueprints defining API endpoints (/api/accounts, /api/transactions, /api/plaid, etc.)
- migrations – Alembic scripts for schema migrations
- run.py – entry point for Flask

Frontend modules
- src/main.js & App.vue – application bootstrap
- src/router – Vue Router configuration for views
- src/views – top-level pages (Dashboard.vue, Accounts.vue, etc.)
- src/components – reusable UI elements and chart wrappers
- src/api & src/services – API client modules communicating with Flask (axios wrappers)
- src/styles – global and component styles
- cypress – end-to-end tests

##### Extract architectural insights from README
- Monolithic backend with clear layering: config → extensions → models → business logic → routes
- SPA front end communicating over a single API base URL
- Environment variables drive external service configuration and API base URL
- Logging is centralized via config/log_setup.py

a. Main components
- User browser / SPA (Vue.js app)
- Flask REST API (backend/app)
- Relational database (e.g., Postgres via SQLAlchemy)
- External services: Plaid and Teller
- Message flows: optional webhooks from Teller

b. Relationships and interactions
- Browser sends HTTP(S) requests to Flask endpoints (GET /api/transactions, POST /api/refresh_accounts, etc.)
- Flask routes call helpers to fetch/update data from Plaid/Teller or database
- SQLAlchemy models persist data in the relational database
- Webhook endpoint (/api/teller_webhook) receives asynchronous updates from Teller
- Flask logs events to local file via log_setup

c. Architectural patterns and design principles
- Layered architecture (Configuration → Extensions → Models → Business Logic → Routes)
- Blueprints for modular API grouping (accounts, transactions, categories, exports)
- Separation of concerns: helpers for external SDK logic, sql/ for DB logic, routes/ for HTTP layer
- SPA pattern: decoupled UI and API
- Environment-driven configuration

d. Key technologies and frameworks
- Flask, Flask-Blueprints, SQLAlchemy, Alembic (backend)
- Vue.js 3, Vue Router, Vite, Tailwind CSS (frontend)
- Axios or fetch (API calls)
- Plaid SDK, Teller API wrappers
- Cypress for E2E testing

##### Diagramming conventions
- UI components (blue)
- Backend modules (green)
- Data stores (orange)
- External services (gray)

##### Detail
– Include environment variable loader → config/environment.py.
– Show log pipeline configured by config/log_setup.py.
– Represent Alembic migrations as a side-car to the database.
– Highlight static asset serving (Flask’s static folder) if relevant.
– Capture the dual setup for Plaid vs. Teller integration paths.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["User Browser"]:::external
        SPA["Vue.js SPA"]:::ui
        Router["Vue Router\n(index.js)"]:::ui
        Views["Views"]:::ui
        Components["Components"]:::ui
        API_Client["API Clients\n(api & services)"]:::ui
        Styles["Styles & Utilities"]:::ui
        Cypress["Cypress Tests"]:::ui
        Env_FE[".env Template"]:::ui

        Browser -->|"load SPA"| SPA
        SPA --> Router
        SPA --> Views
        SPA --> Components
        SPA --> API_Client
        SPA --> Styles
        SPA --> Cypress
        SPA --> Env_FE

        click SPA "https://github.com/braydio/pynance/blob/main/frontend/src/main.js"
        click SPA "https://github.com/braydio/pynance/blob/main/frontend/src/App.vue"
        click Router "https://github.com/braydio/pynance/blob/main/frontend/src/router/index.js"
        click Views "https://github.com/braydio/pynance/tree/main/frontend/src/views"
        click Components "https://github.com/braydio/pynance/tree/main/frontend/src/components"
        click API_Client "https://github.com/braydio/pynance/tree/main/frontend/src/api"
        click API_Client "https://github.com/braydio/pynance/blob/main/frontend/src/services/api.js"
        click Styles "https://github.com/braydio/pynance/tree/main/frontend/src/styles"
        click Styles "https://github.com/braydio/pynance/blob/main/frontend/src/utils/format.js"
        click Styles "https://github.com/braydio/pynance/blob/main/frontend/src/utils/externalScripts.js"
        click Cypress "https://github.com/braydio/pynance/tree/main/frontend/cypress"
        click Env_FE "https://github.com/braydio/pynance/blob/main/frontend/example.env"
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Config_Sub["Configuration"]:::backend
        Extensions["Extensions Init"]:::backend
        Models["SQLAlchemy Models"]:::backend
        SQL_Layer["Business Logic (SQL)"]:::backend
        Helpers["Helpers (SDK & Imports)"]:::backend
        Routes_Sub["API Routes (Blueprints)"]:::backend
        Migrations["Alembic Migrations"]:::backend
        Run["Flask Entry\n(run.py)"]:::backend
        DB["Relational Database"]:::datastore
        Plaid["Plaid Service"]:::external
        Teller["Teller Service"]:::external
        Teller_Webhook["Teller Webhook"]:::backend

        Config_Sub --> Extensions
        Extensions --> Models
        Extensions --> SQL_Layer
        Extensions --> Helpers
        Extensions --> Routes_Sub
        Models --> DB
        SQL_Layer --> DB
        Helpers --> DB
        Helpers --> Plaid
        Helpers --> Teller
        Routes_Sub --> SQL_Layer
        Routes_Sub --> Helpers
        Routes_Sub --> Models
        Routes_Sub --> Run
        Run --> Extensions
        Routes_Sub --> Teller_Webhook
        Migrations --> DB

        click Config_Sub "https://github.com/braydio/pynance/tree/main/backend/app/config"
        click Extensions "https://github.com/braydio/pynance/blob/main/backend/app/extensions.py"
        click Models "https://github.com/braydio/pynance/blob/main/backend/app/models.py"
        click SQL_Layer "https://github.com/braydio/pynance/tree/main/backend/app/sql"
        click Helpers "https://github.com/braydio/pynance/tree/main/backend/app/helpers"
        click Routes_Sub "https://github.com/braydio/pynance/tree/main/backend/app/routes"
        click Migrations "https://github.com/braydio/pynance/tree/main/backend/migrations"
        click Run "https://github.com/braydio/pynance/blob/main/backend/run.py"
        click Teller_Webhook "https://github.com/braydio/pynance/blob/main/backend/app/routes/teller_webhook.py"
    end

    %% External Interactions
    Browser -->|"HTTP(S) API Calls"| Routes_Sub
    API_Client -->|"REST Requests"| Routes_Sub
    Plaid -->|"API Calls"| Helpers
    Teller -->|"API Calls"| Helpers
    Teller -->|"Webhooks"| Teller_Webhook

    classDef ui fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D6F5D6,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
