# tekrondo/vuln-bank architecture

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

- Interactive diagram: https://gitdiagram.com/tekrondo/vuln-bank
- Repository: https://github.com/tekrondo/vuln-bank

## Overview

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`](https://github.com/tekrondo/vuln-bank/blob/main/app.py) (App), [`templates`](https://github.com/tekrondo/vuln-bank/tree/main/templates) (Templates), [`auth.py`](https://github.com/tekrondo/vuln-bank/blob/main/auth.py) (Auth), [`docker-compose.yml`](https://github.com/tekrondo/vuln-bank/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_browser(("Browser<br/>client"))
  node_app_py["App<br/>flask monolith<br/>[app.py]"]
  node_auth_py["Auth<br/>identity/token<br/>[auth.py]"]
end

subgraph group_presentation["Presentation"]
  node_templates["Templates<br/>jinja views"]
  node_style_css["Styles<br/>css assets<br/>[style.css]"]
  node_openapi["API Spec<br/>openapi docs<br/>[openapi.json]"]
end

subgraph group_data["Data"]
  node_db_py["Database<br/>pg access<br/>[database.py]"]
  node_uploads[("Uploads<br/>filesystem store")]
  node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_deploy["Deployment"]
  node_compose["Compose<br/>runtime stack<br/>[docker-compose.yml]"]
  node_dockerfile["Dockerfile<br/>image build"]
end

node_browser -->|"HTTP requests"| node_app_py
node_app_py -->|"render"| node_templates
node_app_py -->|"serve assets"| node_style_css
node_app_py -->|"auth logic"| node_auth_py
node_app_py -->|"queries"| node_db_py
node_db_py -->|"SQL"| node_postgres
node_app_py -->|"file I/O"| node_uploads
node_browser -->|"docs"| node_openapi
node_app_py -->|"exposes"| node_openapi
node_auth_py -->|"user data"| node_postgres
node_templates -->|"forms"| node_auth_py
node_templates -->|"pages"| node_app_py
node_compose -->|"runs"| node_app_py
node_compose -->|"runs"| node_postgres
node_dockerfile -->|"builds"| node_app_py

click node_app_py "https://github.com/tekrondo/vuln-bank/blob/main/app.py"
click node_auth_py "https://github.com/tekrondo/vuln-bank/blob/main/auth.py"
click node_db_py "https://github.com/tekrondo/vuln-bank/blob/main/database.py"
click node_templates "https://github.com/tekrondo/vuln-bank/tree/main/templates"
click node_style_css "https://github.com/tekrondo/vuln-bank/blob/main/static/style.css"
click node_openapi "https://github.com/tekrondo/vuln-bank/blob/main/static/openapi.json"
click node_uploads "https://github.com/tekrondo/vuln-bank/tree/main/static/uploads"
click node_compose "https://github.com/tekrondo/vuln-bank/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/tekrondo/vuln-bank/tree/main/Dockerfile"

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,node_auth_py toneBlue
class node_templates,node_style_css,node_openapi toneAmber
class node_db_py,node_uploads,node_postgres toneMint
class node_compose,node_dockerfile toneRose
```

## Components

### Runtime

Flask monolith and request handling

- **Browser**: client · Primary user client for HTML pages and API calls
- [App](https://github.com/tekrondo/vuln-bank/blob/main/app.py): flask monolith · Main Flask application with routes and response handling · `app.py`
- [Auth](https://github.com/tekrondo/vuln-bank/blob/main/auth.py): identity/token · Login, token, and password reset logic · `auth.py`

### Presentation

Server-rendered pages and shared assets

- [Templates](https://github.com/tekrondo/vuln-bank/tree/main/templates): jinja views · Server-rendered pages for landing, auth, dashboard, and admin · `templates`
- [Styles](https://github.com/tekrondo/vuln-bank/blob/main/static/style.css): css assets · Shared site styling · `static/style.css`
- [API Spec](https://github.com/tekrondo/vuln-bank/blob/main/static/openapi.json): openapi docs · HTTP API documentation and contract · `static/openapi.json`

### Data

Database and local file storage

- [Database](https://github.com/tekrondo/vuln-bank/blob/main/database.py): pg access · PostgreSQL connection, initialization, and queries · `database.py`
- [Uploads](https://github.com/tekrondo/vuln-bank/tree/main/static/uploads): filesystem store · Local on-disk storage for uploaded files · `static/uploads`
- **PostgreSQL**: database · Primary persistent store for users, transactions, loans, and related banking data

### Deployment

Container build and compose setup

- [Compose](https://github.com/tekrondo/vuln-bank/blob/main/docker-compose.yml): runtime stack · Defines web app and database containers · `docker-compose.yml`
- [Dockerfile](https://github.com/tekrondo/vuln-bank/tree/main/Dockerfile): image build · Builds the application container image · `Dockerfile`

## Connections

- 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
