# equipo-sistemas-catastro/carga_mutaciones architecture

> Architecture diagram of the GitHub repository equipo-sistemas-catastro/carga_mutaciones, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/equipo-sistemas-catastro/carga_mutaciones
- Repository: https://github.com/equipo-sistemas-catastro/carga_mutaciones

## Overview

##### Project type and purpose
- This is a backend-only data-processing API built in Python using FastAPI. Its primary purpose is to ingest fixed-format `.txt` files of cadastral (“mutaciones registrales”) data, validate and transform them (Pydantic), persist them to a PostgreSQL database (SQLAlchemy), and expose REST endpoints for querying and triggering processing.

##### File structure
- Top-level “app/” folder contains the entire FastAPI application.
- app/api/v1/endpoints.py: API router for version “v1.”
- app/core/: configuration (config.py) and security utilities.
- app/models/: SQLAlchemy ORM definitions (registro.py).
- app/schemas/: Pydantic models for request/response (registro, paginacion).
- app/crud/: database CRUD logic (registro).
- app/db/: session creation and DB initialization.
- app/services/: business logic, file ingestion (cargar_txt), mutation distribution, post-distribution tasks.
- app/querys/: raw SQL queries used by services or CRUD.
- app/main.py: the FastAPI “entrypoint.”
- app/run_carga.py: probably a CLI or script wrapper to trigger batch loads.
- tests/ folder holds pytest tests for file processing and DB.
- temp/: sample input files and target directories configured via environment variables.
- requirements.txt, .gitignore, and uvicorn (runner script or config).

##### Key architectural insights from README
- REST API using FastAPI.
- PostgreSQL DB accessed via SQLAlchemy with Pydantic validation.
- Environment-driven configuration.
- Automated file-based ingestion pipelines that move files from origin to “success” or “failure” folders.

##### Main components
a. Client Layer
- API consumers: users, scripts, or external systems calling the REST endpoints (e.g., GET /registros, POST /cargar).
b. API Layer (FastAPI)
- Router (app/api/v1/endpoints.py)
- Dependency injection for config, DB session, security.
c. Service Layer
- FileProcessor Service (cargar_txt)
- MutationDistributor Service (distribuir_mutaciones)
- PostDistribution Service (post_distribucion)
d. Data Access Layer
- CRUD module (app/crud/registro.py)
- Raw SQL queries in app/querys/
- SQLAlchemy models (app/models/registro.py)
e. Database
- PostgreSQL instance (PG_USER, PG_PASSWORD, etc.)
- Tables per ORM models
f. Filesystem
- Input folder (CARPETA_ORIGEN_MUTACIONES)
- Success folder (CARPETA_EXITOSO_MUTACIONES)
- Failure folder (CARPETA_FALLIDO_MUTACIONES)
g. Auxiliary
- Session management (app/db/session.py)
- App configuration (app/core/config.py)
- Authentication/security (app/core/security.py)
- Uvicorn/Gunicorn as ASGI server

##### Interactions and data flow
1. Client issues an HTTP request → FastAPI router.
2. Router calls service layer.
3. Service reads files from origin folder, parses lines (Pydantic), maps to ORM models.
4. CRUD layer persists records to PostgreSQL.
5. After processing, files move to either “success” or “failure” directory.
6. Additional endpoints query the DB via CRUD and return paginated responses.

##### Architectural patterns and design principles
- Layered architecture (API → Services → CRUD → DB).
- Separation of concerns: Pydantic for validation, SQLAlchemy for persistence, services for business logic.
- Configuration via environment variables.
- Single responsibility for each module.

