How paulsurya/numus_app works
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: __init__.py App package · models.py Models · base.html Base layout · auth.py Auth
Components 13
Runtime
Application startup and external client
- Browser · User-facing HTTP client
- App launch · Starts the Flask application
app.py
Web Layer
Flask app wiring and route handlers
- App package · Application setup and wiring
numus/__init__.py - Auth · Login and authentication routes
numus/views/auth.py - Dashboard · Summary and analytics routes
numus/views/dashboard.py - Input · Income and expense entry routes
numus/views/input.py
Data Layer
Domain models and SQLite persistence
Presentation
Server-rendered templates and styling
- Base layout · Shared page shell and styling hooks
numus/templates/base.html - Login page · Authentication screen
numus/templates/login.html - Entry page · Transaction input form
numus/templates/input.html - Dashboard page · Finance summary view
numus/templates/dashboard.html - Tailwind CDN · Browser-side styling dependency
Connections 16
- 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