# esacaris/monitoreo-proin-v2 architecture

> Architecture diagram of the GitHub repository esacaris/monitoreo-proin-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/esacaris/monitoreo-proin-v2
- Repository: https://github.com/esacaris/monitoreo-proin-v2

## Overview

#### Purpose and entry points
This repository is a containerized research-project management system for UNJBG. It manages projects, operational plans, milestones, purchases/services, budgets, documents, inventories, and generated reports. Backend entry point: `backend/app/main.py`; frontend bootstrap and application shell: `frontend/src/main.tsx`, `frontend/src/App.tsx`; composed deployment: `docker-compose.yml`.

#### Client application
The frontend is a React 18/TypeScript single-page application. `frontend/src/context/AuthContext.tsx` owns client authentication state, while `frontend/src/components/Layout.tsx` provides the authenticated application frame. Feature pages map to core backend domains, notably projects (`frontend/src/pages/Proyectos.tsx`, `frontend/src/pages/ProyectoDetalle.tsx`), processing (`frontend/src/pages/DataProcessing.tsx`), and Nextcloud integration (`frontend/src/pages/NextcloudPage.tsx`). Service modules isolate Axios/API calls from UI, e.g. `frontend/src/services/api.ts` and `frontend/src/services/proyectoService.ts`.

#### API and access boundary
FastAPI exposes domain-specific HTTP endpoints under `backend/app/api/endpoints/`. Authentication and authorization begin at `backend/app/api/endpoints/auth.py`, backed by JWT/password mechanisms in `backend/app/core/security.py`. User and role management is exposed through `backend/app/api/endpoints/usuarios.py`; the stated Monitor-versus-Researcher project-access boundary is enforced by API behavior rather than the client alone. Runtime configuration, including environment-supplied infrastructure settings and CORS, is centralized in `backend/app/core/config.py`.

#### Persistence and domain model
SQLAlchemy persistence is initialized through `backend/app/db/session.py` and model registration/base support in `backend/app/db/base.py`. PostgreSQL is the primary database. Models represent the project-centered aggregate and related operational records: `backend/app/models/proyecto.py`, `backend/app/models/actividad.py`, `backend/app/models/hito.py`, `backend/app/models/compra.py`, `backend/app/models/gasto.py`, and `backend/app/models/documento.py`. Pydantic schemas in corresponding `backend/app/schemas/` modules form the API validation/serialization boundary between requests, database entities, and responses.

#### Project execution and administrative workflows
Project operations are separated into endpoint modules: project registration/detail in `backend/app/api/endpoints/proyectos.py`; activities and milestones in `backend/app/api/endpoints/actividades.py` and `backend/app/api/endpoints/hitos.py`; procurement/order tracking in `backend/app/api/endpoints/compras.py` and `backend/app/api/endpoints/ordenes.py`; financial expenditure tracking in `backend/app/api/endpoints/gastos.py`; and laboratory inventory in `backend/app/api/endpoints/inventarios.py`. These workflows are tied by project identifiers and support technical, physical, and financial progress tracking.

#### Ingestion, processing, and reporting
Imported institutional Excel/Word data enters via `backend/app/api/endpoints/importacion.py` and is transformed by `backend/app/services/excel_importer.py` before persistence. Scientific data-processing requests are exposed by `backend/app/api/endpoints/procesamiento.py` and delegated to modality-specific processors: `backend/app/services/data_processors/electrochimica.py`, `backend/app/services/data_processors/uvvis.py`, and `backend/app/services/data_processors/xrd.py`. Reporting endpoints (`backend/app/api/endpoints/informes.py`) invoke `backend/app/services/report_generator.py` to create project/milestone reporting artifacts.

#### File and external-service boundary
Uploads and generated media are filesystem-backed directories mounted for the backend: `backend/uploads/` and `backend/media/`. Document APIs reside in `backend/app/api/endpoints/documentos.py`. Nextcloud is an external document-storage integration, isolated behind `backend/app/services/nextcloud_client.py` and exposed through `backend/app/api/endpoints/nextcloud.py`; this keeps remote file operations outside core persistence logic.

