CrmClinicas/docs/plans/2026-03-02-crm-clinicas-design.md

# CRM Clinicas SaaS — Documento de Diseno

**Fecha:** 2026-03-02
**Estado:** Aprobado
**Cliente:** Clinica general multiespecialidad (Mexico)
**Deployment:** Self-hosted en VM Ubuntu 24.04 (4 CPU, 15GB RAM, 24GB disco)

---

## 1. Vision General

CRM SaaS completo para clinicas medicas en Mexico. MVP orientado a una clinica pequena (1-3 doctores) con arquitectura multi-tenant preparada para escalar a multiples clientes.

## 2. Stack Tecnologico

| Capa | Tecnologia |
|------|-----------|
| Frontend | Next.js 15 (App Router) + TypeScript + Tailwind CSS + shadcn/ui |
| Backend/BaaS | Supabase Self-Hosted (PostgreSQL + Auth + Storage + Realtime) |
| CFDI | Facturama API |
| WhatsApp | Twilio / 360dialog |
| Pagos SaaS | Conekta |
| Reverse Proxy | Nginx |
| SSL | Certbot + Let's Encrypt (cuando haya dominio) |
| Contenedores | Docker + Docker Compose |
| OS | Ubuntu 24.04 LTS |

## 3. Arquitectura

```
VM (Ubuntu 24.04)
  Docker Compose:
    - Nginx (:80) -> reverse proxy
    - Next.js App (:3000)
    - Supabase Stack:
      - PostgreSQL (:5432)
      - GoTrue Auth (:9999)
      - Storage (:5000)
      - Realtime (:4000)
      - Kong API Gateway (:8000)
      - Studio (:3001) — admin panel
```

### Multi-tenancy

Row-Level Security (RLS) en PostgreSQL. Cada tabla tiene `clinic_id`. Politicas RLS filtran automaticamente segun el JWT del usuario autenticado. Ningun query puede cruzar datos entre clinicas.

## 4. Modulos del MVP

### 4.1 Gestion de Pacientes
- CRUD completo con datos demograficos, CURP, alergias, tipo de sangre
- Busqueda rapida por nombre, telefono, CURP
- Timeline cronologico (citas, consultas, facturas, archivos)
- Comunicacion WhatsApp
- Fuente de captacion (referido, redes, Google)
- Import/export CSV

### 4.2 Agenda y Citas
- Calendario visual (dia/semana/mes) por doctor
- Drag-and-drop para reagendar
- Slots configurables por doctor (duracion, horarios por dia)
- Bloqueo de horarios (vacaciones, juntas)
- Estados: scheduled -> confirmed -> in_progress -> completed / cancelled / no_show
- Recordatorios automaticos WhatsApp 24h y 1h antes
- Lista de espera
- Vista de recepcion (citas del dia, quien llego, quien esta en consulta)

### 4.3 Expediente Clinico Electronico
- Historia clinica: antecedentes familiares, personales, quirurgicos, medicamentos, alergias, inmunizaciones
- Nota de consulta SOAP (Subjective, Objective, Assessment, Plan)
- Signos vitales con graficas de tendencia
- Diagnosticos CIE-10
- Receta digital PDF con cedula profesional
- Archivos adjuntos (labs, imagenes, estudios)
- Firma digital del doctor
- Export PDF del expediente completo

### 4.4 Facturacion y Pagos
- Catalogo de servicios con claves SAT
- Creacion de factura desde consulta completada
- Timbrado CFDI 4.0 via Facturama API
- Cancelacion CFDI con motivo
- Formas de pago: efectivo, tarjeta, transferencia
- Cuentas por cobrar y parcialidades
- Corte de caja diario
- Reportes de ingresos por periodo, doctor, servicio

### 4.5 Inventario
- Catalogo de productos (medicamento, insumo, material, equipo)
- Control de stock por sucursal
- Movimientos: entrada, salida, ajuste, merma
- Alertas de stock minimo
- Vinculacion a consulta (descuento automatico)
- Vinculacion a factura
- Reporte de movimientos

### 4.6 Dashboard y Reportes
- KPIs: pacientes nuevos, citas del dia, ingresos del mes, tasa ausentismo
- Graficas: ingresos por mes, citas por doctor, servicios mas solicitados
- Ocupacion de agenda por doctor
- Inventario critico

## 5. Modelo de Datos

### Tablas principales:

```
clinics (tenant)
users (doctores, staff — vinculado a auth.users)
patients
doctor_schedules
appointments
medical_records (antecedentes)
consultation_notes (notas SOAP por visita)
prescriptions
medical_files
services_catalog
invoices
invoice_items
payments
products
inventory_stock
inventory_movements
branches
audit_log
```

### Campos clave por tabla:

**clinics:** id, name, slug, rfc, razon_social, regimen_fiscal, codigo_postal, pac_provider, pac_api_key (encrypted), subscription_plan, subscription_status

**patients:** id, clinic_id, first_name, last_name, date_of_birth, gender, curp, phone, email, address (jsonb), blood_type, allergies (text[]), emergency_contact (jsonb), source

**appointments:** id, clinic_id, patient_id, doctor_id, starts_at, ends_at, status, type, reason, reminder_sent

**consultation_notes:** id, clinic_id, patient_id, doctor_id, appointment_id, subjective, objective, assessment, plan, vital_signs (jsonb), diagnoses (jsonb CIE-10), is_signed

**invoices:** id, clinic_id, patient_id, invoice_number, cfdi_uuid, cfdi_status, uso_cfdi, forma_pago, metodo_pago, subtotal, tax_amount, total, payment_status

**products:** id, clinic_id, sku, name, category, unit, purchase_price, sale_price, min_stock

**inventory_movements:** id, clinic_id, product_id, type, quantity, reason, reference_id

## 6. Seguridad y Cumplimiento

- NOM-004-SSA3-2012: Notas SOAP, firma digital, historial inmutable (soft delete)
- NOM-024-SSA3-2012: Control de acceso, bitacora de accesos, integridad
- LFPDPPP: Aviso de privacidad, consentimiento, encriptacion, derechos ARCO
- CFDI 4.0 SAT: PAC certificado (Facturama), claves SAT, XML firmado
- Multi-tenancy: RLS de PostgreSQL
- Encriptacion: HTTPS (cuando hay dominio), encriptacion at-rest, pgcrypto para campos sensibles
- Auditoria: tabla audit_log con triggers automaticos
- Roles: owner > admin > doctor > receptionist
- Backups: pg_dump cron diario con rotacion 7 dias

## 7. Estructura del Proyecto

```
src/
  app/
    (auth)/          — login, register, forgot-password
    (dashboard)/     — layout protegido con sidebar
      patients/
      appointments/
      medical-records/
      billing/
      inventory/
      settings/
    api/webhooks/    — conekta, whatsapp
  components/
    ui/              — shadcn/ui
    forms/
    calendar/
    medical/
    layout/
  lib/
    supabase/        — client, server, admin
    cfdi/            — integracion PAC
    whatsapp/
    utils/
  hooks/
  types/
supabase/
  migrations/
  seed.sql
  functions/         — edge functions (reminders, cfdi)
docker-compose.yml
nginx.conf
```

## 8. Integraciones Externas

| Servicio | Uso | Costo |
|----------|-----|-------|
| Facturama | CFDI SAT | ~$1.50 MXN/factura |
| Twilio/360dialog | WhatsApp | ~$0.50 MXN/mensaje |
| Conekta | Pagos suscripciones | 2.9% + $2.50/tx |
| Resend | Emails transaccionales | Free tier |

## 9. Modelo de Negocio SaaS

| Plan | Precio | Doctores | Sucursales | Features |
|------|--------|----------|------------|----------|
| Basico | $799 MXN/mes | 1 | 1 | Agenda + Expediente |
| Pro | $1,499 MXN/mes | 3 | 2 | + Facturacion + Inventario |
| Enterprise | $2,999 MXN/mes | Ilimitado | Ilimitado | + WhatsApp + Reportes avanzados |

Trial gratuito: 14 dias (Plan Pro)

## 10. Costos Operativos (Self-Hosted)

| Concepto | Mensual |
|----------|---------|
| VM | $0 (existente) |
| Dominio | ~$17 MXN/mes |
| Facturama | ~$300 MXN/mes |
| Twilio | ~$200 MXN/mes |
| **Total** | **~$520 MXN/mes** |

## 11. Roadmap

| Fase | Semanas | Entregable |
|------|---------|-----------|
| 1 - Fundacion | 1-2 | Docker setup, auth, multi-tenancy RLS, layout, CRUD pacientes |
| 2 - Agenda | 3-4 | Calendario, slots, citas, estados, vista recepcion |
| 3 - Expediente | 5-7 | Historia clinica, notas SOAP, recetas PDF, archivos |
| 4 - Facturacion | 8-10 | Catalogo servicios, facturas, CFDI, pagos, corte de caja |
| 5 - Inventario | 11-12 | Productos, stock, movimientos, alertas |
| 6 - Polish | 13-14 | Dashboard, reportes, WhatsApp, testing, produccion |

## 12. Deployment (Self-Hosted)

- Docker Compose con todos los servicios
- Nginx como reverse proxy (:80)
- Acceso por IP publica (sin dominio por ahora)
- SSL con Certbot cuando se agregue dominio
- Backups automaticos con pg_dump + cron
- Monitoreo basico con docker logs + healthchecks