System Design - Sistema de Reservas de Turnos Medicos
Proposito
Documento de diseno de alto nivel del sistema. Muestra los componentes principales, como se comunican, y las decisiones arquitectonicas que los conectan.
Cuando usarlo
- Al inicio del proyecto para alinear al equipo.
- Cuando un nuevo miembro se une al equipo.
- Cuando se evalua un cambio que afecta multiples componentes.
1. Vision General
El sistema permite a pacientes reservar turnos con medicos de diferentes especialidades en clinicas. Es una aplicacion web con API REST, base de datos relacional, y servicios de soporte para notificaciones.
2. Diagrama de Arquitectura (Texto)
+------------------+
| Frontend Web |
| (React SPA) |
+--------+---------+
|
HTTPS/REST
|
+--------v---------+
| API Gateway / |
| Load Balancer |
+--------+---------+
|
+--------------+--------------+
| |
+---------v----------+ +----------v---------+
| Backend API | | Backend API |
| (NestJS) | | (NestJS) |
| Instancia 1 | | Instancia 2 |
+---------+----------+ +----------+----------+
| |
+-------------+---------------+
|
+--------v---------+
| PgBouncer |
| (Conn Pooler) |
+--------+---------+
|
+--------v---------+
| PostgreSQL 17 |
| (DO Managed) |
+------------------+
Servicios Auxiliares:
+------------------+ +------------------+
| Queue (SQS/Bull) |---->| Workers |
| (Notificaciones) | | (Email/Push) |
+------------------+ +------------------+
+------------------+
| File Storage |
| (DO Spaces/S3) |
+------------------+
3. Componentes Principales
3.1 Frontend Web (React SPA)
- Responsabilidad: Interfaz de usuario para pacientes, medicos, y admins.
- Tecnologia: React + TypeScript + Vite.
- Comunicacion: REST API via HTTPS.
- Hosting: CDN (Cloudflare Pages o similar).
3.2 Backend API (NestJS)
- Responsabilidad: Logica de negocio, validacion, autorizacion.
- Tecnologia: NestJS + TypeORM + TypeScript.
- Desplegado: VPS con PM2 en cluster mode (2-3 instancias).
- Autenticacion: JWT con RS256.
- Documentacion: OpenAPI/Swagger autogenerado.
3.3 Base de Datos (PostgreSQL 17)
- Responsabilidad: Persistencia de datos transaccionales.
- Managed: DigitalOcean Managed PostgreSQL.
- Connection Pooling: PgBouncer en transaction mode.
- Decisiones clave: Ver ADR-001.
3.4 Cola de Mensajes
- Responsabilidad: Procesamiento asincrono de notificaciones.
- Opciones: AWS SQS (si ya usamos AWS) o BullMQ con Redis.
- Mensajes: Confirmacion de turno, recordatorio, cancelacion.
3.5 Servicio de Notificaciones
- Responsabilidad: Envio de emails y push notifications.
- Email: SendGrid o AWS SES.
- Workers: Procesan mensajes de la cola y envian notificaciones.
3.6 File Storage
- Responsabilidad: Almacenar fotos de perfil de medicos, documentos.
- Tecnologia: DigitalOcean Spaces (compatible S3).
4. Flujos Principales
4.1 Reserva de Turno
Paciente -> Frontend -> API (POST /bookings)
1. Validar autenticacion (JWT)
2. Validar datos de entrada
3. Verificar disponibilidad (query a BD con lock)
4. Crear booking (INSERT con transaccion)
5. Encolar notificacion (mensaje a cola)
6. Retornar confirmacion al paciente
Worker de Notificaciones:
1. Leer mensaje de la cola
2. Enviar email al paciente (confirmacion)
3. Enviar email/push al medico (nueva reserva)
4. Marcar mensaje como procesado
4.2 Busqueda de Disponibilidad
Paciente -> Frontend -> API (GET /doctors/:id/availability?date_from=X&date_to=Y)
1. Obtener DoctorAvailability del medico (horario recurrente)
2. Obtener BlockedDates en el rango
3. Obtener Bookings existentes en el rango
4. Calcular slots disponibles = Availability - BlockedDates - Bookings
5. Retornar lista de slots con fecha, hora inicio, hora fin
4.3 Autenticacion
Usuario -> Frontend -> API (POST /auth/login)
1. Validar email + password (bcrypt compare)
2. Verificar cuenta activa y no bloqueada
3. Generar access token (JWT, 15 min)
4. Generar refresh token (opaco, 7 dias, guardado en BD)
5. Retornar tokens
Frontend en cada request:
1. Enviar access token en header Authorization: Bearer <token>
2. Si 401 -> intentar refresh con POST /auth/refresh
3. Si refresh falla -> redirigir a login
5. Decisiones Arquitectonicas Clave
| Decision |
ADR |
Resumen |
| Base de datos |
ADR-001 |
PostgreSQL managed en DO |
| Estilo de API |
ADR-002 |
REST con OpenAPI |
| Deployment |
Pendiente |
PM2 cluster mode en VPS |
| Autenticacion |
Dentro de FEAT-001 |
JWT con RS256 |
6. Requisitos No Funcionales
| Requisito |
Target |
Estrategia |
| Disponibilidad |
99.5% |
Managed DB con failover, PM2 con restart automatico |
| Latencia API (p95) |
< 500ms |
Connection pooling, indices en BD, caching futuro |
| Throughput |
100 req/s |
PM2 cluster mode, PgBouncer |
| Seguridad datos salud |
Compliance basico |
Encriptacion at-rest y in-transit, audit log |
| Recovery Time (RTO) |
< 1 hora |
Backups diarios, runbook documentado |
| Recovery Point (RPO) |
< 24 horas |
Backups diarios automaticos |
7. Riesgos Tecnicos
| Riesgo |
Probabilidad |
Impacto |
Mitigacion |
| Doble booking por concurrencia |
Media |
Alto |
SELECT FOR UPDATE + transacciones |
| Agotamiento de conexiones a BD |
Media |
Alto |
PgBouncer + pool budget por instancia |
| Caida de servicio de email |
Baja |
Medio |
Cola con reintentos, booking no depende de email |
| Crecimiento de datos historicos |
Baja (a corto plazo) |
Medio |
Particionamiento de bookings por fecha |
8. Evolucion Futura
Corto plazo (6 meses)
- Agregar recordatorios automaticos (24h antes del turno).
- Cache de disponibilidad con Redis.
- App mobile (React Native).
- Telemedicina con videollamadas.
- Integracion con obras sociales / seguros.
- Dashboard de analytics para clinicas.
Largo plazo (2+ anos)
- IA para sugerencias de horarios optimos.
- Recetas electronicas.
- Integracion con historia clinica electronica.
Checklist de Completitud
Archivos relacionados