# paulsurya/numus_app architecture

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

- Interactive diagram: https://gitdiagram.com/paulsurya/numus_app
- Repository: https://github.com/paulsurya/numus_app

## Overview

1. **What this repository is**
   Numus is a small **Flask-based finance tracking app**. The architecture is intentionally simple: a Python web server, a SQLite database, and server-rendered HTML templates for the UI.

2. **Top-level runtime entry point**
   `app.py` appears to be the application launch script. In a Flask project like this, that file typically starts the server and wires up the app package under `numus/`.

3. **Application package boundary**
   The `numus/` directory is the main application package. It holds the reusable app setup, database models, view modules, and templates, which keeps the web app logic separated from the launcher.

4. **Database and persistence**
   The repository includes `instance/database.db`, which indicates **SQLite** persistence managed through Flask’s instance folder. The only model explicitly called out in the README is a **User table with a UserMixin**, suggesting basic authentication/user identity is already part of the data layer.

5. **Domain model layer**
   `numus/models.py` is the central place for persistent entities. Based on the README, this likely contains the user model and will later hold finance-related records such as income, expenses, and categories.

6. **Request handling / route modules**
   The `numus/views/` package is split by concern:
   - `auth.py` for login/authentication flows
   - `dashboard.py` for the analytics/dashboard page
   - `input.py` for creating expense/income entries  
   This is a clean separation between user access, data entry, and reporting.

7. **UI rendering layer**
   `numus/templates/` contains the server-rendered pages:
   - `base.html` as the shared layout shell
   - `login.html` for authentication
   - `input.html` for transaction entry
   - `dashboard.html` for visualization/summary  
   The app is not a SPA; the browser receives rendered HTML from Flask.

8. **Shared presentation structure**
   `base.html` likely defines the common page frame and styling hooks. The README notes **Tailwind CDN** usage, so styling is handled directly in templates rather than through a local CSS pipeline.

9. **Primary data flow**
   The main flow is: browser request → Flask route in `views/` → model/database access through `models.py` → template rendering in `templates/` → HTML response back to the browser. The dashboard likely reads stored finance records and aggregates them for display.

10. **Functional boundaries in the app**
   The application is centered on three user-facing capabilities:
   - authenticate a user
   - enter income/expense records
   - display categorized spending summaries on the dashboard  
   Categories such as food, travel, and custom categories are part of the reporting boundary and probably influence both storage and dashboard grouping.

11. **Current implementation maturity**
   The README says only the “basics of Flask connectivity” are implemented so far. That means the architecture is already partitioned into app, models, views, and templates, but the finance logic is still minimal and likely evolving.

12. **Infrastructure and deployment shape**
   There is no sign of separate services, queues, APIs, or frontend build tooling. This is a **single-process monolith** backed by local SQLite, with dependencies installed from `numus/requirements.txt`.

13. **How to draw the architecture**
   For a diagram, show:
   - Client/browser at the top
   - Flask app entrypoint (`app.py` / `numus/__init__.py`)
   - Route modules (`auth`, `dashboard`, `input`)
   - Model/data layer (`models.py`)
   - SQLite database (`instance/database.db`)
   - Template rendering layer (`base`, `login`, `input`, `dashboard`)
   - Tailwind CDN as an external styling dependency  
   The key boundary is between request handling/templates and the persistent data layer.

