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