How tekrondo/vuln-bank works
1. Overall shape
- This is a single Flask-style monolith: one Python web app (app.py) handles the application routes, business logic, and HTTP responses.
- Supporting modules split out authentication (auth.py) and database access / initialization (database.py), but there is no separate service layer or microservice boundary.
2. Primary runtime boundary
- The app is designed to run either:
- in Docker / Docker Compose, or
- locally with Python and PostgreSQL.
- The main external dependency is PostgreSQL, configured through .env values and likely started as a Compose service named db.
3. Request flow
- The browser talks directly to the Flask server on port 5000.
- Requests are processed in app.py, which then:
- renders HTML pages,
- reads/writes data through database.py,
- and delegates login/token-related logic to auth.py.
- There is no separate front-end app; the UI is server-rendered.
4. Presentation layer
- The UI is built from Jinja templates in templates/.
- Key screens include:
- landing/index,
- login/register,
- forgot/reset password,
- dashboard,
- admin.
- static/style.css provides shared styling, and the app likely embeds any client-side behavior directly into templates rather than using a large JS bundle.
5. Authentication and authorization boundary
- auth.py is the logical boundary for user identity, token handling, and password reset.
- The README indicates a weak JWT/token-based model, with tokens handled on the client side and no strong server-side invalidation.
- Admin access is exposed as a separate template, implying role/privilege checks happen in the Flask route layer rather than in a dedicated auth service.
6. Persistence layer
- database.py is the bridge to PostgreSQL and likely owns connection setup plus table creation/queries.
- The README says the database is auto-initialized with tables for users, transactions, and loans; other banking entities (cards, bills) are likely modeled in the same database as additional tables.
- The architecture is database-backed stateful, with application state persisted centrally in PostgreSQL.
7. File storage subsystem
- static/uploads/ is the on-disk storage location for uploaded files such as profile pictures.
- Upload handling is part of the main app process, not an external object store, so file I/O is local to the container or host filesystem.
- This makes upload processing a distinct boundary: browser upload -> Flask endpoint -> filesystem under static/uploads.
8. API surface and documentation
- The repository includes static/openapi.json, and the README exposes /api/docs.
- That suggests the app provides an HTTP API alongside the HTML pages, with the OpenAPI spec used for documentation or testing.
- The API likely reuses the same backend and database as the web UI, rather than being a separate service.
9. State and session model
- User state is likely split between:
- server-side database records for accounts, balances, transactions, etc.,
- and client-held auth tokens for session continuity.
- Because the README calls out localStorage token storage and no session expiration, the browser is part of the authentication state boundary.
10. Operational/deployment layout
- Dockerfile and docker-compose.yml define the containerized deployment path.
- The Compose setup likely runs at least two components:
- the web application container,
- a PostgreSQL container.
- This makes the repo deployable as a small two-tier system: web app plus database.
11. Where the important data flows are
- Login / registration flow: browser forms -> Flask routes -> auth logic -> PostgreSQL users table.
- Account operations flow: browser/dashboard -> Flask routes -> database queries/updates -> rendered response.
- Upload flow: browser -> upload endpoint -> filesystem under static/uploads.
- API flow: client/browser -> JSON endpoints -> database and auth checks -> JSON/HTML response.
12. Architecture summary for diagramming
- Draw it as a monolithic Flask web application with three main internal subsystems:
- presentation/templates,
- auth/session handling,
- database/file storage access.
- Show PostgreSQL as the main persistence backend, the browser as the only external client, and static/uploads as local filesystem storage for uploaded content.
Main entry points: app.py App · templates Templates · auth.py Auth · docker-compose.yml Compose
Components 11
Runtime
Flask monolith and request handling
Presentation
Server-rendered pages and shared assets
Data
Database and local file storage
Deployment
Container build and compose setup
- Compose · Defines web app and database containers
docker-compose.yml - Dockerfile · Builds the application container image
Dockerfile
Connections 15
- Browser → App: HTTP requests · Browser sends page loads, forms, and API calls to Flask
- App → Templates: render · Routes render Jinja pages for the UI
- App → Styles: serve assets · App serves shared styling for the UI
- App → Auth: auth logic · Routes delegate login, registration, and password reset handling
- App → Database: queries · Application reads and writes persistent banking state through the database layer
- Database → PostgreSQL: SQL · Database module connects to PostgreSQL and executes queries
- App → Uploads: file I/O · Upload endpoints persist files to local storage
- Browser → API Spec: docs · OpenAPI spec documents the HTTP API surface
- App → API Spec: exposes · API endpoints are documented alongside the web app
- Auth → PostgreSQL: user data · Identity and token-related state is backed by the database
- Templates → Auth: forms · Login and recovery pages feed authentication flows
- Templates → App: pages · Templates are populated by the Flask route layer
- Compose → App: runs · Compose starts the web application container
- Compose → PostgreSQL: runs · Compose starts the PostgreSQL service
- Dockerfile → App: builds · Docker image packages the Flask app