Arquitectura Tecnica de MedTime¶

Identificador: TECH-ARC-001 Version: 0.1.0 Fecha: 2025-12-07 Ultima Revision: Creacion inicial - IT-01 Autor: ArchitectureDrone (MTS-DRN-ARC-001) Refs Funcional: MTS-ARQ-001 Refs UI: UI-MTS-INDEX-001

1. Vision Arquitectonica
1.1. Principios Fundamentales
1.2. Restricciones Arquitectonicas
2. Modelo C4
2.1. Nivel 1: Contexto del Sistema
2.2. Nivel 2: Contenedores
2.3. Nivel 3: Componentes (por definir)
3. Clean Architecture
3.1. Capas de la Arquitectura
3.2. Regla de Dependencias
3.3. Estructura de Proyecto
4. Principios SOLID
5. Patrones de Diseno
5.1. Patrones Estructurales
5.2. Patrones de Comportamiento
5.3. Patrones de Datos
6. Comunicacion entre Servicios
7. Estrategia Offline-First
8. Decisiones Arquitectonicas
9. Referencias

1. Vision Arquitectonica¶

1.1. Principios Fundamentales¶

MedTime sigue una arquitectura moderna, escalable y segura basada en los siguientes principios:

Principio	Descripcion	Implicacion
Privacy by Design	La privacidad es parte integral del diseno	Cifrado E2E, Zero-Knowledge donde sea posible
Offline-First	La app funciona sin conexion	Sincronizacion robusta, conflict resolution
Clean Architecture	Separacion clara de responsabilidades	Capas independientes, testeable
API-First	APIs como contrato de comunicacion	OpenAPI specs antes de implementacion
Security by Default	Seguridad no es opcional	OWASP, HIPAA compliance por defecto

1.2. Restricciones Arquitectonicas¶

Restriccion	Razon	ADR
iOS 15+ / Android 8+	Balance features vs alcance	ADR-006 (pendiente)
REST over GraphQL	Simplicidad, caching, tooling	ADR-007 (pendiente)
Firebase Auth	Time-to-market, seguridad probada	ADR-002
PostgreSQL	Open source, SQL estándar (agnóstico)	ADR-004

IMPORTANTE: Para entender la arquitectura dual Cliente-Servidor de MedTime, consultar 02-arquitectura-cliente-servidor.md (TECH-CS-001). Este documento define la separación LOCAL vs SERVIDOR y es FUNDAMENTAL para el desarrollo.

2. Modelo C4¶

Siguiendo el Modelo C4 para documentacion de arquitectura.

2.1. Nivel 1: Contexto del Sistema¶

C4Context
    title System Context Diagram - MedTime

    Person(patient_ind, "Paciente Independiente", "Gestiona su propia medicacion de forma autonoma")
    Person(patient_dep, "Paciente Dependiente", "Requiere supervision de un cuidador")
    Person(caregiver_sol, "Cuidador Solidario", "Supervisa pacientes sin responsabilidad legal")
    Person(caregiver_resp, "Cuidador Responsable", "Tutela legal de pacientes dependientes")
    Person(doctor, "Medico", "Profesional medico con acceso a reportes")
    Person(health_pro, "Profesional Sanitario", "Enfermero, farmaceutico u otro profesional")

    System(medtime, "MedTime", "Suite de aplicaciones para gestion de medicamentos y adherencia al tratamiento")

    System_Ext(drugbank, "DrugBank API", "Base de datos de medicamentos e interacciones")
    System_Ext(rxnorm, "RxNorm API", "Normalizacion de medicamentos USA")
    System_Ext(calendar, "Calendar APIs", "Google/Apple Calendar")
    System_Ext(push, "Push Services", "FCM/APNs")
    System_Ext(auth, "Firebase Auth", "Autenticacion")

    Rel(patient_ind, medtime, "Usa", "HTTPS")
    Rel(patient_dep, medtime, "Usa (supervisado)", "HTTPS")
    Rel(caregiver_sol, medtime, "Supervisa", "HTTPS")
    Rel(caregiver_resp, medtime, "Gestiona", "HTTPS")
    Rel(doctor, medtime, "Consulta", "HTTPS")
    Rel(health_pro, medtime, "Consulta", "HTTPS")

    Rel(medtime, drugbank, "Consulta interacciones", "HTTPS/API Key")
    Rel(medtime, rxnorm, "Normaliza medicamentos", "HTTPS")
    Rel(medtime, calendar, "Sincroniza eventos", "OAuth2")
    Rel(medtime, push, "Envia notificaciones", "HTTPS")
    Rel(medtime, auth, "Autentica usuarios", "HTTPS")

