# astv2008/entrecol architecture

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

- Interactive diagram: https://gitdiagram.com/astv2008/entrecol
- Repository: https://github.com/astv2008/entrecol

## Overview

Entrecol is a web application for authorized users to query payroll and entertainment reports and for administrators to load source files. The principal flow is browser → FastAPI routes → report services and repositories → MariaDB, with optional PDF generation. A separate upload flow validates and transforms payroll, book, and movie files before loading them and returning a load report. Authentication adds mandatory TOTP, revocable sessions, roles, and auditing. The graph follows documented capabilities and sampled import/call evidence; unsampled report routes and service internals are shown as subsystems, with uncertain links omitted.

Main entry points: [`backend/app/api/v1/reportes_pdf.py`](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_pdf.py) (PDF report routes), [`backend/app/api/v1/router.py`](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/router.py) (API routes), [`backend/app/api/v1/reportes_nomina.py`](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_nomina.py) (Report routes), [`backend/app/etl/nomina/service.py`](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/service.py) (Payroll ETL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and API"]
  node_frontend["Static frontend<br/>[reportes.js]"]
  node_app["FastAPI application<br/>[main.py]"]
  node_routes["API routes<br/>[router.py]"]
end

subgraph group_security["Identity and audit"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_security_service["Auth and audit service<br/>[service.py]"]
  node_security_deps["Auth dependencies<br/>[dependencies.py]"]
  node_security_models["Security records<br/>[seguridad.py]"]
end

subgraph group_reporting["Reporting"]
  node_report_routes["Report routes<br/>[reportes_nomina.py]"]
  node_entertainment_routes["Entertainment routes"]
  node_pdf_routes["PDF report routes<br/>[reportes_pdf.py]"]
  node_payroll_reports["Payroll report services<br/>[reporte_nomina.py]"]
  node_personal_reports["Personal report services"]
  node_health_report["Health and pension reports"]
  node_novelty_reports["Novelty reports"]
  node_books_reports["Book reports<br/>[reporte_libros.py]"]
  node_movies_reports["Movie reports"]
  node_repositories["Report repositories<br/>[nomina.py]"]
  node_entertainment_repository["Entertainment repository<br/>[entretenimiento.py]"]
  node_pdf["PDF generation<br/>[pdf.py]"]
end

subgraph group_ingestion["Data ingestion"]
  node_upload_routes["Upload routes<br/>[cargas.py]"]
  node_load_report["Load report<br/>[common.py]"]
  node_payroll_etl["Payroll ETL<br/>[service.py]"]
  node_books_etl["Books ETL<br/>[service.py]"]
  node_movies_etl["Movies ETL<br/>[service.py]"]
  node_payroll_extract["Payroll extraction<br/>[extractor.py]"]
  node_books_extract["Book extraction<br/>[extractor.py]"]
  node_movies_extract["Movie extraction<br/>[extractor.py]"]
  node_transformers["File transformers<br/>[transformer.py]"]
  node_catalogs["Catalog resolution<br/>[catalogos.py]"]
  node_payroll_loader["Payroll loader<br/>[loader.py]"]
  node_books_loader["Book loader<br/>[loader.py]"]
  node_movies_loader["Movie loader<br/>[loader.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_session["Database sessions<br/>[session.py]"]
end

node_browser(("Browser user"))

node_browser -->|"uses"| node_frontend
node_frontend -.->|"calls API"| node_app
node_app -->|"mounts"| node_routes
node_routes -->|"registers"| node_auth_routes
node_routes -->|"registers"| node_upload_routes
node_routes -->|"registers"| node_report_routes
node_routes -->|"registers"| node_entertainment_routes
node_routes -->|"registers"| node_pdf_routes
node_auth_routes -->|"uses"| node_security_service
node_auth_routes -->|"uses"| node_security_deps
node_security_deps -->|"uses"| node_security_service
node_security_service -->|"persists"| node_security_models
node_upload_routes -->|"dispatches"| node_payroll_etl
node_upload_routes -->|"dispatches"| node_books_etl
node_upload_routes -->|"dispatches"| node_movies_etl
node_payroll_etl -->|"extracts"| node_payroll_extract
node_books_etl -->|"extracts"| node_books_extract
node_movies_etl -->|"extracts"| node_movies_extract
node_payroll_etl -->|"transforms"| node_transformers
node_books_etl -->|"transforms"| node_transformers
node_movies_etl -->|"transforms"| node_transformers
node_payroll_etl -->|"loads"| node_payroll_loader
node_books_etl -->|"loads"| node_books_loader
node_movies_etl -->|"loads"| node_movies_loader
node_payroll_etl -->|"returns"| node_load_report
node_books_etl -->|"returns"| node_load_report
node_movies_etl -->|"returns"| node_load_report
node_payroll_loader -->|"resolves"| node_catalogs
node_books_loader -->|"resolves"| node_catalogs
node_movies_loader -->|"resolves"| node_catalogs
node_report_routes -.->|"serves"| node_payroll_reports
node_report_routes -.->|"serves"| node_personal_reports
node_report_routes -.->|"serves"| node_health_report
node_report_routes -.->|"serves"| node_novelty_reports
node_entertainment_routes -.->|"serves"| node_books_reports
node_entertainment_routes -.->|"serves"| node_movies_reports
node_pdf_routes -->|"generates"| node_pdf
node_pdf_routes -->|"queries"| node_repositories
node_pdf_routes -->|"queries"| node_entertainment_repository
node_pdf_routes -->|"uses"| node_payroll_reports
node_pdf_routes -->|"uses"| node_personal_reports
node_pdf_routes -->|"uses"| node_health_report
node_pdf_routes -->|"uses"| node_novelty_reports
node_pdf_routes -->|"uses"| node_books_reports
node_pdf_routes -->|"uses"| node_movies_reports
node_repositories -.->|"queries"| node_db_session
node_entertainment_repository -.->|"queries"| node_db_session

click node_frontend "https://github.com/astv2008/entrecol/blob/main/frontend/js/pages/reportes.js"
click node_app "https://github.com/astv2008/entrecol/blob/main/backend/app/main.py"
click node_routes "https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/router.py"
click node_auth_routes "https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/auth.py"
click node_security_service "https://github.com/astv2008/entrecol/blob/main/backend/app/security/service.py"
click node_security_deps "https://github.com/astv2008/entrecol/blob/main/backend/app/security/dependencies.py"
click node_security_models "https://github.com/astv2008/entrecol/blob/main/backend/app/models/seguridad.py"
click node_upload_routes "https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/cargas.py"
click node_load_report "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/common.py"
click node_payroll_etl "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/service.py"
click node_books_etl "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/libros/service.py"
click node_movies_etl "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/peliculas/service.py"
click node_payroll_extract "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/extractor.py"
click node_books_extract "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/libros/extractor.py"
click node_movies_extract "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/peliculas/extractor.py"
click node_transformers "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/transformer.py"
click node_catalogs "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/catalogos.py"
click node_payroll_loader "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/loader.py"
click node_books_loader "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/libros/loader.py"
click node_movies_loader "https://github.com/astv2008/entrecol/blob/main/backend/app/etl/peliculas/loader.py"
click node_report_routes "https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_nomina.py"
click node_entertainment_routes "https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_entretenimiento.py"
click node_pdf_routes "https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_pdf.py"
click node_payroll_reports "https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_nomina.py"
click node_personal_reports "https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_personal.py"
click node_health_report "https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_salud_pension.py"
click node_novelty_reports "https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_novedades.py"
click node_books_reports "https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_libros.py"
click node_movies_reports "https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_peliculas.py"
click node_repositories "https://github.com/astv2008/entrecol/blob/main/backend/app/repositories/nomina.py"
click node_entertainment_repository "https://github.com/astv2008/entrecol/blob/main/backend/app/repositories/entretenimiento.py"
click node_pdf "https://github.com/astv2008/entrecol/blob/main/backend/app/reports/pdf.py"
click node_db_session "https://github.com/astv2008/entrecol/blob/main/backend/app/db/session.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_frontend,node_app,node_routes,node_browser toneBlue
class node_auth_routes,node_security_service,node_security_deps,node_security_models toneAmber
class node_report_routes,node_entertainment_routes,node_pdf_routes,node_payroll_reports,node_personal_reports,node_health_report,node_novelty_reports,node_books_reports,node_movies_reports,node_repositories,node_entertainment_repository,node_pdf toneMint
class node_upload_routes,node_load_report,node_payroll_etl,node_books_etl,node_movies_etl,node_payroll_extract,node_books_extract,node_movies_extract,node_transformers,node_catalogs,node_payroll_loader,node_books_loader,node_movies_loader toneRose
class node_db_session toneIndigo
```

## Components

### Web and API

- [Static frontend](https://github.com/astv2008/entrecol/blob/main/frontend/js/pages/reportes.js): `frontend/js/pages/reportes.js`
- [FastAPI application](https://github.com/astv2008/entrecol/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`

### Identity and audit

- [Authentication routes](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Auth and audit service](https://github.com/astv2008/entrecol/blob/main/backend/app/security/service.py): `backend/app/security/service.py`
- [Auth dependencies](https://github.com/astv2008/entrecol/blob/main/backend/app/security/dependencies.py): `backend/app/security/dependencies.py`
- [Security records](https://github.com/astv2008/entrecol/blob/main/backend/app/models/seguridad.py): `backend/app/models/seguridad.py`

### Reporting

- [Report routes](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_nomina.py): `backend/app/api/v1/reportes_nomina.py`
- [Entertainment routes](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_entretenimiento.py): `backend/app/api/v1/reportes_entretenimiento.py`
- [PDF report routes](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/reportes_pdf.py): `backend/app/api/v1/reportes_pdf.py`
- [Payroll report services](https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_nomina.py): `backend/app/services/reporte_nomina.py`
- [Personal report services](https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_personal.py): `backend/app/services/reporte_personal.py`
- [Health and pension reports](https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_salud_pension.py): `backend/app/services/reporte_salud_pension.py`
- [Novelty reports](https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_novedades.py): `backend/app/services/reporte_novedades.py`
- [Book reports](https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_libros.py): `backend/app/services/reporte_libros.py`
- [Movie reports](https://github.com/astv2008/entrecol/blob/main/backend/app/services/reporte_peliculas.py): `backend/app/services/reporte_peliculas.py`
- [Report repositories](https://github.com/astv2008/entrecol/blob/main/backend/app/repositories/nomina.py): `backend/app/repositories/nomina.py`
- [Entertainment repository](https://github.com/astv2008/entrecol/blob/main/backend/app/repositories/entretenimiento.py): `backend/app/repositories/entretenimiento.py`
- [PDF generation](https://github.com/astv2008/entrecol/blob/main/backend/app/reports/pdf.py): `backend/app/reports/pdf.py`

### Data ingestion

- [Upload routes](https://github.com/astv2008/entrecol/blob/main/backend/app/api/v1/cargas.py): `backend/app/api/v1/cargas.py`
- [Load report](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/common.py): `backend/app/etl/common.py`
- [Payroll ETL](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/service.py): `backend/app/etl/nomina/service.py`
- [Books ETL](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/libros/service.py): `backend/app/etl/libros/service.py`
- [Movies ETL](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/peliculas/service.py): `backend/app/etl/peliculas/service.py`
- [Payroll extraction](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/extractor.py): `backend/app/etl/nomina/extractor.py`
- [Book extraction](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/libros/extractor.py): `backend/app/etl/libros/extractor.py`
- [Movie extraction](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/peliculas/extractor.py): `backend/app/etl/peliculas/extractor.py`
- [File transformers](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/transformer.py): `backend/app/etl/nomina/transformer.py`
- [Catalog resolution](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/catalogos.py): `backend/app/etl/catalogos.py`
- [Payroll loader](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/nomina/loader.py): `backend/app/etl/nomina/loader.py`
- [Book loader](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/libros/loader.py): `backend/app/etl/libros/loader.py`
- [Movie loader](https://github.com/astv2008/entrecol/blob/main/backend/app/etl/peliculas/loader.py): `backend/app/etl/peliculas/loader.py`

### Persistence

- [Database sessions](https://github.com/astv2008/entrecol/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **Browser user**

## Connections

- Browser user → Static frontend: uses
- Static frontend → FastAPI application: calls API
- FastAPI application → API routes: mounts (evidence: `backend/app/main.py`)
- API routes → Authentication routes: registers (evidence: `backend/app/api/v1/router.py`)
- API routes → Upload routes: registers (evidence: `backend/app/api/v1/router.py`)
- API routes → Report routes: registers (evidence: `backend/app/api/v1/router.py`)
- API routes → Entertainment routes: registers (evidence: `backend/app/api/v1/router.py`)
- API routes → PDF report routes: registers (evidence: `backend/app/api/v1/router.py`)
- Authentication routes → Auth and audit service: uses (evidence: `backend/app/api/v1/auth.py`)
- Authentication routes → Auth dependencies: uses (evidence: `backend/app/api/v1/auth.py`)
- Auth dependencies → Auth and audit service: uses (evidence: `backend/app/security/dependencies.py`)
- Auth and audit service → Security records: persists (evidence: `backend/app/security/service.py`)
- Upload routes → Payroll ETL: dispatches (evidence: `backend/app/api/v1/cargas.py`)
- Upload routes → Books ETL: dispatches (evidence: `backend/app/api/v1/cargas.py`)
- Upload routes → Movies ETL: dispatches (evidence: `backend/app/api/v1/cargas.py`)
- Payroll ETL → Payroll extraction: extracts (evidence: `backend/app/etl/nomina/service.py`)
- Books ETL → Book extraction: extracts (evidence: `backend/app/etl/libros/service.py`)
- Movies ETL → Movie extraction: extracts (evidence: `backend/app/etl/peliculas/service.py`)
- Payroll ETL → File transformers: transforms (evidence: `backend/app/etl/nomina/service.py`)
- Books ETL → File transformers: transforms (evidence: `backend/app/etl/libros/service.py`)
- Movies ETL → File transformers: transforms (evidence: `backend/app/etl/peliculas/service.py`)
- Payroll ETL → Payroll loader: loads (evidence: `backend/app/etl/nomina/service.py`)
- Books ETL → Book loader: loads (evidence: `backend/app/etl/libros/service.py`)
- Movies ETL → Movie loader: loads (evidence: `backend/app/etl/peliculas/service.py`)
- Payroll ETL → Load report: returns (evidence: `backend/app/etl/nomina/service.py`)
- Books ETL → Load report: returns (evidence: `backend/app/etl/libros/service.py`)
- Movies ETL → Load report: returns (evidence: `backend/app/etl/peliculas/service.py`)
- Payroll loader → Catalog resolution: resolves (evidence: `backend/app/etl/nomina/loader.py`)
- Book loader → Catalog resolution: resolves (evidence: `backend/app/etl/libros/loader.py`)
- Movie loader → Catalog resolution: resolves (evidence: `backend/app/etl/peliculas/loader.py`)
- Report routes → Payroll report services: serves
- Report routes → Personal report services: serves
- Report routes → Health and pension reports: serves
- Report routes → Novelty reports: serves
- Entertainment routes → Book reports: serves
- Entertainment routes → Movie reports: serves
- PDF report routes → PDF generation: generates (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Report repositories: queries (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Entertainment repository: queries (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Payroll report services: uses (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Personal report services: uses (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Health and pension reports: uses (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Novelty reports: uses (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Book reports: uses (evidence: `backend/app/api/v1/reportes_pdf.py`)
- PDF report routes → Movie reports: uses (evidence: `backend/app/api/v1/reportes_pdf.py`)
- Report repositories → Database sessions: queries
- Entertainment repository → Database sessions: queries
