# rg727876-hub/consultorio-padre-pio architecture

> Architecture diagram of the GitHub repository rg727876-hub/consultorio-padre-pio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rg727876-hub/consultorio-padre-pio
- Repository: https://github.com/rg727876-hub/consultorio-padre-pio

## Overview

1. **Repository shape**
   - This is a two-tier monorepo: `backend/` is a Node.js/Express REST API, `frontend/` is a React + Vite single-page app, and `database/` contains the MySQL schema and seed data.
   - The main architectural boundary is client-server: the frontend never talks directly to the database; all business actions go through the API.

2. **Backend runtime and entry points**
   - The backend starts from `backend/server.js`, with `src/app.js` configuring the Express app.
   - Cross-cutting setup lives in `src/config/` for MySQL and mail, while environment-driven behavior is expected through `.env`.
   - The backend is the system of record for authentication, authorization, scheduling, payments, auditing, and clinical data.

3. **Backend layering**
   - The backend follows a conventional controller–route–model split:
     - `routes/` defines resource-specific endpoints.
     - `controllers/` implements business use cases.
     - `models/` encapsulate SQL access for each domain entity.
   - This separation matters because business rules are concentrated in controllers, while data persistence stays in model modules.

4. **Security and request pipeline**
   - Requests are filtered through `middlewares/` for authentication, role checks, and centralized error handling.
   - `auth.middleware.js` and `role.middleware.js` enforce JWT-based access control and role boundaries.
   - `utils/jwt.util.js` and `utils/mailer.util.js` support token handling and email workflows, especially activation flows.

5. **Backend domain subsystems**
   - The API is organized around clinical domains: users, patients, doctors, services, schedules, appointments, payments, history, consultations, audit, and activation.
   - Specialized controllers such as `authStaff.controller.js` and `authPatient.controller.js` show that staff and patient authentication are intentionally separated.
   - The admin expansion in the README adds richer user/doctor profile management and status transitions, which are still implemented through the same backend layer.

6. **Scheduling and lifecycle automation**
   - `src/jobs/expireAppointments.js` is a background process that marks stale appointments as expired.
   - This job is part of the business workflow, not just infrastructure: it changes appointment state independently of user requests.
   - Appointment status transitions therefore come from both synchronous API actions and asynchronous scheduled processing.

7. **External integrations**
   - MySQL is the primary persistence layer, defined by `database/schema.sql` and optionally populated by `database/seed.sql`.
   - Email delivery is a first-class integration via the mailer config and utilities, used for account activation and related account lifecycle flows.
   - `src/services/nubefact.service.js` suggests an external billing/invoicing integration for generating comprobantes/fiscal documents.

8. **Frontend application structure**
   - The frontend is a React SPA bootstrapped in `src/main.jsx` and composed in `src/App.jsx`.
   - Routing is handled in `src/routes/AppRouter.jsx` with protected navigation via `PrivateRoute.jsx`.
   - The UI is broken into feature pages rather than technical layers: admin, agenda, auth, caja, doctor, and recepción.

9. **Frontend state and API access**
   - `src/context/AuthContext.jsx` plus `src/hooks/useAuth.js` manage session state and user identity on the client.
   - `src/api/axios.js` centralizes HTTP communication with the backend, so all screens share one API client configuration.
   - This implies the frontend is mostly a thin presentation layer over the REST API, with auth/session concerns kept in context rather than duplicated per page.

10. **Feature-oriented UI boundaries**
   - The frontend mirrors real operational roles:
     - admin pages for users, doctors, services, and schedules
     - reception pages for patient registration, appointment management, and patient detail
     - doctor pages for agenda and clinical history
     - cash desk pages for payments and comprobantes
   - These are not just screens; they map to backend permissions and domain objects, which is important for diagramming role-based boundaries.

11. **Clinical and administrative data model**
   - The database schema centers on entities like `USUARIO`, `ROL`, `DOCTOR`, `PACIENTE`, `CITA`, `HORARIO`, `SERVICIO`, `PAGO`, `COMPROBANTE`, `HISTORIA_CLINICA`, `CONSULTA_CLINICA`, `AUDITORIA`, and `TOKEN_ACTIVACION`.
   - Several many-to-many relationships are explicit, such as doctor-to-service assignment and user-to-role assignment.
   - Appointment and payment are the main transactional aggregates; clinical history and audit are supporting record-keeping subsystems.

