# adelcelevator/tarjetas_refrigerio architecture

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

- Interactive diagram: https://gitdiagram.com/adelcelevator/tarjetas_refrigerio
- Repository: https://github.com/adelcelevator/tarjetas_refrigerio

## Overview

1. **What this service is**
   - `Tarjetas Refrigerio` is a Rust backend for managing prepaid “tarjetas” and cafeteria/refrigerio payments for a group.
   - The system is centered on backend APIs plus database-driven processing; there is no frontend in this repo.

2. **Primary runtime boundary**
   - The executable entrypoint is `src/main.rs`.
   - The backend is built with **Actix** for HTTP/REST handling, so the main runtime flow is: request in → middleware → controller → service → repository → database.

3. **HTTP/API layer**
   - `src/controllers/` contains the REST endpoints, separated by domain:
     - `token`, `user`, `tarjeta`, `pagos`, `cobros`, `parametro`, `comprobante`.
   - These controllers are the first application boundary after middleware and are responsible for translating HTTP requests/responses into domain operations.

4. **Cross-cutting middleware**
   - `src/middlewares/` contains:
     - `auth_middleware.rs` for session/JWT validation.
     - `logging_middleware.rs` for tracing/log correlation.
   - These apply before the controller logic, so authentication and observability are enforced consistently at the request edge.

5. **Business logic layer**
   - `src/services/` holds the domain workflows:
     - `token`, `usuario`, `tarjeta`, `pagos`, `cobros`, `comprobante`, `parametro`.
   - Services are where orchestration happens: validation, coordination between repositories, and business rules that span multiple persistence entities.

6. **Persistence split: PostgreSQL vs MongoDB**
   - The repo uses two databases with different responsibilities:
     - **PostgreSQL** is the main transactional store for users, cards, payments, receipts, parameters, roles, people, histories, etc.
     - **MongoDB** is used for session/token storage.
   - This split is explicit in the folder structure: `src/repository/postgres/` versus `src/repository/mongo/`, and `src/datasources/` also mirrors that separation.

7. **Repository layer**
   - `src/repository/postgres/` contains one repository per domain entity or query area, such as:
     - `tarjeta_repository`, `pago_repository`, `comprobante_repository`, `usuario_repository`, `roles_repository`, `parametro_repository`.
   - `src/repository/mongo/token_repo.rs` handles token/session persistence.
   - Repositories are the data-access boundary; they hide Diesel/DB details from services.

8. **Model structure**
   - `src/models/data_model/postgres/` contains the PostgreSQL entity models, such as:
     - `tarjeta`, `pago`, `comprobante`, `persona`, `usuario`, `rol`, `tipo_pago`, `unidades`, `tarjeta_historial`.
   - `src/models/data_model/mongo/token_model.rs` represents session/token data in MongoDB.
   - `src/models/responses/` contains API response DTOs like login and payment-type/unit responses.

9. **Authentication and session flow**
   - Authentication appears to be JWT-based, with token/session lifecycle managed through:
     - `src/services/token_service.rs`
     - `src/repository/mongo/token_repo.rs`
     - `src/middlewares/auth_middleware.rs`
   - The request path is likely: login/token creation → token stored/validated in MongoDB → middleware checks token on subsequent requests.

10. **Database-facing utility layer**
   - `src/utils/` contains support code for:
     - database connections and helpers (`connection_utils`, `bd_utils`)
     - encryption (`cifrador_utils`)
     - token handling (`token_utils`, `token_user`)
     - environment/config loading (`env_utils`)
     - logging setup (`loging_utils`)
     - shared enums for roles, states, and service errors.
   - This layer supports both request processing and persistence setup.

11. **PostgreSQL-side processing**
   - The README states that PostgreSQL also contains:
     - jobs for authorized-comprobante processing and card generation
     - triggers for validation and internal state updates
     - indexes for search performance
   - That means some business processing is intentionally pushed into the database, not only into Rust services.

12. **Operational packaging**
   - The presence of `Dockerfile`, `docker-compose.yml`, and `.env.dist` indicates containerized deployment with environment-driven configuration.
   - `log4rs.yml` configures application logging, and `open_api_spec.yaml` documents the REST surface.

13. **How to draw the architecture**
   - A good diagram would show:
     - clients calling the Actix REST API
     - middleware for auth/logging
     - controllers and services in the application layer
     - repositories and datasources as the persistence boundary
     - PostgreSQL as the main transactional backend
     - MongoDB as the session/token store
     - database-side jobs/triggers as an additional processing boundary inside PostgreSQL.