Main entry points: [`numus/__init__.py`](https://github.com/paulsurya/numus_app/blob/master/numus/__init__.py) (App package), [`numus/models.py`](https://github.com/paulsurya/numus_app/blob/master/numus/models.py) (Models), [`numus/templates/base.html`](https://github.com/paulsurya/numus_app/blob/master/numus/templates/base.html) (Base layout), [`numus/views/auth.py`](https://github.com/paulsurya/numus_app/blob/master/numus/views/auth.py) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_browser(("Browser<br/>client"))
  node_app_py["App launch<br/>entrypoint<br/>[app.py]"]
end

subgraph group_web["Web Layer"]
  node_app_pkg["App package<br/>flask package<br/>[__init__.py]"]
  node_auth_view["Auth<br/>route module<br/>[auth.py]"]
  node_dashboard_view["Dashboard<br/>route module<br/>[dashboard.py]"]
  node_input_view["Input<br/>route module<br/>[input.py]"]
end

subgraph group_data["Data Layer"]
  node_models_py["Models<br/>domain model<br/>[models.py]"]
  node_sqlite_db[("SQLite DB<br/>database<br/>[database.db]")]
end

subgraph group_ui["Presentation"]
  node_base_tpl["Base layout<br/>template<br/>[base.html]"]
  node_login_tpl["Login page<br/>template<br/>[login.html]"]
  node_input_tpl["Entry page<br/>template<br/>[input.html]"]
  node_dashboard_tpl["Dashboard page<br/>template<br/>[dashboard.html]"]
  node_tailwind(("Tailwind CDN<br/>external style"))
end

node_browser -->|"HTTP request"| node_app_py
node_app_py -->|"bootstraps"| node_app_pkg
node_app_pkg -->|"registers"| node_auth_view
node_app_pkg -->|"registers"| node_dashboard_view
node_app_pkg -->|"registers"| node_input_view
node_auth_view -->|"uses"| node_models_py
node_dashboard_view -->|"reads"| node_models_py
node_input_view -->|"writes"| node_models_py
node_models_py -->|"persists"| node_sqlite_db
node_auth_view -->|"renders"| node_login_tpl
node_input_view -->|"renders"| node_input_tpl
node_dashboard_view -->|"renders"| node_dashboard_tpl
node_login_tpl -->|"extends"| node_base_tpl
node_input_tpl -->|"extends"| node_base_tpl
node_dashboard_tpl -->|"extends"| node_base_tpl
node_base_tpl -.->|"loads"| node_tailwind

click node_app_py "https://github.com/paulsurya/numus_app/blob/master/app.py"
click node_app_pkg "https://github.com/paulsurya/numus_app/blob/master/numus/__init__.py"
click node_auth_view "https://github.com/paulsurya/numus_app/blob/master/numus/views/auth.py"
click node_dashboard_view "https://github.com/paulsurya/numus_app/blob/master/numus/views/dashboard.py"
click node_input_view "https://github.com/paulsurya/numus_app/blob/master/numus/views/input.py"
click node_models_py "https://github.com/paulsurya/numus_app/blob/master/numus/models.py"
click node_sqlite_db "https://github.com/paulsurya/numus_app/blob/master/instance/database.db"
click node_base_tpl "https://github.com/paulsurya/numus_app/blob/master/numus/templates/base.html"
click node_login_tpl "https://github.com/paulsurya/numus_app/blob/master/numus/templates/login.html"
click node_input_tpl "https://github.com/paulsurya/numus_app/blob/master/numus/templates/input.html"
click node_dashboard_tpl "https://github.com/paulsurya/numus_app/blob/master/numus/templates/dashboard.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_browser,node_app_py toneBlue
class node_app_pkg,node_auth_view,node_dashboard_view,node_input_view toneAmber
class node_models_py,node_sqlite_db toneMint
class node_base_tpl,node_login_tpl,node_input_tpl,node_dashboard_tpl,node_tailwind toneRose
```

## Components

### Runtime

Application startup and external client

- **Browser**: client · User-facing HTTP client
- [App launch](https://github.com/paulsurya/numus_app/blob/master/app.py): entrypoint · Starts the Flask application · `app.py`

### Web Layer

Flask app wiring and route handlers

- [App package](https://github.com/paulsurya/numus_app/blob/master/numus/__init__.py): flask package · Application setup and wiring · `numus/__init__.py`
- [Auth](https://github.com/paulsurya/numus_app/blob/master/numus/views/auth.py): route module · Login and authentication routes · `numus/views/auth.py`
- [Dashboard](https://github.com/paulsurya/numus_app/blob/master/numus/views/dashboard.py): route module · Summary and analytics routes · `numus/views/dashboard.py`
- [Input](https://github.com/paulsurya/numus_app/blob/master/numus/views/input.py): route module · Income and expense entry routes · `numus/views/input.py`

### Data Layer

Domain models and SQLite persistence

- [Models](https://github.com/paulsurya/numus_app/blob/master/numus/models.py): domain model · Persistent entities and user model · `numus/models.py`
- [SQLite DB](https://github.com/paulsurya/numus_app/blob/master/instance/database.db): database · Local finance data store · `instance/database.db`

### Presentation

Server-rendered templates and styling

- [Base layout](https://github.com/paulsurya/numus_app/blob/master/numus/templates/base.html): template · Shared page shell and styling hooks · `numus/templates/base.html`
- [Login page](https://github.com/paulsurya/numus_app/blob/master/numus/templates/login.html): template · Authentication screen · `numus/templates/login.html`
- [Entry page](https://github.com/paulsurya/numus_app/blob/master/numus/templates/input.html): template · Transaction input form · `numus/templates/input.html`
- [Dashboard page](https://github.com/paulsurya/numus_app/blob/master/numus/templates/dashboard.html): template · Finance summary view · `numus/templates/dashboard.html`
- **Tailwind CDN**: external style · Browser-side styling dependency

## Connections

- Browser → App launch: HTTP request · User requests hit the Flask app
- App launch → App package: bootstraps · Launcher imports and starts the application package
- App package → Auth: registers · App wiring exposes auth routes
- App package → Dashboard: registers · App wiring exposes dashboard routes
- App package → Input: registers · App wiring exposes entry routes
- Auth → Models: uses · Authentication logic relies on user data
- Dashboard → Models: reads · Dashboard aggregates stored finance records
- Input → Models: writes · Entry flow persists new records
- Models → SQLite DB: persists · Models map to the local SQLite database
- Auth → Login page: renders · Login route returns the login page
- Input → Entry page: renders · Input route returns the transaction form
- Dashboard → Dashboard page: renders · Dashboard route returns the summary page
- Login page → Base layout: extends · Shared layout is reused by the login page
- Entry page → Base layout: extends · Shared layout is reused by the entry page
- Dashboard page → Base layout: extends · Shared layout is reused by the dashboard page
- Base layout → Tailwind CDN: loads · Templates use Tailwind via CDN