#### Runtime and deployment
The system runs as separate backend and frontend containers defined by `backend/Dockerfile`, `frontend/Dockerfile`, and `docker-compose.yml`; PostgreSQL 15 is the database runtime. The frontend is served through its Nginx configuration (`frontend/nginx.conf`), while the FastAPI service is available independently for API consumers and generated OpenAPI documentation.

Main entry points: [`backend/app/main.py`](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/main.py) (FastAPI application), [`backend/app/db/session.py`](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/db/session.py) (SQLAlchemy persistence), [`docker-compose.yml`](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/docker-compose.yml) (Container composition), [`frontend/src/App.tsx`](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/App.tsx) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client SPA"]
  node_frontend["React application<br/>React/TypeScript SPA<br/>[main.tsx]"]
  node_app_shell["Application shell<br/>React layout<br/>[App.tsx]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.tsx]"]
  node_project_ui["Project workflows<br/>React pages<br/>[Proyectos.tsx]"]
  node_api_client["API services<br/>Axios services<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["FastAPI application<br/>API entry point<br/>[main.py]"]
  node_auth_api["Auth &amp; user access<br/>API endpoints<br/>[auth.py]"]
  node_project_api["Project operations API<br/>API endpoints<br/>[proyectos.py]"]
  node_schema_boundary["Validation schemas<br/>Pydantic schemas"]
end

subgraph group_domain["Domain &amp; workflows"]
  node_import_api["Import API<br/>API endpoint<br/>[importacion.py]"]
  node_excel_importer["Institutional importer<br/>Import service<br/>[excel_importer.py]"]
  node_processing_api["Scientific processing API<br/>API endpoint<br/>[procesamiento.py]"]
  node_processors["Modality processors<br/>Processing services<br/>[electrochimica.py]"]
  node_reporting["Report generation<br/>Reporting service"]
end

subgraph group_runtime["Runtime &amp; integrations"]
  node_persistence["SQLAlchemy persistence<br/>Database session<br/>[session.py]"]
  node_postgres[("PostgreSQL 15<br/>Primary database")]
  node_file_storage["Mounted file storage<br/>Filesystem directories"]
  node_nextcloud["Nextcloud integration<br/>External storage client"]
  node_deployment{{"Container composition<br/>Docker Compose<br/>[docker-compose.yml]"}}
end

node_frontend -->|"boots"| node_app_shell
node_app_shell -->|"uses"| node_auth_context
node_app_shell -->|"renders"| node_project_ui
node_project_ui -->|"calls through"| node_api_client
node_auth_context -->|"supplies token"| node_api_client
node_api_client -->|"HTTP API"| node_fastapi
node_fastapi -->|"routes"| node_auth_api
node_fastapi -->|"routes"| node_project_api
node_fastapi -->|"routes"| node_import_api
node_fastapi -->|"routes"| node_processing_api
node_auth_api -->|"users and roles"| node_persistence
node_project_api -->|"validates"| node_schema_boundary
node_project_api -->|"project records"| node_persistence
node_import_api -->|"delegates"| node_excel_importer
node_excel_importer -->|"persists imports"| node_persistence
node_processing_api -->|"delegates"| node_processors
node_reporting -->|"writes artifacts"| node_file_storage
node_persistence -->|"SQLAlchemy"| node_postgres
node_fastapi -->|"document integration"| node_nextcloud
node_deployment -->|"frontend container"| node_frontend
node_deployment -->|"backend container"| node_fastapi
node_deployment -->|"database service"| node_postgres

click node_frontend "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/main.tsx"
click node_app_shell "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/App.tsx"
click node_auth_context "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/context/AuthContext.tsx"
click node_project_ui "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/pages/Proyectos.tsx"
click node_api_client "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/services/api.ts"
click node_fastapi "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/main.py"
click node_auth_api "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/auth.py"
click node_project_api "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/proyectos.py"
click node_import_api "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/importacion.py"
click node_excel_importer "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/excel_importer.py"
click node_processing_api "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/procesamiento.py"
click node_processors "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/data_processors/electrochimica.py"
click node_reporting "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/report_generator.py"
click node_persistence "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/db/session.py"
click node_nextcloud "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/nextcloud_client.py"
click node_deployment "https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/docker-compose.yml"

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_shell,node_auth_context,node_project_ui,node_api_client toneBlue
class node_fastapi,node_auth_api,node_project_api,node_schema_boundary toneAmber
class node_import_api,node_excel_importer,node_processing_api,node_processors,node_reporting toneMint
class node_persistence,node_postgres,node_file_storage,node_nextcloud,node_deployment toneRose
```

## Components

### Client SPA

- [React application](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/main.tsx): React/TypeScript SPA · Authenticated research-management interface. · `frontend/src/main.tsx`
- [Application shell](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/App.tsx): React layout · `frontend/src/App.tsx`
- [Auth state](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/context/AuthContext.tsx): React context · `frontend/src/context/AuthContext.tsx`
- [Project workflows](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/pages/Proyectos.tsx): React pages · Project detail and operational views. · `frontend/src/pages/Proyectos.tsx`
- [API services](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/frontend/src/services/api.ts): Axios services · `frontend/src/services/api.ts`

### Backend API

- [FastAPI application](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/main.py): API entry point · `backend/app/main.py`
- [Auth & user access](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/auth.py): API endpoints · Enforces JWT authentication, roles, and project access. · `backend/app/api/endpoints/auth.py`
- [Project operations API](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/proyectos.py): API endpoints · Projects, activities, milestones, procurement, expenses, and inventory. · `backend/app/api/endpoints/proyectos.py`
- **Validation schemas**: Pydantic schemas · Request and response boundary for domain entities.

### Domain & workflows

- [Import API](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/importacion.py): API endpoint · `backend/app/api/endpoints/importacion.py`
- [Institutional importer](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/excel_importer.py): Import service · Transforms Excel/Word institutional data before persistence. · `backend/app/services/excel_importer.py`
- [Scientific processing API](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/api/endpoints/procesamiento.py): API endpoint · `backend/app/api/endpoints/procesamiento.py`
- [Modality processors](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/data_processors/electrochimica.py): Processing services · Electrochemistry, UV-Vis, and XRD processing. · `backend/app/services/data_processors/electrochimica.py`
- [Report generation](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/report_generator.py): Reporting service · Creates project and milestone artifacts. · `backend/app/services/report_generator.py`

### Runtime & integrations

- [SQLAlchemy persistence](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/db/session.py): Database session · Session initialization and registered model base. · `backend/app/db/session.py`
- **PostgreSQL 15**: Primary database · Stores project-centered operational records.
- **Mounted file storage**: Filesystem directories · Uploads and generated media.
- [Nextcloud integration](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/backend/app/services/nextcloud_client.py): External storage client · Remote document operations remain outside core persistence. · `backend/app/services/nextcloud_client.py`
- [Container composition](https://github.com/esacaris/monitoreo-proin-v2/blob/claude/gimaecc-research-platform-1u0e1u/docker-compose.yml): Docker Compose · Runs frontend, backend, and PostgreSQL services. · `docker-compose.yml`

## Connections

- React application → Application shell: boots
- Application shell → Auth state: uses
- Application shell → Project workflows: renders
- Project workflows → API services: calls through
- Auth state → API services: supplies token
- API services → FastAPI application: HTTP API
- FastAPI application → Auth & user access: routes
- FastAPI application → Project operations API: routes
- FastAPI application → Import API: routes
- FastAPI application → Scientific processing API: routes
- Auth & user access → SQLAlchemy persistence: users and roles
- Project operations API → Validation schemas: validates
- Project operations API → SQLAlchemy persistence: project records
- Import API → Institutional importer: delegates
- Institutional importer → SQLAlchemy persistence: persists imports
- Scientific processing API → Modality processors: delegates
- Report generation → Mounted file storage: writes artifacts
- SQLAlchemy persistence → PostgreSQL 15: SQLAlchemy
- FastAPI application → Nextcloud integration: document integration
- Container composition → React application: frontend container
- Container composition → FastAPI application: backend container
- Container composition → PostgreSQL 15: database service