# victoazam/sapoupei architecture

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

- Interactive diagram: https://gitdiagram.com/victoazam/sapoupei
- Repository: https://github.com/victoazam/sapoupei

## Overview

sapoupei is a Flask financial-education and personal budgeting application with a separate administrator area for aggregated reporting. Users register or sign in, manage their own income and expenses, and view budget summaries, goals, and educational guidance; administrators view population-level metrics and export aggregated CSV reports. The graph reflects the sampled route, service, model, and application code plus documented capabilities. Some UI and PWA details are documented but not fully sampled, so their connections are limited to documented relationships.

Main entry points: [`app.py`](https://github.com/victoazam/sapoupei/blob/main/app.py) (Flask app), [`routes/financeiro.py`](https://github.com/victoazam/sapoupei/blob/main/routes/financeiro.py) (Finance routes), [`routes/admin.py`](https://github.com/victoazam/sapoupei/blob/main/routes/admin.py) (Admin reports), [`routes/auth.py`](https://github.com/victoazam/sapoupei/blob/main/routes/auth.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_api_entry["API entry<br/>[index.py]"]
  node_flask_app["Flask app<br/>[app.py]"]
  node_pwa_worker["Offline asset cache<br/>[service-worker.js]"]
  node_pwa_manifest["PWA installation metadata<br/>[manifest.json]"]
  node_browser_js["Browser interactions<br/>[app.js]"]
end

subgraph group_identity["Identity and access"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_auth_tokens["Reset tokens<br/>[auth.py]"]
end

subgraph group_personal["Personal finance"]
  node_finance_routes["Finance routes<br/>[financeiro.py]"]
  node_financial_service["Financial rules<br/>[financial.py]"]
  node_personal_dashboard["Personal dashboard<br/>[painel.html]"]
  node_movement_pages["Movement pages"]
  node_goal_page["Monthly goal page<br/>[meta_mensal.html]"]
  node_tips_page["Education and tips<br/>[dicas.html]"]
end

subgraph group_admin["Administration"]
  node_admin_routes["Admin reports<br/>[admin.py]"]
  node_admin_dashboard["Admin dashboard<br/>[dashboard.html]"]
  node_csv_report["CSV export<br/>[admin.py]"]
end

subgraph group_shared["Shared services and data"]
  node_forms["Forms and validation<br/>[forms.py]"]
  node_extensions["Flask extensions<br/>[extensions.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_config["Database configuration<br/>[config.py]"]
  node_mysql[("MySQL database")]
  node_mail["Mail service"]
end

node_user(("User"))
node_admin_actor(("Administrator"))

node_user -->|"opens app"| node_api_entry
node_api_entry -->|"imports app"| node_flask_app
node_flask_app -->|"registers routes"| node_auth_routes
node_flask_app -->|"registers routes"| node_finance_routes
node_flask_app -->|"registers routes"| node_admin_routes
node_auth_routes -->|"validates forms"| node_forms
node_finance_routes -->|"validates forms"| node_forms
node_auth_routes -->|"creates tokens"| node_auth_tokens
node_auth_routes -->|"sends reset email"| node_mail
node_auth_routes -->|"reads and writes users"| node_models
node_finance_routes -->|"reads and writes finance data"| node_models
node_finance_routes -->|"refreshes profiles"| node_financial_service
node_flask_app -->|"builds dashboard totals"| node_financial_service
node_flask_app -->|"queries dashboard data"| node_models
node_admin_actor -->|"requests reports"| node_admin_routes
node_admin_routes -->|"queries aggregates"| node_models
node_admin_routes -->|"classifies profiles"| node_financial_service
node_admin_routes -->|"exports CSV"| node_csv_report
node_flask_app -->|"renders dashboard"| node_personal_dashboard
node_finance_routes -->|"renders movement views"| node_movement_pages
node_finance_routes -->|"renders goal page"| node_goal_page
node_finance_routes -->|"renders tips"| node_tips_page
node_admin_routes -->|"renders report"| node_admin_dashboard
node_models -->|"persists records"| node_mysql
node_config -->|"configures connection"| node_mysql
node_flask_app -->|"initializes extensions"| node_extensions
node_flask_app -->|"serves worker"| node_pwa_worker
node_user -.->|"installs PWA"| node_pwa_manifest
node_pwa_worker -.->|"caches static assets"| node_browser_js

click node_api_entry "https://github.com/victoazam/sapoupei/blob/main/api/index.py"
click node_flask_app "https://github.com/victoazam/sapoupei/blob/main/app.py"
click node_auth_routes "https://github.com/victoazam/sapoupei/blob/main/routes/auth.py"
click node_auth_tokens "https://github.com/victoazam/sapoupei/blob/main/services/auth.py"
click node_forms "https://github.com/victoazam/sapoupei/blob/main/forms.py"
click node_finance_routes "https://github.com/victoazam/sapoupei/blob/main/routes/financeiro.py"
click node_financial_service "https://github.com/victoazam/sapoupei/blob/main/services/financial.py"
click node_personal_dashboard "https://github.com/victoazam/sapoupei/blob/main/templates/painel.html"
click node_movement_pages "https://github.com/victoazam/sapoupei/tree/main/templates/financeiro"
click node_goal_page "https://github.com/victoazam/sapoupei/blob/main/templates/financeiro/meta_mensal.html"
click node_tips_page "https://github.com/victoazam/sapoupei/blob/main/templates/financeiro/dicas.html"
click node_admin_routes "https://github.com/victoazam/sapoupei/blob/main/routes/admin.py"
click node_admin_dashboard "https://github.com/victoazam/sapoupei/blob/main/templates/admin/dashboard.html"
click node_csv_report "https://github.com/victoazam/sapoupei/blob/main/routes/admin.py"
click node_extensions "https://github.com/victoazam/sapoupei/blob/main/extensions.py"
click node_models "https://github.com/victoazam/sapoupei/blob/main/models.py"
click node_config "https://github.com/victoazam/sapoupei/blob/main/config.py"
click node_pwa_worker "https://github.com/victoazam/sapoupei/blob/main/static/service-worker.js"
click node_pwa_manifest "https://github.com/victoazam/sapoupei/blob/main/static/manifest.json"
click node_browser_js "https://github.com/victoazam/sapoupei/blob/main/static/js/app.js"

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_api_entry,node_flask_app,node_pwa_worker,node_pwa_manifest,node_browser_js,node_user toneBlue
class node_auth_routes,node_auth_tokens toneAmber
class node_finance_routes,node_financial_service,node_personal_dashboard,node_movement_pages,node_goal_page,node_tips_page toneMint
class node_admin_routes,node_admin_dashboard,node_csv_report toneRose
class node_forms,node_extensions,node_models,node_config,node_mysql,node_mail,node_admin_actor toneIndigo
```

## Components

### Web application

- [API entry](https://github.com/victoazam/sapoupei/blob/main/api/index.py): `api/index.py`
- [Flask app](https://github.com/victoazam/sapoupei/blob/main/app.py): `app.py`
- [Offline asset cache](https://github.com/victoazam/sapoupei/blob/main/static/service-worker.js): `static/service-worker.js`
- [PWA installation metadata](https://github.com/victoazam/sapoupei/blob/main/static/manifest.json): `static/manifest.json`
- [Browser interactions](https://github.com/victoazam/sapoupei/blob/main/static/js/app.js): `static/js/app.js`

### Identity and access

- [Authentication routes](https://github.com/victoazam/sapoupei/blob/main/routes/auth.py): `routes/auth.py`
- [Reset tokens](https://github.com/victoazam/sapoupei/blob/main/services/auth.py): `services/auth.py`

### Personal finance

- [Finance routes](https://github.com/victoazam/sapoupei/blob/main/routes/financeiro.py): `routes/financeiro.py`
- [Financial rules](https://github.com/victoazam/sapoupei/blob/main/services/financial.py): `services/financial.py`
- [Personal dashboard](https://github.com/victoazam/sapoupei/blob/main/templates/painel.html): `templates/painel.html`
- [Movement pages](https://github.com/victoazam/sapoupei/tree/main/templates/financeiro): `templates/financeiro`
- [Monthly goal page](https://github.com/victoazam/sapoupei/blob/main/templates/financeiro/meta_mensal.html): `templates/financeiro/meta_mensal.html`
- [Education and tips](https://github.com/victoazam/sapoupei/blob/main/templates/financeiro/dicas.html): `templates/financeiro/dicas.html`

### Administration

- [Admin reports](https://github.com/victoazam/sapoupei/blob/main/routes/admin.py): `routes/admin.py`
- [Admin dashboard](https://github.com/victoazam/sapoupei/blob/main/templates/admin/dashboard.html): `templates/admin/dashboard.html`
- [CSV export](https://github.com/victoazam/sapoupei/blob/main/routes/admin.py): `routes/admin.py`

### Shared services and data

- [Forms and validation](https://github.com/victoazam/sapoupei/blob/main/forms.py): `forms.py`
- [Flask extensions](https://github.com/victoazam/sapoupei/blob/main/extensions.py): `extensions.py`
- [Domain models](https://github.com/victoazam/sapoupei/blob/main/models.py): `models.py`
- [Database configuration](https://github.com/victoazam/sapoupei/blob/main/config.py): `config.py`
- **MySQL database**
- **Mail service**

### Other components

- **User**
- **Administrator**

## Connections

- User → API entry: opens app
- API entry → Flask app: imports app (evidence: `api/index.py`)
- Flask app → Authentication routes: registers routes (evidence: `app.py`)
- Flask app → Finance routes: registers routes (evidence: `app.py`)
- Flask app → Admin reports: registers routes (evidence: `app.py`)
- Authentication routes → Forms and validation: validates forms (evidence: `routes/auth.py`)
- Finance routes → Forms and validation: validates forms (evidence: `routes/financeiro.py`)
- Authentication routes → Reset tokens: creates tokens (evidence: `routes/auth.py`)
- Authentication routes → Mail service: sends reset email (evidence: `routes/auth.py`)
- Authentication routes → Domain models: reads and writes users (evidence: `routes/auth.py`)
- Finance routes → Domain models: reads and writes finance data (evidence: `routes/financeiro.py`)
- Finance routes → Financial rules: refreshes profiles (evidence: `routes/financeiro.py`)
- Flask app → Financial rules: builds dashboard totals (evidence: `app.py`)
- Flask app → Domain models: queries dashboard data (evidence: `app.py`)
- Administrator → Admin reports: requests reports (evidence: `routes/admin.py`)
- Admin reports → Domain models: queries aggregates (evidence: `routes/admin.py`)
- Admin reports → Financial rules: classifies profiles (evidence: `routes/admin.py`)
- Admin reports → CSV export: exports CSV (evidence: `routes/admin.py`)
- Flask app → Personal dashboard: renders dashboard (evidence: `app.py`)
- Finance routes → Movement pages: renders movement views (evidence: `routes/financeiro.py`)
- Finance routes → Monthly goal page: renders goal page (evidence: `routes/financeiro.py`)
- Finance routes → Education and tips: renders tips (evidence: `routes/financeiro.py`)
- Admin reports → Admin dashboard: renders report (evidence: `routes/admin.py`)
- Domain models → MySQL database: persists records (evidence: `models.py`)
- Database configuration → MySQL database: configures connection (evidence: `config.py`)
- Flask app → Flask extensions: initializes extensions (evidence: `app.py`)
- Flask app → Offline asset cache: serves worker (evidence: `app.py`)
- User → PWA installation metadata: installs PWA (evidence: `README.md`)
- Offline asset cache → Browser interactions: caches static assets (evidence: `static/service-worker.js`)
