danskers/finances_api

Purpose and Runtime

Finanzas Media is a server-rendered personal-finance application: users manage accounts, income, expenses, debts, monthly history, and optional receipt images. It runs as a Python FastAPI/ASGI service, normally launched with Uvicorn; its principal application entry point is app/main.py.

HTTP and Presentation Layer

app/main.py owns the FastAPI application, session-oriented routes, page rendering, and the primary request workflow. Jinja2 templates form the UI boundary rather than a separate frontend client:

• templates/dashboard.html

• templates/transacciones.html

• templates/historial.html

Requests render HTML forms/pages and mutate state through POST endpoints. Shared page structure and styling live in templates/base.html and static/styles.css.

Identity and Session Boundary

Authentication is local application logic, with registration/login/logout routed through app/main.py. Password hashing and verification, plus authentication-related mechanisms, are centralized in app/security.py. The app uses cookie sessions; protected finance operations must resolve the current user before accessing user-owned accounts or transactions. There is no separate identity provider indicated.

Finance Domain and Persistence

The relational core is modeled in app/models.py: Usuario owns Cuenta and Transaccion; each transaction belongs to both a user and account and records amount, type, category, optional subcategory, date/month, and optional receipt URL. Request/form data contracts are defined in app/schemas.py.

Persistence is local SQLite through SQLModel/SQLAlchemy:

• app/database.py

• finanzas.db

This creates a clear ownership boundary: account and transaction reads/writes should be scoped by usuario_id, while cuenta_id links movements to a funding source.

Primary Finance Flow

1. A visitor registers or logs in through app/main.py; session state identifies the user.

2. The user creates accounts, then submits transactions tied to a selected account.

3. The service derives/persists transaction month/date metadata in SQLite.

4. Dashboard, current-month transactions, search/history, and deletion routes query the scoped domain data and render templates.

5. Transaction deletion removes the database record; receipt-object lifecycle behavior is not established by the supplied structure.

Receipt Upload Integration

Receipt handling is separated into app/routers/uploads.py, with Supabase initialization/configuration in app/supabase_client.py. The upload boundary accepts an optional image, sends it from the backend to Supabase Storage’s public facturas bucket using a service-role credential, then records the resulting public URL in Transaccion.factura_url.

External dependencies are Supabase Storage for binary receipt storage and public retrieval; credentials come from environment configuration (app/.env exists locally). The service-role key is privileged and must remain server-only.

Deployment and Architectural Constraints

The intended hosting target is Render Web Service, serving the FastAPI process. Material runtime dependencies present in the repository environment include FastAPI, Uvicorn, Jinja2, SQLModel/SQLAlchemy, session/security libraries, and the Supabase Python client. SQLite (finanzas.db) is local-file persistence, so durability and multi-instance behavior depend on the hosting volume/process model; Supabase is used for storage, not shown as the application’s transactional database.