# armankumar456/trakn-expense-tracker architecture

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

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

## Overview

1. **Overall shape**
   - TRAKN is a single Python Flask monolith for personal finance, not a microservice system.
   - The same backend serves HTML pages, JSON APIs, and static assets.
   - The app is organized around user-facing finance modules rather than around infrastructure components.

2. **Primary runtime boundary**
   - `backend/app.py` is the central entrypoint and route coordinator.
   - It exposes both page routes for Jinja templates and `/api/...` endpoints for application data.
   - `backend/config.py` and `backend/database.py` isolate configuration and persistence concerns from the route layer.

3. **Persistence layer**
   - Default storage is SQLite in a local `data/trakn.db` file, giving the app a single-file, self-hosted data model.
   - The repo README notes MySQL support can be enabled via `database.py`, but SQLite is the intended baseline architecture.
   - The database stores users, transactions, budgets, recurring items, goals, assets, liabilities, feedback, and related metadata.

4. **Authentication and access control**
   - Authentication is JWT-based, with tokens verified by backend endpoints and stored client-side in `localStorage`.
   - Security boundaries are enforced server-side with role-based access for regular users vs admins.
   - The auth subsystem also includes logout token blacklisting, account lockout after repeated failures, rate limiting, and password hashing.

5. **Frontend delivery model**
   - The UI is server-rendered HTML from `templates/*.html`, one template per feature page.
   - `static/css/styles.css` provides shared styling and theme variables.
   - `static/js/app.js` contains the client-side application logic under the `FinFlow` namespace, which groups API access, forms, validation, toast notifications, theming, and feature modules.

6. **Client-to-server data flow**
   - Users interact with page templates in the browser.
   - JavaScript issues authenticated AJAX/fetch calls to `/api/...` endpoints.
   - The Flask backend validates input, applies sanitization, reads/writes the database, and returns JSON for the UI to render/update.
   - This pattern is used consistently across transactions, budgets, goals, profile, admin, and feedback flows.

7. **Core finance domain modules**
   - Transactions are the central record-keeping subsystem and drive summaries, export/import, and downstream analytics.
   - Income, expenses, budgets, recurring items, goals, and net worth are separate feature areas with their own CRUD APIs and views.
   - These modules likely share the same user/account model and database wrapper, but are exposed as distinct UI sections and API namespaces.

8. **Analytics and visualization subsystem**
   - `templates/analytics.html` is the primary visualization surface for financial analysis.
   - The README indicates 20+ charts and comparisons, implying the browser performs chart rendering using Chart.js.
   - Analytics appears to aggregate data from transactions, budgets, recurring items, and goals to compute trends, forecasts, and health scores.

9. **Import/export and reporting**
   - CSV import/export is a distinct boundary around transaction data migration and reporting.
   - The import flow includes field mapping, validation, and error reporting, so it is not just a raw file upload.
   - Export endpoints provide a data portability layer for users and admin user exports.

10. **Admin and moderation path**
   - `templates/admin.html` and `/api/admin/...` form a privileged back-office subsystem.
   - Admin functions include user management, platform stats, and feedback inbox handling.
   - This is separated from the normal user flow by role checks and protected endpoints.

11. **Feedback and messaging**
   - The feedback subsystem is chat-like rather than a simple form submission.
   - It supports threaded conversations between user and admin, unread reply tracking, and message history.
   - Operationally, it acts as the support/messaging boundary between the app owner and users.

12. **Auxiliary surfaces**
   - The repository also includes pages for calculator, news, profile, login, onboarding, and legal documents.
   - These are mostly presentation or helper surfaces that complement the core finance model rather than introducing separate backend systems.
   - The calculator and news pages broaden the app into advice and reference content, but they still sit inside the same Flask/static architecture.

13. **Deployment and operational profile**
   - The app is designed for local or self-hosted deployment with minimal external dependencies.
   - Python 3 and Flask are the core runtime, with browser-side JavaScript handling most interactive behavior.
   - The architecture favors simplicity and portability over horizontal scaling: one app process, one local database file, and static asset delivery from the same repo.

