How rg727876-hub/consultorio-padre-pio works
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: server.js Express API · user.model.js Data models · user.controller.js User domain · payment.controller.js Billing
Components 16
Frontend
React + Vite single-page application
- Browser SPA · Role-based UI for admin, reception, doctor, and cash desk users
frontend/src/main.jsx - App router · Top-level navigation and protected routes
frontend/src/routes/AppRouter.jsx - Auth state · Session and identity state shared across the SPA
frontend/src/context/AuthContext.jsx - API client · Centralized Axios configuration for backend calls
frontend/src/api/axios.js
Backend
Node.js/Express API and background jobs
- Express API · Server-side system of record for business workflows
backend/server.js - App setup · Express app configuration and middleware wiring
backend/src/app.js - Auth layer · JWT auth, role checks, activation, and login flows
backend/src/middlewares/auth.middleware.js - User domain · Users, doctors, patients, and account activation
backend/src/controllers/user.controller.js - Scheduling · Schedules, agenda, and appointment lifecycle
backend/src/controllers/appointment.controller.js - Billing · Payments and fiscal document issuance
backend/src/controllers/payment.controller.js - Clinical records · Consultations and patient history
backend/src/controllers/consulta.controller.js - Audit jobs · Audit logging and automatic expiration of stale appointments
backend/src/jobs/expireAppointments.js - Data models · Repository models for SQL access to core entities
backend/src/models/user.model.js
Database
MySQL schema and seed data
- MySQL DB · Schema and seeded relational data for the clinic system
database/schema.sql
Connections 20
- 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