How rickneser2023/sistema-clinico works
1. Overall shape
- This is a single Next.js monolith using the App Router. There is no separate frontend and backend service in the repo; UI, server actions, and a few API routes live together in one codebase.
2. Primary runtime stack
- The app runs on Next.js + React with Prisma as the ORM and PostgreSQL as the database.
- The repo is containerized with Docker / Docker Compose, so the app and database are intended to run together as the main deployment unit.
3. Top-level user experience
- The app is a clinical management system centered on patient records, histories, agenda, attention flow, billing, reports, and administration.
- The main navigation appears to be the app shell with routes like /, /pacientes, /nueva-historia, /agenda, /atencion, /facturacion, /medicos, /ejecutivo/reportes, and /configuracion.
4. Presentation shell
- app/layout.tsx and shared components like DashboardLayout, Header, Sidebar, ThemeProvider, AuthProvider, and ToastProvider define the global shell and cross-cutting UI context.
- This is a UI-heavy app with a persistent shell and page-level content rendered inside it.
5. Core domain modules
- The repo is organized by clinical workflow:
- Pacientes: list, search, and patient detail/history.
- Nueva historia: medical intake and consultation form.
- Agenda: scheduling/calendar views.
- Atención: operational handling of active cases, including a Kanban-style board.
- Facturación: payment/comprobante flow.
- Médicos / Ejecutivo / Reportes / Configuración: operational, management, and admin views.
- These are exposed as route folders under app/, which makes them diagram-friendly as separate bounded areas inside one app.
6. Business logic boundary
- The app/actions/* folder is the main server-side business logic layer, grouped by domain: agenda, auth, dashboard, facturacion, historia, infraestructura, notificaciones, pacientes, reportes, and usuarios.
- This suggests the app relies heavily on server actions rather than a separate backend service, with domain logic centralized outside the page components.
7. Persistence layer
- lib/prisma.ts provides the Prisma client, and prisma/schema.prisma plus the migration history define the database model.
- The schema and migrations show the app has evolved to support users/permissions, clinical records, appointments, advances/balances, and stored comprobantes.
- prisma/seed.ts indicates there is seeded data for initial/demo use.
8. Data flow through the app
- Typical flow is: page/component interaction → server action or API route → Prisma → PostgreSQL → UI re-render / updated state.
- Some views are interactive client components, such as HistoriaForm, PatientTabsClient, KanbanAtencion, and MedicosManager, which means the app mixes server-rendered pages with client-side interaction where needed.
9. API surface
- The app/api folder is small and specific, with endpoints for users and comprobante/[id].
- These look like targeted HTTP boundaries for data retrieval or compatibility, while most domain operations likely remain in server actions.
10. Reusable UI and feature widgets
- components/ contains reusable clinical UI elements: charts, cards, forms, preview widgets, notifications, and layout controls.
- Notable domain widgets include ClinicalCharts, AgendaCalendario, CobrarForm, ComprobantePreview, ValidarAdelantoBtn, and report filters/tables, which support multiple pages rather than a single screen.
11. Validation and security helpers
- lib/validations/* contains domain-specific validation rules for citas, historia, and pacientes.
- lib/password.ts and the presence of auth-related actions/routes indicate credential handling and access control are part of the architecture, not just demo UI.
12. Demo/mock data and presentation layer
- lib/mockData.ts shows the app can render realistic clinical scenarios without depending entirely on live data, which matches the README’s focus on demo/presentation use.
- The UI styling is driven by app/globals.css, implying a custom, design-centric presentation layer rather than a component library.
13. Operational boundaries for a diagram
- A good architecture diagram would show one Next.js application boundary containing:
- page routes,
- shared UI shell/components,
- server actions,
- validation/helpers,
- Prisma data access,
- and the PostgreSQL database.
- External dependencies are limited and materially important: Docker for local orchestration and PostgreSQL for persistent storage.
14. Key takeaway
- This repo is best understood as a modular clinical management platform inside one Next.js app, with strong separation between presentation, server actions/business logic, and database persistence, but without a standalone backend service.
Main entry points: prisma.ts Prisma client · ClinicalCharts.tsx Clinical widgets · pacientes.ts Pacientes actions · facturacion.ts Facturación actions
Components 28
Presentation
App Router pages, global shell, and interactive feature components.
- App shell · Global Next.js layout and providers for the whole app.
app/layout.tsx - Home · Main landing route for the clinical dashboard.
app/page.tsx - Login · Authentication entry screen.
app/login/page.tsx - Shell UI · Persistent dashboard layout, header, sidebar, theme, auth, and toast providers.
components/DashboardLayout.tsx
Domain UI
Clinical workflow screens and specialized widgets.
- Pacientes · Patient list and patient detail/historical views.
app/pacientes/page.tsx - Nueva historia · Clinical intake and consultation form.
app/nueva-historia/page.tsx - Agenda · Scheduling and calendar workflow.
app/agenda/page.tsx - Atención · Active case handling and operational board.
app/atencion/page.tsx - Facturación · Billing and payment flow.
app/facturacion/page.tsx - Médicos · Physician management screen.
app/medicos/page.tsx - Reportes · Executive reporting views.
app/ejecutivo/reportes/page.tsx - Configuración · Administration and configuration view.
app/configuracion/page.tsx - Clinical widgets · Reusable clinical and billing UI including charts, forms, preview, and notifications.
components/ClinicalCharts.tsx - Report widgets · Report filters and tabular preview widgets.
components/reportes/FiltrosReporte.tsx
Server Logic
Server actions and HTTP endpoints that coordinate business workflows.
- Dashboard · Server-side dashboard aggregation and summary logic.
app/actions/dashboard.ts - Pacientes actions · Server actions for patient search, detail, and persistence.
app/actions/pacientes.ts - Historia actions · Server actions for intake and consultation workflows.
app/actions/historia.ts - Agenda actions · Scheduling and appointment server actions.
app/actions/agenda.ts - Facturación actions · Billing, receipts, and payment server actions.
app/actions/facturacion.ts - Auth actions · Login and access-control server actions.
app/actions/auth.ts - Reportes actions · Reporting and aggregation server actions.
app/actions/reportes.ts - API routes · Targeted HTTP endpoints for users and comprobantes.
app/api/users/route.ts - Validations · Domain validation rules for citas, historia, and pacientes.
lib/validations/pacientes.ts
Persistence
Prisma client, schema, migrations, and seeded data.
- Prisma client · Shared Prisma connection and ORM entry point.
lib/prisma.ts - Schema · Prisma schema and migration history for the clinical model.
prisma/schema.prisma - PostgreSQL · Primary persistent datastore for the application.
- Seed data · Initial/demo data loader for the database.
prisma/seed.ts
Operations
Containerized runtime and deployment orchestration.
- Docker Compose · Container orchestration for the app and database.
docker-compose.yml
Connections 29
- App shell → Shell UI: wraps · The global layout composes the persistent shell and providers.
- Home → Dashboard: loads · Home/dashboard route retrieves summary data from server actions.
- Login → Auth actions: authenticates · Login screen submits credentials to auth logic.
- Pacientes → Pacientes actions: uses · Patient routes rely on patient server actions.
- Pacientes → Clinical widgets: renders · Patient views use reusable clinical UI widgets.
- Nueva historia → Historia actions: submits · Clinical intake form is backed by historia server actions.
- Nueva historia → Validations: validates · The intake workflow uses domain validation rules.
- Agenda → Agenda actions: coordinates · Scheduling screen is driven by agenda server actions.
- Agenda → Clinical widgets: renders · Agenda uses calendar and shared UI components.
- Atención → Clinical widgets: renders · Operational board is implemented with interactive clinical widgets.
- Facturación → Facturación actions: processes · Billing screen delegates payment and comprobante logic to actions.
- Facturación → Clinical widgets: renders · Billing screen uses forms, previews, and payment controls.
- Médicos → Clinical widgets: renders · Physician management uses shared interactive components.
- Reportes → Reportes actions: aggregates · Reporting route pulls summarized data from reporting actions.
- Reportes → Report widgets: renders · Reports page uses filters and preview tables.
- Configuración → Auth actions: administers · Configuration touches access and account-related server logic.
- API routes → Facturación actions: serves · Comprobante endpoint exposes billing data over HTTP.
- API routes → Pacientes actions: serves · Users API boundary supports app data access patterns.
- Pacientes actions → Prisma client: queries · Patient server actions access the ORM client.
- Historia actions → Prisma client: writes · Clinical workflow actions persist through Prisma.
- Agenda actions → Prisma client: queries · Scheduling actions read and write through Prisma.
- Facturación actions → Prisma client: writes · Billing actions store payment and comprobante data.
- Auth actions → Prisma client: reads · Authentication logic queries user and permission data.
- Reportes actions → Prisma client: reads · Reporting actions aggregate persisted clinical and operational data.
- Prisma client → Schema: uses · The client is generated from the Prisma schema.
- Schema → PostgreSQL: persists to · Schema models map onto the PostgreSQL datastore.
- Seed data → PostgreSQL: initializes · Seed script populates the database with starter data.
- Docker Compose → PostgreSQL: orchestrates · Docker Compose runs the database alongside the app.
- Docker Compose → App shell: orchestrates · Container setup includes the Next.js application runtime.