Main entry points: [`src/controllers/mod.rs`](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/mod.rs) (Controllers), [`src/middlewares/mod.rs`](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/mod.rs) (Middleware), [`src/services/mod.rs`](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/mod.rs) (Services), [`src/services/token_service.rs`](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/token_service.rs) (Token service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Main<br/>Actix entrypoint<br/>[main.rs]"]
  node_middleware{{"Middleware<br/>request edge<br/>[mod.rs]"}}
  node_auth_mw["Auth check<br/>auth middleware<br/>[auth_middleware.rs]"]
  node_log_mw["Request log<br/>logging middleware"]
  node_controllers{{"Controllers<br/>REST API<br/>[mod.rs]"}}
  node_token_ctrl["Token API<br/>auth controller"]
  node_user_ctrl["User API<br/>user controller<br/>[user_controller.rs]"]
  node_tarjeta_ctrl["Tarjeta API<br/>card controller"]
  node_payments_ctrl["Payments API<br/>payments controller"]
  node_services{{"Services<br/>business logic<br/>[mod.rs]"}}
  node_token_svc["Token service<br/>auth workflow<br/>[token_service.rs]"]
  node_tarjeta_svc["Tarjeta service<br/>card workflow<br/>[tarjeta_service.rs]"]
  node_pago_svc["Pago service<br/>payment workflow<br/>[pagos_service.rs]"]
end

subgraph group_data["Data layer"]
  node_repos_pg[("Postgres repos<br/>postgres data access<br/>[mod.rs]")]
  node_tarjeta_repo["Tarjeta repo<br/>postgres repository"]
  node_pago_repo["Pago repo<br/>postgres repository<br/>[pago_repository.rs]"]
  node_usuario_repo["Usuario repo<br/>postgres repository"]
  node_token_repo["Token repo<br/>mongo repository<br/>[token_repo.rs]"]
end

subgraph group_infra["Infrastructure"]
  node_db_postgres[("PostgreSQL<br/>transactional DB")]
  node_db_mongo[("MongoDB<br/>session store")]
  node_db_jobs{{"DB jobs<br/>postgres processing"}}
  node_datasources["Datasources<br/>db wiring<br/>[mod.rs]"]
end

node_main -->|"wires"| node_middleware
node_main -->|"registers"| node_controllers
node_middleware -->|"includes"| node_auth_mw
node_middleware -->|"includes"| node_log_mw
node_middleware -->|"guards"| node_controllers
node_controllers -->|"routes"| node_token_ctrl
node_controllers -->|"routes"| node_user_ctrl
node_controllers -->|"routes"| node_tarjeta_ctrl
node_controllers -->|"routes"| node_payments_ctrl
node_controllers -->|"delegates"| node_services
node_services -->|"contains"| node_token_svc
node_services -->|"contains"| node_tarjeta_svc
node_services -->|"contains"| node_pago_svc
node_token_svc -->|"uses"| node_token_repo
node_token_svc -->|"stores"| node_db_mongo
node_tarjeta_svc -->|"uses"| node_tarjeta_repo
node_tarjeta_svc -->|"queries"| node_repos_pg
node_pago_svc -->|"uses"| node_pago_repo
node_pago_svc -->|"coordinates"| node_repos_pg
node_repos_pg -->|"reads/writes"| node_db_postgres
node_token_repo -->|"reads/writes"| node_db_mongo
node_datasources -->|"connects"| node_db_postgres
node_datasources -->|"connects"| node_db_mongo
node_db_postgres -->|"executes"| node_db_jobs
node_controllers -.->|"auth flow"| node_token_svc
node_auth_mw -.->|"validates"| node_token_repo

click node_main "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/main.rs"
click node_middleware "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/mod.rs"
click node_auth_mw "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/auth_middleware.rs"
click node_log_mw "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/logging_middleware.rs"
click node_controllers "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/mod.rs"
click node_token_ctrl "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/token_controller.rs"
click node_user_ctrl "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/user_controller.rs"
click node_tarjeta_ctrl "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/tarjeta_controller.rs"
click node_payments_ctrl "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/pagos_controller.rs"
click node_services "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/mod.rs"
click node_token_svc "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/token_service.rs"
click node_tarjeta_svc "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/tarjeta_service.rs"
click node_pago_svc "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/pagos_service.rs"
click node_repos_pg "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/mod.rs"
click node_tarjeta_repo "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/tarjeta_repository.rs"
click node_pago_repo "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/pago_repository.rs"
click node_usuario_repo "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/usuario_repository.rs"
click node_token_repo "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/mongo/token_repo.rs"
click node_datasources "https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/datasources/mod.rs"

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_main,node_middleware,node_auth_mw,node_log_mw,node_controllers,node_token_ctrl,node_user_ctrl,node_tarjeta_ctrl,node_payments_ctrl,node_services,node_token_svc,node_tarjeta_svc,node_pago_svc toneBlue
class node_repos_pg,node_tarjeta_repo,node_pago_repo,node_usuario_repo,node_token_repo toneAmber
class node_db_postgres,node_db_mongo,node_db_jobs,node_datasources toneMint
```

## Components

### Application

Actix runtime, HTTP boundary, middleware, and business services.

- [Main](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/main.rs): Actix entrypoint · Bootstraps the HTTP server and wires the application stack. · `src/main.rs`
- [Middleware](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/mod.rs): request edge · Cross-cutting request interception for auth and logging. · `src/middlewares/mod.rs`
- [Auth check](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/auth_middleware.rs): auth middleware · Validates session or JWT credentials before controllers run. · `src/middlewares/auth_middleware.rs`
- [Request log](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/middlewares/logging_middleware.rs): logging middleware · Adds tracing and log correlation around incoming requests. · `src/middlewares/logging_middleware.rs`
- [Controllers](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/mod.rs): REST API · HTTP endpoints grouped by domain and request/response translation. · `src/controllers/mod.rs`
- [Token API](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/token_controller.rs): auth controller · Handles login and token/session operations. · `src/controllers/token_controller.rs`
- [User API](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/user_controller.rs): user controller · Exposes user-related HTTP operations. · `src/controllers/user_controller.rs`
- [Tarjeta API](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/tarjeta_controller.rs): card controller · Manages prepaid card endpoints and related flows. · `src/controllers/tarjeta_controller.rs`
- [Payments API](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/controllers/pagos_controller.rs): payments controller · Handles pago and cobro endpoints. · `src/controllers/pagos_controller.rs`
- [Services](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/mod.rs): business logic · Domain orchestration, validation, and workflow coordination. · `src/services/mod.rs`
- [Token service](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/token_service.rs): auth workflow · Creates and validates token/session lifecycle. · `src/services/token_service.rs`
- [Tarjeta service](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/tarjeta_service.rs): card workflow · Coordinates card-related business rules. · `src/services/tarjeta_service.rs`
- [Pago service](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/services/pagos_service.rs): payment workflow · Orchestrates payment and charge processing. · `src/services/pagos_service.rs`

### Data layer

Repositories, datasources, and model structures.

- [Postgres repos](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/mod.rs): postgres data access · Repository boundary for transactional PostgreSQL data. · `src/repository/postgres/mod.rs`
- [Tarjeta repo](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/tarjeta_repository.rs): postgres repository · Persists cards and card history. · `src/repository/postgres/tarjeta_repository.rs`
- [Pago repo](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/pago_repository.rs): postgres repository · Persists payments and payment details. · `src/repository/postgres/pago_repository.rs`
- [Usuario repo](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/postgres/usuario_repository.rs): postgres repository · Data access for users, roles, and people. · `src/repository/postgres/usuario_repository.rs`
- [Token repo](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/repository/mongo/token_repo.rs): mongo repository · Stores and retrieves session or token records. · `src/repository/mongo/token_repo.rs`

### Infrastructure

Deployment, configuration, and database-side processing.

- **PostgreSQL**: transactional DB · Main relational store for cards, users, payments, receipts, and parameters.
- **MongoDB**: session store · Document store used for token/session persistence.
- **DB jobs**: postgres processing · Database-side jobs, triggers, and indexes for validation and state updates.
- [Datasources](https://github.com/adelcelevator/tarjetas_refrigerio/blob/master/src/datasources/mod.rs): db wiring · Connection helpers and database access setup. · `src/datasources/mod.rs`

## Connections

- Main → Middleware: wires · Application startup installs request middleware.
- Main → Controllers: registers · Main server exposes the REST controllers.
- Middleware → Auth check: includes · Authentication middleware is part of the request edge.
- Middleware → Request log: includes · Logging middleware is part of the request edge.
- Middleware → Controllers: guards · Requests pass through middleware before controller logic.
- Controllers → Token API: routes · Token-related HTTP endpoints.
- Controllers → User API: routes · User-related HTTP endpoints.
- Controllers → Tarjeta API: routes · Card-related HTTP endpoints.
- Controllers → Payments API: routes · Payment and charge endpoints.
- Controllers → Services: delegates · Controllers translate HTTP input into service calls.
- Services → Token service: contains · Auth and session workflow.
- Services → Tarjeta service: contains · Card workflow orchestration.
- Services → Pago service: contains · Payment workflow orchestration.
- Token service → Token repo: uses · Token lifecycle is persisted in MongoDB.
- Token service → MongoDB: stores · Token/session records live in MongoDB.
- Tarjeta service → Tarjeta repo: uses · Card workflows persist through the card repository.
- Tarjeta service → Postgres repos: queries · Business rules coordinate PostgreSQL repositories.
- Pago service → Pago repo: uses · Payment workflows persist through the payment repository.
- Pago service → Postgres repos: coordinates · Payment flows may span multiple PostgreSQL repositories.
- Postgres repos → PostgreSQL: reads/writes · PostgreSQL repositories access the main relational store.
- Token repo → MongoDB: reads/writes · Mongo token repository accesses the session store.
- Datasources → PostgreSQL: connects · Connection layer wires PostgreSQL access.
- Datasources → MongoDB: connects · Connection layer wires MongoDB access.
- PostgreSQL → DB jobs: executes · Database-side jobs and triggers run inside PostgreSQL.
- Controllers → Token service: auth flow · Login and token endpoints drive the authentication flow.
- Auth check → Token repo: validates · Middleware checks token state during protected requests.