2.1.1. Actores del Sistema¶

Actor	Descripcion	Tier Minimo	Requiere Cuenta
Paciente Independiente	Usuario autonomo que gestiona su propia medicacion	Free	Opcional (solo local)
Paciente Dependiente	Usuario supervisado por cuidador(es), puede tener autonomia limitada	Free	Si (para vinculacion)
Cuidador Solidario	Supervisa pacientes sin responsabilidad legal (familiar, amigo)	Pro	Si
Cuidador Responsable	Tutela legal de pacientes dependientes (padre, tutor legal)	Pro	Si
Medico	Profesional medico con acceso de solo lectura a reportes compartidos	Perfect	Si
Profesional Sanitario	Enfermero, farmaceutico u otro profesional de salud	Perfect	Si

NOTA: Un Paciente Independiente en tier Free puede operar sin cuenta de usuario (100% local). Para acceder a catalogos publicos, ser paciente dependiente o cuidador, se requiere cuenta.

2.1.2. Sistemas Externos¶

Sistema	Proposito	Integracion
DrugBank API	Interacciones medicamentosas	REST API + Cache
RxNorm API	Normalizacion medicamentos	REST API
Firebase Auth	Autenticacion, MFA	SDK
FCM/APNs	Push notifications	SDK
Google/Apple Calendar	Sincronizacion	OAuth2

2.2. Nivel 2: Contenedores¶

C4Container
    title Container Diagram - MedTime

    Person(patient, "Paciente")

    System_Boundary(medtime, "MedTime System") {
        Container(ios_app, "iOS App", "Swift/SwiftUI", "Aplicacion nativa iOS")
        Container(android_app, "Android App", "Kotlin/Compose", "Aplicacion nativa Android")
        Container(web_portal, "Web Portal", "React/Next.js", "Portal para medicos")

        Container(api_gateway, "API Gateway", "Cloud Functions/Edge", "Routing, rate limiting, auth")

        Container(auth_service, "Auth Service", "Firebase Auth", "Autenticacion y autorizacion")
        Container(med_service, "Medications API", "Node.js/TypeScript", "Gestion de medicamentos")
        Container(ntf_service, "Notifications API", "Node.js/TypeScript", "Notificaciones y alertas")
        Container(sync_service, "Sync Service", "Node.js/TypeScript", "Sincronizacion offline")

        ContainerDb(main_db, "Main Database", "PostgreSQL/Supabase", "Datos principales")
        ContainerDb(cache, "Cache", "Redis", "Cache de sesiones y datos frecuentes")
        ContainerDb(local_db_ios, "Local DB iOS", "Core Data", "Almacenamiento offline iOS")
        ContainerDb(local_db_android, "Local DB Android", "Room", "Almacenamiento offline Android")
    }

    System_Ext(external, "External APIs", "DrugBank, RxNorm, Calendar")

    Rel(patient, ios_app, "Usa", "HTTPS")
    Rel(patient, android_app, "Usa", "HTTPS")

    Rel(ios_app, api_gateway, "API calls", "HTTPS/REST")
    Rel(android_app, api_gateway, "API calls", "HTTPS/REST")
    Rel(web_portal, api_gateway, "API calls", "HTTPS/REST")

    Rel(api_gateway, auth_service, "Valida tokens")
    Rel(api_gateway, med_service, "Routing")
    Rel(api_gateway, ntf_service, "Routing")
    Rel(api_gateway, sync_service, "Routing")

    Rel(med_service, main_db, "R/W", "SQL")
    Rel(ntf_service, main_db, "R/W", "SQL")
    Rel(sync_service, main_db, "R/W", "SQL")
    Rel(med_service, cache, "R/W", "Redis Protocol")

    Rel(med_service, external, "Consulta", "HTTPS")

    Rel(ios_app, local_db_ios, "R/W offline")
    Rel(android_app, local_db_android, "R/W offline")

2.2.1. Contenedores Principales¶

