How equipo-sistemas-catastro/carga_mutaciones works
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).