# aloxvim/gestion-gastos architecture

> Architecture diagram of the GitHub repository aloxvim/gestion-gastos, 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/aloxvim/gestion-gastos
- Repository: https://github.com/aloxvim/gestion-gastos

## Overview

Gestión de Gastos is a personal-finance application with a React web client, PHP REST backend, MySQL persistence, and a Telegram bot client. Users authenticate (including optional email 2FA), manage accounts and income, expenses, and transfers, then review balances, history, and AI-assisted analysis. Administrators manage users and audit-related functions. The README documents the major capabilities and the bot’s API integration; edges between unsampled feature pages and backend routes are omitted where source excerpts do not establish the specific calls.

Main entry points: [`backend/public/api/index.php`](https://github.com/aloxvim/gestion-gastos/blob/main/backend/public/api/index.php) (REST API router), [`frontend/src/App.jsx`](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/App.jsx) (Web routes), [`telegram_bot/services/api_client.py`](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/services/api_client.py) (Bot API client), [`telegram_bot/bot.py`](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/bot.py) (Bot dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["Web routes<br/>[App.jsx]"]
  node_auth_context["Web authentication<br/>[AuthContext.jsx]"]
  node_web_api["Web API client<br/>[api.js]"]
  node_accounts_page["Accounts<br/>[AccountsPage.jsx]"]
  node_movements_page["Movements<br/>[MovementsPage.jsx]"]
  node_dashboard_page["Dashboard<br/>[DashboardPage.jsx]"]
  node_analysis_page["AI analysis page<br/>[AnalysisPage.jsx]"]
  node_settings_page["Settings<br/>[SettingsPage.jsx]"]
  node_admin_page["Administration<br/>[AdminPage.jsx]"]
  node_ui_controls["Common controls<br/>[Button.jsx]"]
  node_input_control["Input control<br/>[Input.jsx]"]
end

subgraph group_backend["Backend services"]
  node_api_entry["REST API router<br/>[index.php]"]
  node_auth_controller["Authentication<br/>[AuthController.php]"]
  node_user_controller["User services<br/>[UserController.php]"]
  node_account_controller["Account services"]
  node_movement_controller["Movement services"]
  node_analysis_controller["Analysis services"]
  node_admin_controller["Admin services"]
  node_tag_controller["Tag services<br/>[TagController.php]"]
end

subgraph group_finance["Finance domain"]
  node_account_model["Account domain<br/>[Cuenta.php]"]
  node_movement_model["Movement domain<br/>[Movimiento.php]"]
  node_tag_model["Tag domain<br/>[Etiqueta.php]"]
  node_user_model["User domain<br/>[Usuario.php]"]
  node_session_model["Session domain<br/>[Sesion.php]"]
  node_ai_config["AI configuration"]
end

subgraph group_bot["Telegram bot"]
  node_telegram_bot["Bot dispatcher<br/>[bot.py]"]
  node_bot_auth["Bot authentication<br/>[auth_handlers.py]"]
  node_bot_queries["Bot queries<br/>[query_handlers.py]"]
  node_bot_movements["Bot movements"]
  node_bot_transfers["Bot transfers"]
  node_bot_sessions["Bot sessions<br/>[session_manager.py]"]
  node_bot_api["Bot API client<br/>[api_client.py]"]
end

subgraph group_storage["Persistence and AI"]
end

node_person(("User"))
node_telegram_user(("Telegram user"))

node_person -->|"uses"| node_app
node_app -->|"reads auth"| node_auth_context
node_app -->|"routes to"| node_accounts_page
node_app -->|"routes to"| node_movements_page
node_app -->|"routes to"| node_dashboard_page
node_app -->|"routes to"| node_analysis_page
node_app -->|"routes to"| node_settings_page
node_app -->|"routes to"| node_admin_page
node_auth_context -->|"calls"| node_web_api
node_accounts_page -->|"calls"| node_web_api
node_settings_page -->|"calls"| node_web_api
node_accounts_page -->|"renders"| node_ui_controls
node_accounts_page -->|"renders"| node_input_control
node_settings_page -->|"renders"| node_ui_controls
node_settings_page -->|"renders"| node_input_control
node_web_api -->|"HTTP requests"| node_api_entry
node_telegram_user -->|"messages"| node_telegram_bot
node_telegram_bot -->|"dispatches"| node_bot_auth
node_telegram_bot -->|"dispatches"| node_bot_queries
node_telegram_bot -->|"dispatches"| node_bot_movements
node_telegram_bot -->|"dispatches"| node_bot_transfers
node_bot_auth -->|"creates session"| node_bot_sessions
node_bot_queries -->|"checks session"| node_bot_sessions
node_bot_movements -->|"uses session"| node_bot_sessions
node_bot_transfers -->|"uses session"| node_bot_sessions
node_bot_sessions -->|"creates client"| node_bot_api
node_bot_auth -->|"authenticates"| node_bot_api
node_bot_queries -->|"queries"| node_bot_api
node_bot_movements -->|"submits actions"| node_bot_api
node_bot_transfers -->|"submits transfers"| node_bot_api
node_bot_api -->|"HTTP requests"| node_api_entry
node_api_entry -->|"routes to"| node_auth_controller
node_api_entry -->|"routes to"| node_user_controller
node_api_entry -->|"routes to"| node_account_controller
node_api_entry -->|"routes to"| node_movement_controller
node_api_entry -->|"routes to"| node_analysis_controller
node_api_entry -->|"routes to"| node_admin_controller
node_api_entry -->|"routes to"| node_tag_controller
node_auth_controller -->|"uses"| node_user_model
node_auth_controller -->|"uses"| node_session_model
node_user_controller -->|"uses"| node_user_model
node_user_controller -->|"uses"| node_session_model
node_user_controller -->|"uses"| node_account_model
node_account_controller -->|"uses"| node_account_model
node_account_controller -->|"uses"| node_tag_model
node_movement_controller -->|"uses"| node_movement_model
node_movement_controller -->|"validates accounts"| node_account_model
node_analysis_controller -->|"loads analysis data"| node_movement_model

click node_app "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_web_api "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/services/api.js"
click node_accounts_page "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/AccountsPage.jsx"
click node_movements_page "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/MovementsPage.jsx"
click node_dashboard_page "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_analysis_page "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/AnalysisPage.jsx"
click node_settings_page "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/SettingsPage.jsx"
click node_admin_page "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/AdminPage.jsx"
click node_ui_controls "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/components/common/Button.jsx"
click node_input_control "https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/components/common/Input.jsx"
click node_api_entry "https://github.com/aloxvim/gestion-gastos/blob/main/backend/public/api/index.php"
click node_auth_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AuthController.php"
click node_user_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/UserController.php"
click node_account_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AccountController.php"
click node_movement_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/MovementController.php"
click node_analysis_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AnalysisController.php"
click node_admin_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AdminController.php"
click node_tag_controller "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/TagController.php"
click node_account_model "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Cuenta.php"
click node_movement_model "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Movimiento.php"
click node_tag_model "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Etiqueta.php"
click node_user_model "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Usuario.php"
click node_session_model "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Sesion.php"
click node_ai_config "https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/ConfiguracionIA.php"
click node_telegram_bot "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/bot.py"
click node_bot_auth "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/auth_handlers.py"
click node_bot_queries "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/query_handlers.py"
click node_bot_movements "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/movement_handlers.py"
click node_bot_transfers "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/transfer_handlers.py"
click node_bot_sessions "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/services/session_manager.py"
click node_bot_api "https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/services/api_client.py"

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_app,node_auth_context,node_web_api,node_accounts_page,node_movements_page,node_dashboard_page,node_analysis_page,node_settings_page,node_admin_page,node_ui_controls,node_input_control,node_person,node_telegram_user toneBlue
class node_api_entry,node_auth_controller,node_user_controller,node_account_controller,node_movement_controller,node_analysis_controller,node_admin_controller,node_tag_controller toneAmber
class node_account_model,node_movement_model,node_tag_model,node_user_model,node_session_model,node_ai_config toneMint
class node_telegram_bot,node_bot_auth,node_bot_queries,node_bot_movements,node_bot_transfers,node_bot_sessions,node_bot_api toneRose
```

## Components

### Web application

- [Web routes](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Web authentication](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/contexts/AuthContext.jsx): `frontend/src/contexts/AuthContext.jsx`
- [Web API client](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Accounts](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/AccountsPage.jsx): `frontend/src/pages/AccountsPage.jsx`
- [Movements](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/MovementsPage.jsx): `frontend/src/pages/MovementsPage.jsx`
- [Dashboard](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/DashboardPage.jsx): `frontend/src/pages/DashboardPage.jsx`
- [AI analysis page](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/AnalysisPage.jsx): `frontend/src/pages/AnalysisPage.jsx`
- [Settings](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/SettingsPage.jsx): `frontend/src/pages/SettingsPage.jsx`
- [Administration](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/pages/AdminPage.jsx): `frontend/src/pages/AdminPage.jsx`
- [Common controls](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/components/common/Button.jsx): `frontend/src/components/common/Button.jsx`
- [Input control](https://github.com/aloxvim/gestion-gastos/blob/main/frontend/src/components/common/Input.jsx): `frontend/src/components/common/Input.jsx`

### Backend services

- [REST API router](https://github.com/aloxvim/gestion-gastos/blob/main/backend/public/api/index.php): `backend/public/api/index.php`
- [Authentication](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AuthController.php): `backend/app/controllers/AuthController.php`
- [User services](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/UserController.php): `backend/app/controllers/UserController.php`
- [Account services](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AccountController.php): `backend/app/controllers/AccountController.php`
- [Movement services](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/MovementController.php): `backend/app/controllers/MovementController.php`
- [Analysis services](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AnalysisController.php): `backend/app/controllers/AnalysisController.php`
- [Admin services](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/AdminController.php): `backend/app/controllers/AdminController.php`
- [Tag services](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/controllers/TagController.php): `backend/app/controllers/TagController.php`

### Finance domain

- [Account domain](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Cuenta.php): `backend/app/models/Cuenta.php`
- [Movement domain](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Movimiento.php): `backend/app/models/Movimiento.php`
- [Tag domain](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Etiqueta.php): `backend/app/models/Etiqueta.php`
- [User domain](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Usuario.php): `backend/app/models/Usuario.php`
- [Session domain](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/Sesion.php): `backend/app/models/Sesion.php`
- [AI configuration](https://github.com/aloxvim/gestion-gastos/blob/main/backend/app/models/ConfiguracionIA.php): `backend/app/models/ConfiguracionIA.php`

### Telegram bot

- [Bot dispatcher](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/bot.py): `telegram_bot/bot.py`
- [Bot authentication](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/auth_handlers.py): `telegram_bot/handlers/auth_handlers.py`
- [Bot queries](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/query_handlers.py): `telegram_bot/handlers/query_handlers.py`
- [Bot movements](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/movement_handlers.py): `telegram_bot/handlers/movement_handlers.py`
- [Bot transfers](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/handlers/transfer_handlers.py): `telegram_bot/handlers/transfer_handlers.py`
- [Bot sessions](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/services/session_manager.py): `telegram_bot/services/session_manager.py`
- [Bot API client](https://github.com/aloxvim/gestion-gastos/blob/main/telegram_bot/services/api_client.py): `telegram_bot/services/api_client.py`

### Other components

- **User**
- **Telegram user**

## Connections

- User → Web routes: uses
- Web routes → Web authentication: reads auth (evidence: `frontend/src/App.jsx`)
- Web routes → Accounts: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Movements: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → AI analysis page: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Settings: routes to (evidence: `frontend/src/App.jsx`)
- Web routes → Administration: routes to (evidence: `frontend/src/App.jsx`)
- Web authentication → Web API client: calls (evidence: `frontend/src/contexts/AuthContext.jsx`)
- Accounts → Web API client: calls (evidence: `frontend/src/pages/AccountsPage.jsx`)
- Settings → Web API client: calls (evidence: `frontend/src/pages/SettingsPage.jsx`)
- Accounts → Common controls: renders (evidence: `frontend/src/pages/AccountsPage.jsx`)
- Accounts → Input control: renders (evidence: `frontend/src/pages/AccountsPage.jsx`)
- Settings → Common controls: renders (evidence: `frontend/src/pages/SettingsPage.jsx`)
- Settings → Input control: renders (evidence: `frontend/src/pages/SettingsPage.jsx`)
- Web API client → REST API router: HTTP requests
- Telegram user → Bot dispatcher: messages
- Bot dispatcher → Bot authentication: dispatches (evidence: `telegram_bot/bot.py`)
- Bot dispatcher → Bot queries: dispatches (evidence: `telegram_bot/bot.py`)
- Bot dispatcher → Bot movements: dispatches (evidence: `telegram_bot/bot.py`)
- Bot dispatcher → Bot transfers: dispatches (evidence: `telegram_bot/bot.py`)
- Bot authentication → Bot sessions: creates session (evidence: `telegram_bot/handlers/auth_handlers.py`)
- Bot queries → Bot sessions: checks session (evidence: `telegram_bot/handlers/query_handlers.py`)
- Bot movements → Bot sessions: uses session (evidence: `telegram_bot/handlers/movement_handlers.py`)
- Bot transfers → Bot sessions: uses session (evidence: `telegram_bot/handlers/transfer_handlers.py`)
- Bot sessions → Bot API client: creates client (evidence: `telegram_bot/services/session_manager.py`)
- Bot authentication → Bot API client: authenticates (evidence: `telegram_bot/handlers/auth_handlers.py`)
- Bot queries → Bot API client: queries (evidence: `telegram_bot/handlers/query_handlers.py`)
- Bot movements → Bot API client: submits actions (evidence: `telegram_bot/handlers/movement_handlers.py`)
- Bot transfers → Bot API client: submits transfers (evidence: `telegram_bot/handlers/transfer_handlers.py`)
- Bot API client → REST API router: HTTP requests
- REST API router → Authentication: routes to (evidence: `backend/public/api/index.php`)
- REST API router → User services: routes to (evidence: `backend/public/api/index.php`)
- REST API router → Account services: routes to (evidence: `backend/public/api/index.php`)
- REST API router → Movement services: routes to (evidence: `backend/public/api/index.php`)
- REST API router → Analysis services: routes to (evidence: `backend/public/api/index.php`)
- REST API router → Admin services: routes to (evidence: `backend/public/api/index.php`)
- REST API router → Tag services: routes to (evidence: `backend/public/api/index.php`)
- Authentication → User domain: uses (evidence: `backend/app/controllers/AuthController.php`)
- Authentication → Session domain: uses (evidence: `backend/app/controllers/AuthController.php`)
- User services → User domain: uses (evidence: `backend/app/controllers/UserController.php`)
- User services → Session domain: uses (evidence: `backend/app/controllers/UserController.php`)
- User services → Account domain: uses (evidence: `backend/app/controllers/UserController.php`)
- Account services → Account domain: uses (evidence: `backend/app/controllers/AccountController.php`)
- Account services → Tag domain: uses (evidence: `backend/app/controllers/AccountController.php`)
- Movement services → Movement domain: uses (evidence: `backend/app/controllers/MovementController.php`)
- Movement services → Account domain: validates accounts (evidence: `backend/app/controllers/MovementController.php`)
- Analysis services → Movement domain: loads analysis data (evidence: `backend/app/controllers/AnalysisController.php`)
