System Design
Integra descubrimiento, requisitos, dominio, datos, contratos, componentes, calidad, riesgos, pruebas y operación en el diseño coherente de un sistema completo.
Un sistema completo no se diseña acumulando diagramas. Se diseña manteniendo coherencia entre problema, reglas, comportamiento, datos, contratos, operación y evidencia.
Diseñaremos una plataforma multi-tenant para tiendas que centraliza pedidos, inventario y entregas. El ejemplo no pretende definir la arquitectura final de DomiSys; muestra cómo conectar artefactos sin perder trazabilidad.
Situación actual:
Resultado esperado:
Centralizar pedidos válidos y trazables
sin permitir sobreventa
ni ocultar fallos de pago o entrega.Métricas iniciales:
Un stakeholder puede no operar directamente el sistema y un actor externo puede no ser una persona.
OBJ-01 Reducir pedidos incompletos.
OBJ-02 Evitar stock negativo por concurrencia.
OBJ-03 Hacer visible el ciclo de vida del pedido.
OBJ-04 Recuperar operaciones inciertas sin duplicar efectos.RF-01
El sistema debe permitir crear un pedido con sucursal,
cliente, dirección, líneas y método de pago.RNF-03
El 95 % de las creaciones debe responder en menos de 800 ms
bajo 50 solicitudes por segundo,
excluyendo confirmación asíncrona del proveedor de pago.RB-01 quantity > 0
RB-02 un producto debe pertenecer al tenant del pedido
RB-03 no se confirma sin reserva válida
RB-04 repetir la misma idempotency key no crea otro pedido
RB-05 cancelar una operación pagada inicia compensaciónComo cajero
quiero registrar un pedido completo
para que operación pueda prepararlo sin confirmar datos por otro canal.Given una sucursal activa y productos disponibles
When el cajero confirma un pedido válido
Then el sistema registra un único pedido
And reserva las cantidades
And devuelve un identificador trazableGiven la misma idempotency key ya procesada
When se repite la solicitud
Then no se duplica el pedido ni la reserva
And se devuelve el resultado lógico anteriorActor: Cashier.
Precondiciones: sesión válida, caja habilitada y sucursal activa.
Garantía mínima: ningún fallo deja stock descontado sin pedido trazable.
Garantía de éxito: pedido y reserva quedan confirmados una sola vez.
Alternativas: stock insuficiente, pago rechazado, timeout, solicitud duplicada y dependencia no disponible.
flowchart TD
Start((Inicio)) --> Capture[Capturar pedido]
Capture --> Validate{¿Datos válidos?}
Validate -->|No| Correct[Solicitar corrección]
Validate -->|Sí| Reserve[Reservar stock]
Reserve --> Available{¿Reserva exitosa?}
Available -->|No| Reject[Informar falta de stock]
Available -->|Sí| Payment{¿Requiere pago inmediato?}
Payment -->|No| Confirm[Confirmar pedido]
Payment -->|Sí| Charge[Solicitar cobro]
Charge --> Approved{¿Resultado conocido?}
Approved -->|Aprobado| Confirm
Approved -->|Rechazado| Release[Liberar reserva]
Approved -->|Incierto| Pending[Dejar operación pendiente y reconciliar]
Confirm --> Notify[Notificar]
Notify --> End((Fin))stateDiagram-v2
[*] --> Draft
Draft --> PendingPayment : submit [stockReserved]
Draft --> Confirmed : submit [cashOnDelivery && stockReserved]
PendingPayment --> Confirmed : paymentApproved
PendingPayment --> PaymentFailed : paymentRejected
PendingPayment --> PaymentUnknown : timeout
PaymentUnknown --> Confirmed : reconcileApproved
PaymentUnknown --> PaymentFailed : reconcileRejected
Confirmed --> Preparing : startPreparation
Preparing --> Ready : completePreparation
Ready --> InDelivery : dispatch
InDelivery --> Delivered : confirmDelivery
Draft --> Cancelled : cancel
Confirmed --> Cancelling : cancel [authorized]
Cancelling --> Cancelled : compensationCompleted
Cancelling --> CancellationFailed : compensationFailedLos estados PaymentUnknown y Cancelling hacen visible trabajo pendiente que no debe representarse como éxito o fracaso prematuro.
Conceptos principales:
Order: identidad y ciclo de vida.OrderLine: producto, cantidad y precio acordado.Money: moneda y cantidad válida.Address: datos de entrega validados.StockReservation: unidades retenidas temporalmente.PaymentAttempt: cada intento y su resultado.DeliveryAssignment: relación entre pedido y repartidor.Invariantes:
erDiagram
TENANT ||--o{ BRANCH : owns
TENANT ||--o{ PRODUCT : owns
BRANCH ||--o{ INVENTORY_ITEM : stores
PRODUCT ||--o{ INVENTORY_ITEM : tracked_as
BRANCH ||--o{ ORDER : receives
ORDER ||--|{ ORDER_LINE : contains
ORDER ||--o{ STOCK_RESERVATION : protects
ORDER ||--o{ PAYMENT_ATTEMPT : has
ORDER ||--o| DELIVERY_ASSIGNMENT : receivesDecisiones físicas importantes:
(tenant_id, sku).(tenant_id, idempotency_key) para operación relevante.POST /orders
Idempotency-Key: <uuid>
Authorization: Bearer <token>Request:
{
"branchId": "b1",
"customerId": "c1",
"items": [
{ "productId": "p1", "quantity": 2 }
],
"paymentMethod": "cash_on_delivery"
}Respuestas relevantes:
201: pedido creado.200: repetición idempotente con resultado existente.409: stock insuficiente o conflicto de versión.422: datos válidos sintácticamente pero contrarios a reglas.503: dependencia no disponible cuando no existe alternativa segura.Los errores incluyen código estable, detalle, correlation ID y campos afectados.
sequenceDiagram
autonumber
actor Cashier
participant Web
participant API as Order API
participant Inventory
participant DB
participant Outbox
Cashier->>Web: Confirma pedido
Web->>API: POST /orders + Idempotency-Key
API->>API: Autorizar y validar
API->>Inventory: Reservar cantidades
Inventory->>DB: Actualización condicional
DB-->>Inventory: Reserva creada
Inventory-->>API: reservationId
API->>DB: Insertar pedido, líneas y outbox
DB-->>API: Commit
API-->>Web: 201 Created
Outbox->>DB: Leer evento confirmado
Outbox-->>Outbox: Publicar OrderCreatedLa publicación usa outbox para evitar confirmar base de datos y perder el evento entre dos operaciones separadas.
Order Controller
→ traduce HTTP, identidad y validación superficial
Place Order
→ coordina caso de uso
Order Domain
→ protege reglas y estados
Inventory Port
→ contrato de reserva y liberación
Repositories
→ persistencia, sin decidir políticas de negocio
Outbox Publisher
→ entrega eventos confirmados
Reconciliation Worker
→ resuelve pagos o compensaciones inciertasControles:
Supuestos iniciales:
20 000 pedidos/día
factor pico 12
10 lecturas por pedido
2 KB por pedido base, sin auditoría ni índicesOrden de magnitud:
escrituras promedio ≈ 0.23/s
pico estimado ≈ 3/s
lecturas promedio ≈ 2.3/s
pico estimado ≈ 28/sLos números no justifican microservicios por escala. Sí justifican medir carreras de inventario y picos por horarios.
Escenarios:
RTO y RPO se definen por capacidad. Restaurar backups se practica, no se asume.
SLIs:
Cada operación conserva request_id, trace_id, tenant_id, order_id cuando existe y versión desplegada, evitando PII innecesaria.
Razón: escala moderada, equipo pequeño y necesidad de transacciones locales claras.
Consecuencia positiva: menor coste operativo.
Consecuencia negativa: requiere límites internos disciplinados y dificulta escalado independiente si aparece una necesidad real.
Razón: separar unidades disponibles de pedidos aún no confirmados.
Coste: expiración, liberación y reconciliación.
Razón: consistencia entre commit y publicación.
Coste: worker, lag, deduplicación y monitoreo.
Riesgo prioritario: doble reserva.
POC:
Pregunta
→ ¿La estrategia de control evita stock negativo con 100 solicitudes concurrentes?
Criterio
→ stock nunca negativo
→ reservas exitosas no exceden disponibilidad
→ conflictos terminan en tiempo aceptableOtros riesgos:
OBJ-02 evitar sobreventa
→ RF-07 reservar stock
→ RB-03 no confirmar sin reserva
→ CU-04 registrar pedido
→ StockReservation + InventoryItem
→ POST /orders
→ Inventory Port + transacción condicional
→ POC concurrente + integration test
→ métrica stock_negative_totalAntes de implementar:
PaymentUnknown es mejor que devolver rechazo tras un timeout?Antipatrones de System Design ayuda a reconocer atajos que rompen esta coherencia.