Contenedor	Tecnologia	Responsabilidad
iOS App	Swift/SwiftUI	Cliente nativo iOS
Android App	Kotlin/Compose	Cliente nativo Android
Web Portal	React/Next.js	Portal medicos (read-only)
API Gateway	Cloud Functions	Routing, auth, rate limiting
Medications API	Node.js/TS	CRUD medicamentos
Notifications API	Node.js/TS	Push, alertas
Sync Service	Node.js/TS	Sincronizacion offline
Main Database	PostgreSQL	Datos persistentes
Cache	Redis	Sesiones, cache

2.3. Nivel 3: Componentes (por definir)¶

Los diagramas de componentes se definen por servicio en las iteraciones IT-04 a IT-17.

Ver:

apis/API-AUTH-001.md - Componentes de autenticacion
apis/API-MED-001.md - Componentes de medicamentos
etc.

3. Clean Architecture¶

MedTime implementa Clean Architecture para garantizar mantenibilidad y testeabilidad.

3.1. Capas de la Arquitectura¶

flowchart TB
    subgraph PRESENTATION["PRESENTATION"]
        direction TB
        P1["Views, ViewModels, UI Components, Navigation"]
        P2["SwiftUI Views, Jetpack Compose, React Components"]
    end

    subgraph DOMAIN["DOMAIN"]
        direction TB
        subgraph UC["Use Cases (Interactors)"]
            UC1["AddMedicationUseCase"]
            UC2["GetMedicationScheduleUseCase"]
            UC3["RecordDoseUseCase"]
            UC4["CheckInteractionsUseCase"]
        end
        subgraph ENT["Entities (Domain Models)"]
            E1["Medication, Schedule, Dose, User, Alert"]
        end
        subgraph REPO_INT["Repository Interfaces (Ports)"]
            RI1["MedicationRepository, UserRepository, etc."]
        end
    end

    subgraph DATA["DATA"]
        direction TB
        subgraph REPO_IMPL["Repository Implementations (Adapters)"]
            RIM1["MedicationRepositoryImpl"]
            RIM2["CachedMedicationRepository"]
        end
        subgraph DS["Data Sources"]
            DS1["RemoteDataSource (API)"]
            DS2["LocalDataSource (CoreData/Room)"]
            DS3["CacheDataSource (In-memory)"]
        end
        subgraph MAP["Mappers"]
            M1["DTOtoEntity, EntityToDTO"]
        end
    end

    PRESENTATION --> DOMAIN
    DATA --> DOMAIN

    style PRESENTATION fill:#fff3e0,stroke:#e65100
    style DOMAIN fill:#e8f5e9,stroke:#2e7d32
    style DATA fill:#e3f2fd,stroke:#1565c0

3.2. Regla de Dependencias¶

flowchart TB
    subgraph PRES["PRESENTATION"]
        P1["UI / ViewModels"]
    end

    subgraph DOM["DOMAIN (Centro)"]
        D1["Entities"]
        D2["UseCases"]
        D3["Interfaces"]
    end

    subgraph DAT["DATA"]
        DA1["Repositories (impl)"]
    end

    PRES -->|"depende de"| DOM
    DAT -->|"depende de"| DOM

    subgraph NUNCA["PROHIBIDO"]
        N1["Domain → Presentation"]
        N2["Domain → Data"]
        N3["Presentation → Data"]
    end

    style PRES fill:#fff3e0,stroke:#e65100
    style DOM fill:#e8f5e9,stroke:#2e7d32
    style DAT fill:#e3f2fd,stroke:#1565c0
    style NUNCA fill:#ffebee,stroke:#c62828

Regla: Las dependencias SIEMPRE apuntan hacia adentro (hacia Domain)

3.3. Estructura de Proyecto¶

3.3.1. iOS (Swift)¶

MedTime-iOS/
├── App/
│   ├── MedTimeApp.swift
│   └── DI/ (Dependency Injection)
├── Presentation/
│   ├── Screens/
│   │   ├── Medications/
│   │   ├── Schedule/
│   │   └── ...
│   ├── Components/
│   └── Navigation/
├── Domain/
│   ├── Entities/
│   ├── UseCases/
│   └── Repositories/ (Interfaces)
└── Data/
    ├── Repositories/ (Implementations)
    ├── DataSources/
    │   ├── Remote/
    │   └── Local/
    ├── DTOs/
    └── Mappers/

3.3.2. Android (Kotlin)¶

