How adelcelevator/tarjetas_refrigerio works
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: controllers/mod.rs Controllers · middlewares/mod.rs Middleware · services/mod.rs Services · token_service.rs Token service
Components 22
Application
Actix runtime, HTTP boundary, middleware, and business services.
- Main · Bootstraps the HTTP server and wires the application stack.
src/main.rs - Middleware · Cross-cutting request interception for auth and logging.
src/middlewares/mod.rs - Auth check · Validates session or JWT credentials before controllers run.
src/middlewares/auth_middleware.rs - Request log · Adds tracing and log correlation around incoming requests.
src/middlewares/logging_middleware.rs - Controllers · HTTP endpoints grouped by domain and request/response translation.
src/controllers/mod.rs - Token API · Handles login and token/session operations.
src/controllers/token_controller.rs - User API · Exposes user-related HTTP operations.
src/controllers/user_controller.rs - Tarjeta API · Manages prepaid card endpoints and related flows.
src/controllers/tarjeta_controller.rs - Payments API · Handles pago and cobro endpoints.
src/controllers/pagos_controller.rs - Services · Domain orchestration, validation, and workflow coordination.
src/services/mod.rs - Token service · Creates and validates token/session lifecycle.
src/services/token_service.rs - Tarjeta service · Coordinates card-related business rules.
src/services/tarjeta_service.rs - Pago service · Orchestrates payment and charge processing.
src/services/pagos_service.rs
Data layer
Repositories, datasources, and model structures.
- Postgres repos · Repository boundary for transactional PostgreSQL data.
src/repository/postgres/mod.rs - Tarjeta repo · Persists cards and card history.
src/repository/postgres/tarjeta_repository.rs - Pago repo · Persists payments and payment details.
src/repository/postgres/pago_repository.rs - Usuario repo · Data access for users, roles, and people.
src/repository/postgres/usuario_repository.rs - Token repo · Stores and retrieves session or token records.
src/repository/mongo/token_repo.rs
Infrastructure
Deployment, configuration, and database-side processing.
- PostgreSQL · Main relational store for cards, users, payments, receipts, and parameters.
- MongoDB · Document store used for token/session persistence.
- DB jobs · Database-side jobs, triggers, and indexes for validation and state updates.
- Datasources · Connection helpers and database access setup.
src/datasources/mod.rs
Connections 26
- 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.