How armankumar456/trakn-expense-tracker works
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: app.py Flask app · admin.html Admin · app.js FinFlow UI · database.py Database layer
Components 21
Backend
Flask entrypoint, configuration, persistence, and request handling.
- Flask app · Central Flask monolith coordinating pages, APIs, auth, and feature flows.
backend/app.py - Config · Environment and application configuration boundary.
backend/config.py - Database layer · Database access and storage abstraction for the app.
backend/database.py - SQLite DB · Primary single-file local datastore used by the application.
- Auth · Login, token verification, blacklisting, lockout, rate limiting, and role checks.
- JSON API · Authenticated AJAX-facing endpoints serving application data.
Frontend
Server-rendered pages plus shared browser logic and styling.
- HTML pages · Server-rendered feature pages delivered by Flask templates.
- FinFlow UI · Browser-side application logic for API access, forms, validation, toasts, theming, and feature modules.
static/js/app.js - Styles · Shared styling and theme variables for the UI.
static/css/styles.css
Finance features
Core personal-finance modules exposed as pages and APIs.
- Transactions · Core record-keeping flow driving summaries, export/import, and downstream analytics.
templates/transactions.html - Income · Income tracking and CRUD surface.
templates/income.html - Expenses · Expense tracking and CRUD surface.
templates/expense.html - Budgets · Budget creation and monitoring flows.
templates/budget.html - Recurring · Recurring income, expense, and other repeating entries.
templates/recurring.html - Goals · Savings and financial goal tracking.
templates/goals.html - Analytics · Visualization surface for trends, comparisons, forecasts, and health scores.
templates/analytics.html - Net worth · Asset and liability summary surface.
templates/networth.html - Import/Export · CSV migration and reporting boundary with mapping and validation.
templates/import.html
Ops & support
Privileged and auxiliary surfaces around the core app.
Connections 22
- 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.