12. **Operational flows to capture in a diagram**
   - Account activation: registration → email token → activation endpoint → login.
   - Appointment booking: authenticated actor selects doctor/service/time → creates appointment → later confirmation, cancellation, attendance, or expiration.
   - Payment/comprobante flow: appointment generates or receives payment → payment record → fiscal document issuance.
   - Doctor/profile administration: user/doctor edits and status changes can cascade into appointment cancellations and audit records.

13. **Deployment/tooling boundaries**
   - The frontend has Vite and a `vercel.json`, so it is designed for static SPA deployment.
   - The backend is a standalone Node service, intended to run separately from the frontend and the MySQL database.
   - This architecture is split by runtime, not microservices: one API service, one browser app, one relational database.

14. **What matters most for an architecture diagram**
   - Show three major nodes: browser SPA, Express API, and MySQL.
   - Add side integrations for email and invoicing.
   - Inside the API, group by domain modules: auth, users/doctors/patients, scheduling/appointments, payments/comprobantes, clinical records, and audit/jobs.
   - Emphasize that authorization is role-based and that some state changes are asynchronous through cron jobs, not only direct user actions.

Main entry points: [`backend/server.js`](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/server.js) (Express API), [`backend/src/models/user.model.js`](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/models/user.model.js) (Data models), [`backend/src/controllers/user.controller.js`](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/user.controller.js) (User domain), [`backend/src/controllers/payment.controller.js`](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/payment.controller.js) (Billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_spa(("Browser SPA<br/>react client<br/>[main.jsx]"))
  node_app_router["App router<br/>spa routing<br/>[AppRouter.jsx]"]
  node_auth_state["Auth state<br/>client session<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>http client<br/>[axios.js]"]
end

subgraph group_backend["Backend"]
  node_backend_api(("Express API<br/>node service<br/>[server.js]"))
  node_app_setup["App setup<br/>express bootstrap<br/>[app.js]"]
  node_auth_layer["Auth layer<br/>security<br/>[auth.middleware.js]"]
  node_user_domain["User domain<br/>people mgmt<br/>[user.controller.js]"]
  node_scheduling_domain["Scheduling<br/>appointments"]
  node_billing_domain["Billing<br/>payments"]
  node_clinical_domain["Clinical records<br/>medical record"]
  node_audit_jobs["Audit jobs<br/>background process"]
  node_db_access["Data models<br/>sql persistence<br/>[user.model.js]"]
end

subgraph group_database["Database"]
  node_mysql_db[("MySQL DB<br/>relational database<br/>[schema.sql]")]
end

subgraph group_integrations["External integrations"]
  node_mailer_service["Mailer<br/>email service<br/>[mailer.js]"]
  node_invoicing_service["Invoicing<br/>billing integration"]
end

node_browser_spa -->|"navigates"| node_app_router
node_app_router -->|"uses session"| node_auth_state
node_browser_spa -->|"calls API"| node_api_client
node_api_client -->|"requests"| node_backend_api
node_backend_api -->|"bootstraps"| node_app_setup
node_app_setup -->|"applies"| node_auth_layer
node_backend_api -->|"serves"| node_user_domain
node_backend_api -->|"serves"| node_scheduling_domain
node_backend_api -->|"serves"| node_billing_domain
node_backend_api -->|"serves"| node_clinical_domain
node_backend_api -->|"runs"| node_audit_jobs
node_user_domain -->|"persists via"| node_db_access
node_scheduling_domain -->|"persists via"| node_db_access
node_billing_domain -->|"persists via"| node_db_access
node_clinical_domain -->|"persists via"| node_db_access
node_db_access -->|"reads/writes"| node_mysql_db
node_user_domain -->|"sends mail"| node_mailer_service
node_billing_domain -->|"issues documents"| node_invoicing_service
node_audit_jobs -.->|"expires appointments"| node_scheduling_domain
node_auth_layer -.->|"protects"| node_user_domain

click node_browser_spa "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/main.jsx"
click node_app_router "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/routes/AppRouter.jsx"
click node_auth_state "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/context/AuthContext.jsx"
click node_api_client "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/api/axios.js"
click node_backend_api "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/server.js"
click node_app_setup "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/app.js"
click node_auth_layer "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/middlewares/auth.middleware.js"
click node_user_domain "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/user.controller.js"
click node_scheduling_domain "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/appointment.controller.js"
click node_billing_domain "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/payment.controller.js"
click node_clinical_domain "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/consulta.controller.js"
click node_audit_jobs "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/jobs/expireAppointments.js"
click node_db_access "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/models/user.model.js"
click node_mysql_db "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/database/schema.sql"
click node_mailer_service "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/config/mailer.js"
click node_invoicing_service "https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/services/nubefact.service.js"

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_browser_spa,node_app_router,node_auth_state,node_api_client toneBlue
class node_backend_api,node_app_setup,node_auth_layer,node_user_domain,node_scheduling_domain,node_billing_domain,node_clinical_domain,node_audit_jobs,node_db_access toneAmber
class node_mysql_db toneMint
class node_mailer_service,node_invoicing_service toneRose
```

## Components

### Frontend

React + Vite single-page application

- [Browser SPA](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/main.jsx): react client · Role-based UI for admin, reception, doctor, and cash desk users · `frontend/src/main.jsx`
- [App router](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/routes/AppRouter.jsx): spa routing · Top-level navigation and protected routes · `frontend/src/routes/AppRouter.jsx`
- [Auth state](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/context/AuthContext.jsx): client session · Session and identity state shared across the SPA · `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/frontend/src/api/axios.js): http client · Centralized Axios configuration for backend calls · `frontend/src/api/axios.js`