MedTime-Android/
├── app/
│   └── src/main/java/com/medtime/
│       ├── di/
│       └── MedTimeApp.kt
├── presentation/
│   ├── screens/
│   ├── components/
│   └── navigation/
├── domain/
│   ├── entities/
│   ├── usecases/
│   └── repositories/
└── data/
    ├── repositories/
    ├── datasources/
    ├── dtos/
    └── mappers/

4. Principios SOLID¶

Principio	Aplicacion en MedTime
Single Responsibility	Cada UseCase hace una sola cosa
Open/Closed	Entidades extensibles sin modificar
Liskov Substitution	Repositories intercambiables (mock/real)
Interface Segregation	Interfaces especificas por funcionalidad
Dependency Inversion	Domain define interfaces, Data implementa

5. Patrones de Diseno¶

5.1. Patrones Estructurales¶

Patron	Uso	Notas
Repository	Abstraccion de acceso a datos	Ver TPAT-001 en indice
Adapter	DTOs <-> Entities	Patron estandar, usado en capa Data
Facade	API Gateway simplifica servicios	Ver API Gateway specs

5.2. Patrones de Comportamiento¶

Patron	Uso	Notas
Strategy	Algoritmos de recordatorio intercambiables	Patron estandar GoF
Observer	Actualizaciones reactivas (Combine/Flow)	Patron estandar GoF, nativo en frameworks
Command	Operaciones offline en cola	Ver MOB-OFFLINE-001

5.3. Patrones de Datos¶

Patron	Uso	Notas
Unit of Work	Transacciones atomicas	Patron de Martin Fowler, implementado en repos
CQRS (ligero)	Separacion lectura/escritura	Implementacion simplificada, ver specs de APIs
Event Sourcing	Audit trail (parcial)	Solo para auditoria medica, ver PERF-001

6. Comunicacion entre Servicios¶

┌──────────────────────────────────────────────────────────────┐
│                    COMUNICACION                               │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  Mobile App ──────► API Gateway ──────► Services             │
│       │                  │                  │                │
│       │              [Auth Check]           │                │
│       │              [Rate Limit]           │                │
│       │              [Logging]              │                │
│       │                  │                  │                │
│       ▼                  ▼                  ▼                │
│  ┌─────────┐      ┌──────────┐      ┌──────────┐           │
│  │ Offline │      │  Sync    │      │  Event   │           │
│  │  Queue  │ ───► │  Service │ ◄──► │   Bus    │           │
│  └─────────┘      └──────────┘      └──────────┘           │
│                                                               │
└──────────────────────────────────────────────────────────────┘

Protocolos:
- Mobile <-> API: REST/HTTPS + JSON
- Services internos: REST (sincrono) o Event Bus (asincrono)
- Real-time: WebSockets (Supabase Realtime)

7. Estrategia Offline-First¶

┌─────────────────────────────────────────────────────────────┐
│                   OFFLINE-FIRST STRATEGY                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. WRITE LOCAL FIRST                                        │
│     User Action → Local DB → Success UI → Queue for Sync    │
│                                                              │
│  2. SYNC WHEN ONLINE                                         │
│     Online Detected → Process Queue → Remote API → Confirm  │
│                                                              │
│  3. CONFLICT RESOLUTION                                      │
│     Server timestamp > Local → Server wins                   │
│     User explicit merge → Show conflict UI                   │
│                                                              │
│  4. CRITICAL DATA PRIORITY                                   │
│     High: Doses taken, alerts acknowledged                   │
│     Medium: Medication changes, schedule updates             │
│     Low: Preferences, analytics                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Ver documento completo: mobile/MOB-OFFLINE-001.md

8. Decisiones Arquitectonicas¶

Las decisiones arquitectonicas se documentan como ADRs en knowledge-base/adrs/:

ADR	Titulo	Estado
ADR-001	Clean Architecture	Propuesto
ADR-002	Firebase Auth vs Custom	Propuesto
ADR-003	Offline-First Strategy	Propuesto
ADR-004	Database Selection	Propuesto
ADR-005	API Versioning	Propuesto

9. Referencias¶

C4 Model - Documentacion de arquitectura
Clean Architecture - Robert C. Martin
SOLID Principles - Wikipedia
functional-spec/03-arquitectura-funcional.md - Arquitectura funcional
UiSpec/00-ui-spec-index.md - Especificacion de UI

Documento generado por ArchitectureDrone (MTS-DRN-ARC-001) - IT-01