Main entry points: [`backend/app.py`](https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/app.py) (Flask app), [`templates/admin.html`](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/admin.html) (Admin), [`static/js/app.js`](https://github.com/armankumar456/trakn-expense-tracker/blob/main/static/js/app.js) (FinFlow UI), [`backend/database.py`](https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/database.py) (Database layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_app["Flask app<br/>entrypoint/routes<br/>[app.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_database[("Database layer<br/>persistence<br/>[database.py]")]
  node_sqlite[("SQLite DB<br/>data store")]
  node_auth{{"Auth<br/>jwt/security"}}
  node_api["JSON API<br/>/api endpoints"]
end

subgraph group_frontend["Frontend"]
  node_templates["HTML pages<br/>jinja views"]
  node_ui["FinFlow UI<br/>client js<br/>[app.js]"]
  node_styles["Styles<br/>css theme<br/>[styles.css]"]
end

subgraph group_finance["Finance features"]
  node_transactions["Transactions<br/>ledger module<br/>[transactions.html]"]
  node_income["Income<br/>finance module<br/>[income.html]"]
  node_expenses["Expenses<br/>finance module<br/>[expense.html]"]
  node_budget["Budgets<br/>planning module<br/>[budget.html]"]
  node_recurring["Recurring<br/>scheduled items<br/>[recurring.html]"]
  node_goals["Goals<br/>planning module<br/>[goals.html]"]
  node_analytics(("Analytics<br/>charts/insights<br/>[analytics.html]"))
  node_networth["Net worth<br/>portfolio view<br/>[networth.html]"]
  node_importexport["Import/Export<br/>csv exchange<br/>[import.html]"]
end

subgraph group_ops["Ops & support"]
  node_admin["Admin<br/>privileged console<br/>[admin.html]"]
  node_feedback["Feedback<br/>support thread<br/>[feedback.html]"]
  node_aux["Aux pages<br/>support pages"]
end

node_app -->|"reads"| node_config
node_app -->|"uses"| node_database
node_database -->|"stores in"| node_sqlite
node_app -->|"enforces"| node_auth
node_app -->|"serves"| node_api
node_app -->|"renders"| node_templates
node_ui -->|"calls"| node_api
node_ui -->|"enhances"| node_templates
node_styles -->|"skins"| node_templates
node_transactions -->|"drives"| node_api
node_income -->|"uses"| node_api
node_expenses -->|"uses"| node_api
node_budget -->|"uses"| node_api
node_recurring -->|"uses"| node_api
node_goals -->|"uses"| node_api
node_analytics -->|"aggregates"| node_api
node_networth -->|"summarizes"| node_api
node_importexport -->|"imports/exports"| node_transactions
node_admin -->|"restricted by"| node_auth
node_admin -->|"manages"| node_api
node_feedback -->|"routes to"| node_admin
node_aux -->|"served by"| node_app

click node_app "https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/app.py"
click node_config "https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/config.py"
click node_database "https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/database.py"
click node_ui "https://github.com/armankumar456/trakn-expense-tracker/blob/main/static/js/app.js"
click node_styles "https://github.com/armankumar456/trakn-expense-tracker/blob/main/static/css/styles.css"
click node_transactions "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/transactions.html"
click node_income "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/income.html"
click node_expenses "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/expense.html"
click node_budget "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/budget.html"
click node_recurring "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/recurring.html"
click node_goals "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/goals.html"
click node_analytics "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/analytics.html"
click node_networth "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/networth.html"
click node_importexport "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/import.html"
click node_admin "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/admin.html"
click node_feedback "https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/feedback.html"

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_config,node_database,node_sqlite,node_auth,node_api toneBlue
class node_templates,node_ui,node_styles toneAmber
class node_transactions,node_income,node_expenses,node_budget,node_recurring,node_goals,node_analytics,node_networth,node_importexport toneMint
class node_admin,node_feedback,node_aux toneRose
```

## Components

### Backend

Flask entrypoint, configuration, persistence, and request handling.

- [Flask app](https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/app.py): entrypoint/routes · Central Flask monolith coordinating pages, APIs, auth, and feature flows. · `backend/app.py`
- [Config](https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/config.py): settings · Environment and application configuration boundary. · `backend/config.py`
- [Database layer](https://github.com/armankumar456/trakn-expense-tracker/blob/main/backend/database.py): persistence · Database access and storage abstraction for the app. · `backend/database.py`
- **SQLite DB**: data store · Primary single-file local datastore used by the application.
- **Auth**: jwt/security · Login, token verification, blacklisting, lockout, rate limiting, and role checks.
- **JSON API**: /api endpoints · Authenticated AJAX-facing endpoints serving application data.

### Frontend

Server-rendered pages plus shared browser logic and styling.

- **HTML pages**: jinja views · Server-rendered feature pages delivered by Flask templates.
- [FinFlow UI](https://github.com/armankumar456/trakn-expense-tracker/blob/main/static/js/app.js): client js · Browser-side application logic for API access, forms, validation, toasts, theming, and feature modules. · `static/js/app.js`
- [Styles](https://github.com/armankumar456/trakn-expense-tracker/blob/main/static/css/styles.css): css theme · Shared styling and theme variables for the UI. · `static/css/styles.css`

### Finance features

Core personal-finance modules exposed as pages and APIs.

- [Transactions](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/transactions.html): ledger module · Core record-keeping flow driving summaries, export/import, and downstream analytics. · `templates/transactions.html`
- [Income](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/income.html): finance module · Income tracking and CRUD surface. · `templates/income.html`
- [Expenses](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/expense.html): finance module · Expense tracking and CRUD surface. · `templates/expense.html`
- [Budgets](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/budget.html): planning module · Budget creation and monitoring flows. · `templates/budget.html`
- [Recurring](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/recurring.html): scheduled items · Recurring income, expense, and other repeating entries. · `templates/recurring.html`
- [Goals](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/goals.html): planning module · Savings and financial goal tracking. · `templates/goals.html`
- [Analytics](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/analytics.html): charts/insights · Visualization surface for trends, comparisons, forecasts, and health scores. · `templates/analytics.html`
- [Net worth](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/networth.html): portfolio view · Asset and liability summary surface. · `templates/networth.html`
- [Import/Export](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/import.html): csv exchange · CSV migration and reporting boundary with mapping and validation. · `templates/import.html`

### Ops & support

Privileged and auxiliary surfaces around the core app.

- [Admin](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/admin.html): privileged console · Back-office user management, platform stats, and moderation tools. · `templates/admin.html`
- [Feedback](https://github.com/armankumar456/trakn-expense-tracker/blob/main/templates/feedback.html): support thread · Threaded user-admin messaging and unread reply tracking. · `templates/feedback.html`
- **Aux pages**: support pages · Login, onboarding, profile, calculator, news, legal, and badge surfaces around the core app.

## Connections

- Flask app → Config: reads · Loads runtime configuration and environment settings.
- Flask app → Database layer: uses · Coordinates persistence through the database wrapper.
- Database layer → SQLite DB: stores in · Primary local datastore for users and finance records.
- Flask app → Auth: enforces · Verifies JWTs and applies role-based access control.
- Flask app → JSON API: serves · Exposes authenticated JSON endpoints.
- Flask app → HTML pages: renders · Serves server-rendered HTML pages.
- FinFlow UI → JSON API: calls · Issues authenticated fetch/AJAX requests to backend endpoints.
- FinFlow UI → HTML pages: enhances · Adds client-side behavior to page surfaces.
- Styles → HTML pages: skins · Provides shared presentation and theme rules.
- Transactions → JSON API: drives · Primary ledger flow used by the browser and backend.
- Income → JSON API: uses · Income CRUD is exposed through backend data endpoints.
- Expenses → JSON API: uses · Expense CRUD is exposed through backend data endpoints.
- Budgets → JSON API: uses · Budget CRUD and summaries are fetched via the API layer.
- Recurring → JSON API: uses · Recurring-item management is backed by JSON endpoints.
- Goals → JSON API: uses · Goals are managed through authenticated API calls.
- Analytics → JSON API: aggregates · Consumes finance data to compute charts and insights.
- Net worth → JSON API: summarizes · Builds net worth views from assets and liabilities.
- Import/Export → Transactions: imports/exports · Moves transaction data in and out through CSV workflows.
- Admin → Auth: restricted by · Protected by privileged role checks.
- Admin → JSON API: manages · Uses admin-specific backend endpoints.
- Feedback → Admin: routes to · Threads user messages into the admin support inbox.
- Aux pages → Flask app: served by · Auxiliary pages are delivered from the same Flask monolith.