### Backend

Node.js/Express API and background jobs

- [Express API](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/server.js): node service · Server-side system of record for business workflows · `backend/server.js`
- [App setup](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/app.js): express bootstrap · Express app configuration and middleware wiring · `backend/src/app.js`
- [Auth layer](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/middlewares/auth.middleware.js): security · JWT auth, role checks, activation, and login flows · `backend/src/middlewares/auth.middleware.js`
- [User domain](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/user.controller.js): people mgmt · Users, doctors, patients, and account activation · `backend/src/controllers/user.controller.js`
- [Scheduling](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/appointment.controller.js): appointments · Schedules, agenda, and appointment lifecycle · `backend/src/controllers/appointment.controller.js`
- [Billing](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/payment.controller.js): payments · Payments and fiscal document issuance · `backend/src/controllers/payment.controller.js`
- [Clinical records](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/controllers/consulta.controller.js): medical record · Consultations and patient history · `backend/src/controllers/consulta.controller.js`
- [Audit jobs](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/jobs/expireAppointments.js): background process · Audit logging and automatic expiration of stale appointments · `backend/src/jobs/expireAppointments.js`
- [Data models](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/models/user.model.js): sql persistence · Repository models for SQL access to core entities · `backend/src/models/user.model.js`

### Database

MySQL schema and seed data

- [MySQL DB](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/database/schema.sql): relational database · Schema and seeded relational data for the clinic system · `database/schema.sql`

### External integrations

Email and invoicing services

- [Mailer](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/config/mailer.js): email service · Activation and account lifecycle email delivery · `backend/src/config/mailer.js`
- [Invoicing](https://github.com/rg727876-hub/consultorio-padre-pio/blob/main/backend/src/services/nubefact.service.js): billing integration · External fiscal document generation via Nubefact · `backend/src/services/nubefact.service.js`

## Connections

- Browser SPA → App router: navigates · SPA rendering is organized through top-level routing
- App router → Auth state: uses session · Protected routes depend on client authentication state
- Browser SPA → API client: calls API · All screens use the shared HTTP client
- API client → Express API: requests · Browser traffic goes to the standalone API service
- Express API → App setup: bootstraps · Server entry loads the Express app configuration
- App setup → Auth layer: applies · Request pipeline enforces authentication and role boundaries
- Express API → User domain: serves · Authentication, user, doctor, patient, and activation flows
- Express API → Scheduling: serves · Appointments, schedules, and agenda management
- Express API → Billing: serves · Payment capture and comprobante generation
- Express API → Clinical records: serves · Clinical consultations and history records
- Express API → Audit jobs: runs · Background expiration and audit-related processing
- User domain → Data models: persists via · Controllers delegate SQL work to models
- Scheduling → Data models: persists via · Appointment and schedule state is stored through models
- Billing → Data models: persists via · Payment and comprobante records are stored through models
- Clinical records → Data models: persists via · Clinical record operations use the model layer
- Data models → MySQL DB: reads/writes · Models map application entities to relational tables
- User domain → Mailer: sends mail · Activation and lifecycle emails use the mailer integration
- Billing → Invoicing: issues documents · Comprobante generation can call the invoicing integration
- Audit jobs → Scheduling: expires appointments · Scheduled job changes appointment status asynchronously
- Auth layer → User domain: protects · JWT and role checks gate administrative and clinical actions