##### Final advice
- Be very detailed: capture sub-components (config, session, models, schemas).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client["HTTP Client<br/>(Consumers, Scripts)"]:::external

    %% API Layer
    subgraph "API Layer"
        direction TB
        Entrypoint["app/main.py<br/>ASGI EntryPoint"]:::api
        Router["Router<br/>(app/api/v1/endpoints.py)"]:::api
        Dependencies["Dependencies<br/>(Config, Session, Security)"]:::config
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        FileProcessor["FileProcessor Service<br/>(cargar_txt)"]:::service
        Distributor["Mutation Distributor Service<br/>(distribuir_mutaciones)"]:::service
        PostDist["Post-Distribution Service<br/>(post_distribucion)"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        Models["ORM Models<br/>(app/models/registro.py)"]:::data
        Schemas["Pydantic Schemas<br/>(registro, paginacion)"]:::data
        CRUD["CRUD Module<br/>(app/crud/registro.py)"]:::data
        Queries["Raw SQL Queries<br/>(app/querys/)"]:::data
    end

    %% Database
    Database[("PostgreSQL Database")]:::db

    %% Filesystem
    subgraph "Filesystem"
        direction TB
        Origin["Input Folder<br/>(CARPETA_ORIGEN_MUTACIONES)"]:::fs
        Success["Success Folder<br/>(CARPETA_EXITOSO_MUTACIONES)"]:::fs
        Failure["Failure Folder<br/>(CARPETA_FALLIDO_MUTACIONES)"]:::fs
    end

    %% Auxiliary
    Uvicorn["uvicorn<br/>ASGI Server"]:::external
    RunCarga["Batch Load Script<br/>(app/run_carga.py)"]:::external
    Requirements["requirements.txt"]:::external

    %% Connections
    Client -->|"HTTP Request"| Router
    Router -->|"calls"| FileProcessor
    Router -->|"calls"| Distributor
    Router -->|"calls"| PostDist

    Entrypoint -->|"includes"| Router
    Entrypoint -->|"includes"| Dependencies
    Entrypoint -->|"runs on"| Uvicorn

    Dependencies -.->|"provides config"| FileProcessor
    Dependencies -.->|"provides config"| Distributor
    Dependencies -.->|"provides config"| PostDist
    Dependencies -.->|"provides DB session"| CRUD

    FileProcessor -->|"validate (Pydantic)"| Schemas
    FileProcessor -->|"map to ORM"| Models
    FileProcessor -->|"persist"| CRUD
    FileProcessor -->|"read/move"| Origin
    FileProcessor -->|"move to success"| Success
    FileProcessor -->|"move to failure"| Failure

    Distributor -->|"uses raw SQL"| Queries
    Distributor -->|"persist"| CRUD

    PostDist -->|"post tasks"| CRUD

    CRUD -->|"queries"| Database
    Queries -->|"queries"| Database
    Models -->|"defines tables"| Database

    RunCarga -->|"triggers"| FileProcessor

    Requirements -.-> Entrypoint
    Requirements -.-> RunCarga

    %% Click Events
    click Entrypoint "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/main.py"
    click Router "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/api/v1/endpoints.py"
    click RunCarga "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/run_carga.py"
    click Dependencies "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/core/config.py"
    click Dependencies "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/core/security.py"
    click FileProcessor "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/services/cargar_txt.py"
    click Distributor "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/services/distribuir_mutaciones.py"
    click PostDist "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/services/post_distribucion.py"
    click Models "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/models/registro.py"
    click Schemas "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/schemas/registro.py"
    click Schemas "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/schemas/paginacion.py"
    click CRUD "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/crud/registro.py"
    click Queries "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/querys/querys.sql"
    click Queries "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/querys/querys.txt"
    click Uvicorn "https://github.com/equipo-sistemas-catastro/carga_mutaciones/tree/master/uvicorn"
    click Requirements "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/requirements.txt"
    click Dependencies "https://github.com/equipo-sistemas-catastro/carga_mutaciones/blob/master/app/db/session.py"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef service fill:#E0FFE0,stroke:#28A745,color:#28A745
    classDef data fill:#FFF5BA,stroke:#DBAB09,color:#DBAB09
    classDef db fill:#FFDFE0,stroke:#D73A49,color:#D73A49
    classDef fs fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef external fill:#F5F5F5,stroke:#888888,color:#333333
    classDef config fill:#FFE4E1,stroke:#D73A49,color:#D73A49
```
