# rickneser2023/sistema-clinico architecture

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

- Interactive diagram: https://gitdiagram.com/rickneser2023/sistema-clinico
- Repository: https://github.com/rickneser2023/sistema-clinico

## Overview

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: [`lib/prisma.ts`](https://github.com/rickneser2023/sistema-clinico/blob/main/lib/prisma.ts) (Prisma client), [`components/ClinicalCharts.tsx`](https://github.com/rickneser2023/sistema-clinico/blob/main/components/ClinicalCharts.tsx) (Clinical widgets), [`app/actions/pacientes.ts`](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/pacientes.ts) (Pacientes actions), [`app/actions/facturacion.ts`](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/facturacion.ts) (Facturación actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_layout["App shell<br/>layout<br/>[layout.tsx]"]
  node_home_page["Home<br/>route<br/>[page.tsx]"]
  node_login_page["Login<br/>route<br/>[page.tsx]"]
  node_ui_shell["Shell UI<br/>component set"]
end

subgraph group_domain["Domain UI"]
  node_pacientes_area["Pacientes<br/>route area<br/>[page.tsx]"]
  node_historia_page["Nueva historia<br/>route<br/>[page.tsx]"]
  node_agenda_page["Agenda<br/>route<br/>[page.tsx]"]
  node_atencion_page["Atención<br/>route<br/>[page.tsx]"]
  node_facturacion_page["Facturación<br/>route<br/>[page.tsx]"]
  node_medicos_page["Médicos<br/>route<br/>[page.tsx]"]
  node_reportes_page["Reportes<br/>route<br/>[page.tsx]"]
  node_config_page["Configuración<br/>route<br/>[page.tsx]"]
  node_clinical_widgets["Clinical widgets<br/>component set<br/>[ClinicalCharts.tsx]"]
  node_report_widgets["Report widgets<br/>component set<br/>[FiltrosReporte.tsx]"]
end

subgraph group_logic["Server Logic"]
  node_dashboard_actions["Dashboard<br/>action domain<br/>[dashboard.ts]"]
  node_pacientes_actions["Pacientes actions<br/>action domain<br/>[pacientes.ts]"]
  node_historia_actions["Historia actions<br/>action domain<br/>[historia.ts]"]
  node_agenda_actions["Agenda actions<br/>action domain<br/>[agenda.ts]"]
  node_facturacion_actions["Facturación actions<br/>action domain<br/>[facturacion.ts]"]
  node_auth_actions["Auth actions<br/>action domain<br/>[auth.ts]"]
  node_reportes_actions["Reportes actions<br/>action domain<br/>[reportes.ts]"]
  node_api_routes["API routes<br/>http boundary<br/>[route.ts]"]
  node_validation["Validations<br/>rules<br/>[pacientes.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_client["Prisma client<br/>data access<br/>[prisma.ts]"]
  node_schema["Schema<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL<br/>database")]
  node_seed["Seed data<br/>bootstrap<br/>[seed.ts]"]
end

subgraph group_ops["Operations"]
  node_compose["Docker Compose<br/>deployment<br/>[docker-compose.yml]"]
end

node_app_layout -->|"wraps"| node_ui_shell
node_home_page -->|"loads"| node_dashboard_actions
node_login_page -->|"authenticates"| node_auth_actions
node_pacientes_area -->|"uses"| node_pacientes_actions
node_pacientes_area -->|"renders"| node_clinical_widgets
node_historia_page -->|"submits"| node_historia_actions
node_historia_page -->|"validates"| node_validation
node_agenda_page -->|"coordinates"| node_agenda_actions
node_agenda_page -->|"renders"| node_clinical_widgets
node_atencion_page -->|"renders"| node_clinical_widgets
node_facturacion_page -->|"processes"| node_facturacion_actions
node_facturacion_page -->|"renders"| node_clinical_widgets
node_medicos_page -->|"renders"| node_clinical_widgets
node_reportes_page -->|"aggregates"| node_reportes_actions
node_reportes_page -->|"renders"| node_report_widgets
node_config_page -->|"administers"| node_auth_actions
node_api_routes -->|"serves"| node_facturacion_actions
node_api_routes -->|"serves"| node_pacientes_actions
node_pacientes_actions -->|"queries"| node_prisma_client
node_historia_actions -->|"writes"| node_prisma_client
node_agenda_actions -->|"queries"| node_prisma_client
node_facturacion_actions -->|"writes"| node_prisma_client
node_auth_actions -->|"reads"| node_prisma_client
node_reportes_actions -->|"reads"| node_prisma_client
node_prisma_client -->|"uses"| node_schema
node_schema -->|"persists to"| node_postgres
node_seed -.->|"initializes"| node_postgres
node_compose -->|"orchestrates"| node_postgres
node_compose -->|"orchestrates"| node_app_layout

click node_app_layout "https://github.com/rickneser2023/sistema-clinico/blob/main/app/layout.tsx"
click node_home_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/page.tsx"
click node_login_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/login/page.tsx"
click node_pacientes_area "https://github.com/rickneser2023/sistema-clinico/blob/main/app/pacientes/page.tsx"
click node_historia_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/nueva-historia/page.tsx"
click node_agenda_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/agenda/page.tsx"
click node_atencion_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/atencion/page.tsx"
click node_facturacion_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/facturacion/page.tsx"
click node_medicos_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/medicos/page.tsx"
click node_reportes_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/ejecutivo/reportes/page.tsx"
click node_config_page "https://github.com/rickneser2023/sistema-clinico/blob/main/app/configuracion/page.tsx"
click node_dashboard_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/dashboard.ts"
click node_pacientes_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/pacientes.ts"
click node_historia_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/historia.ts"
click node_agenda_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/agenda.ts"
click node_facturacion_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/facturacion.ts"
click node_auth_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/auth.ts"
click node_reportes_actions "https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/reportes.ts"
click node_api_routes "https://github.com/rickneser2023/sistema-clinico/blob/main/app/api/users/route.ts"
click node_ui_shell "https://github.com/rickneser2023/sistema-clinico/blob/main/components/DashboardLayout.tsx"
click node_clinical_widgets "https://github.com/rickneser2023/sistema-clinico/blob/main/components/ClinicalCharts.tsx"
click node_report_widgets "https://github.com/rickneser2023/sistema-clinico/blob/main/components/reportes/FiltrosReporte.tsx"
click node_validation "https://github.com/rickneser2023/sistema-clinico/blob/main/lib/validations/pacientes.ts"
click node_prisma_client "https://github.com/rickneser2023/sistema-clinico/blob/main/lib/prisma.ts"
click node_schema "https://github.com/rickneser2023/sistema-clinico/blob/main/prisma/schema.prisma"
click node_seed "https://github.com/rickneser2023/sistema-clinico/blob/main/prisma/seed.ts"
click node_compose "https://github.com/rickneser2023/sistema-clinico/blob/main/docker-compose.yml"

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_app_layout,node_home_page,node_login_page,node_ui_shell toneBlue
class node_pacientes_area,node_historia_page,node_agenda_page,node_atencion_page,node_facturacion_page,node_medicos_page,node_reportes_page,node_config_page,node_clinical_widgets,node_report_widgets toneAmber
class node_dashboard_actions,node_pacientes_actions,node_historia_actions,node_agenda_actions,node_facturacion_actions,node_auth_actions,node_reportes_actions,node_api_routes,node_validation toneMint
class node_prisma_client,node_schema,node_postgres,node_seed toneRose
class node_compose toneIndigo
```

## Components

### Presentation

App Router pages, global shell, and interactive feature components.

- [App shell](https://github.com/rickneser2023/sistema-clinico/blob/main/app/layout.tsx): layout · Global Next.js layout and providers for the whole app. · `app/layout.tsx`
- [Home](https://github.com/rickneser2023/sistema-clinico/blob/main/app/page.tsx): route · Main landing route for the clinical dashboard. · `app/page.tsx`
- [Login](https://github.com/rickneser2023/sistema-clinico/blob/main/app/login/page.tsx): route · Authentication entry screen. · `app/login/page.tsx`
- [Shell UI](https://github.com/rickneser2023/sistema-clinico/blob/main/components/DashboardLayout.tsx): component set · Persistent dashboard layout, header, sidebar, theme, auth, and toast providers. · `components/DashboardLayout.tsx`

### Domain UI

Clinical workflow screens and specialized widgets.

- [Pacientes](https://github.com/rickneser2023/sistema-clinico/blob/main/app/pacientes/page.tsx): route area · Patient list and patient detail/historical views. · `app/pacientes/page.tsx`
- [Nueva historia](https://github.com/rickneser2023/sistema-clinico/blob/main/app/nueva-historia/page.tsx): route · Clinical intake and consultation form. · `app/nueva-historia/page.tsx`
- [Agenda](https://github.com/rickneser2023/sistema-clinico/blob/main/app/agenda/page.tsx): route · Scheduling and calendar workflow. · `app/agenda/page.tsx`
- [Atención](https://github.com/rickneser2023/sistema-clinico/blob/main/app/atencion/page.tsx): route · Active case handling and operational board. · `app/atencion/page.tsx`
- [Facturación](https://github.com/rickneser2023/sistema-clinico/blob/main/app/facturacion/page.tsx): route · Billing and payment flow. · `app/facturacion/page.tsx`
- [Médicos](https://github.com/rickneser2023/sistema-clinico/blob/main/app/medicos/page.tsx): route · Physician management screen. · `app/medicos/page.tsx`
- [Reportes](https://github.com/rickneser2023/sistema-clinico/blob/main/app/ejecutivo/reportes/page.tsx): route · Executive reporting views. · `app/ejecutivo/reportes/page.tsx`
- [Configuración](https://github.com/rickneser2023/sistema-clinico/blob/main/app/configuracion/page.tsx): route · Administration and configuration view. · `app/configuracion/page.tsx`
- [Clinical widgets](https://github.com/rickneser2023/sistema-clinico/blob/main/components/ClinicalCharts.tsx): component set · Reusable clinical and billing UI including charts, forms, preview, and notifications. · `components/ClinicalCharts.tsx`
- [Report widgets](https://github.com/rickneser2023/sistema-clinico/blob/main/components/reportes/FiltrosReporte.tsx): component set · Report filters and tabular preview widgets. · `components/reportes/FiltrosReporte.tsx`

### Server Logic

Server actions and HTTP endpoints that coordinate business workflows.

- [Dashboard](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/dashboard.ts): action domain · Server-side dashboard aggregation and summary logic. · `app/actions/dashboard.ts`
- [Pacientes actions](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/pacientes.ts): action domain · Server actions for patient search, detail, and persistence. · `app/actions/pacientes.ts`
- [Historia actions](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/historia.ts): action domain · Server actions for intake and consultation workflows. · `app/actions/historia.ts`
- [Agenda actions](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/agenda.ts): action domain · Scheduling and appointment server actions. · `app/actions/agenda.ts`
- [Facturación actions](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/facturacion.ts): action domain · Billing, receipts, and payment server actions. · `app/actions/facturacion.ts`
- [Auth actions](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/auth.ts): action domain · Login and access-control server actions. · `app/actions/auth.ts`
- [Reportes actions](https://github.com/rickneser2023/sistema-clinico/blob/main/app/actions/reportes.ts): action domain · Reporting and aggregation server actions. · `app/actions/reportes.ts`
- [API routes](https://github.com/rickneser2023/sistema-clinico/blob/main/app/api/users/route.ts): http boundary · Targeted HTTP endpoints for users and comprobantes. · `app/api/users/route.ts`
- [Validations](https://github.com/rickneser2023/sistema-clinico/blob/main/lib/validations/pacientes.ts): rules · Domain validation rules for citas, historia, and pacientes. · `lib/validations/pacientes.ts`

### Persistence

Prisma client, schema, migrations, and seeded data.

- [Prisma client](https://github.com/rickneser2023/sistema-clinico/blob/main/lib/prisma.ts): data access · Shared Prisma connection and ORM entry point. · `lib/prisma.ts`
- [Schema](https://github.com/rickneser2023/sistema-clinico/blob/main/prisma/schema.prisma): database schema · Prisma schema and migration history for the clinical model. · `prisma/schema.prisma`
- **PostgreSQL**: database · Primary persistent datastore for the application.
- [Seed data](https://github.com/rickneser2023/sistema-clinico/blob/main/prisma/seed.ts): bootstrap · Initial/demo data loader for the database. · `prisma/seed.ts`

### Operations

Containerized runtime and deployment orchestration.

- [Docker Compose](https://github.com/rickneser2023/sistema-clinico/blob/main/docker-compose.yml): deployment · Container orchestration for the app and database. · `docker-compose.yml`

## Connections

- 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.
