# Especificación de arquitectura de sistema Convierte un alcance y sus requisitos medidos en una arquitectura con la que alguien puede construir — con cada componente trazado hasta un requisito y cada decisión cargando las alternativas que descartó. ## Entregable Un documento Markdown, `architecture-specification.md`, con la estructura fijada en **Salida** más abajo. Toma la salida de **Definición de requisitos no funcionales** y alimenta **Diseño de contratos de API** y **Modelo de datos y plan de migración**. ## Entradas obligatorias - **El alcance** — las capacidades que el sistema debe ofrecer, en forma de lista. Una definición de alcance es la forma esperada; vale cualquier lista de capacidades descriptibles por separado. - **Los requisitos no funcionales** — las restricciones medidas que el diseño debe satisfacer, cada una con su métrica y la condición bajo la que se sostiene. - **Una persona con nombre que decida** — quien puede aceptar una decisión de arquitectura y las alternativas que descarta. Sin ella, la sección de decisiones es una sugerencia. Si falta el alcance, detente y repórtalo. Nunca deduzcas el alcance de un sistema existente: un sistema en marcha registra lo que se construyó y lo que se abandonó a medias, y nada de eso es un requisito. ## Entradas opcionales - Acceso al sistema existente: repositorios, esquemas, configuración, documentación de operación - El entorno de ejecución y sus restricciones: reglas de aislamiento, regiones, fronteras de red, modelo de alojamiento - Las convenciones que el equipo ya sigue y los sistemas que ya opera - Puntos de integración fuera de la frontera y quién es dueño de cada uno - Obligaciones de cumplimiento, residencia o retención que apliquen a los datos - Documentos de arquitectura anteriores del mismo sistema y qué ha cambiado desde entonces Cada entrada opcional que falte pasa a **Preguntas abiertas**. Nunca se convierte en una conjetura. Cuando no se aportó el entorno de ejecución, la forma de despliegue se describe en unidades de ejecución y su ubicación se registra como `desconocida`. ## Ejecución **1 — Fijar la frontera.** Nombra el sistema, qué queda dentro y qué queda fuera. Lista cada actor externo — personas, sistemas, procesos programados — y qué quiere cada uno del sistema. Lo que no se pueda colocar a un lado es una pregunta de frontera, y se registra como tal en lugar de decidirse en silencio. **2 — Derivar los componentes de las capacidades.** Por cada capacidad del alcance, nombra el componente que la posee. Da a cada componente una frase de lo que posee y otra de lo que explícitamente no posee. Dos componentes que poseen lo mismo son uno solo con el nombre sin resolver; un componente que no posee nada se elimina. **3 — Definir las interfaces.** Para cada par de componentes que deban comunicarse: la dirección, qué se intercambia, si la llamada es síncrona o asíncrona y qué hace quien llama cuando el otro lado no está disponible. Aquí las interfaces se nombran y se acotan; **Diseño de contratos de API** las especifica campo a campo. **4 — Nombrar los datos que cruzan cada frontera.** Por cada interfaz y cada actor externo: qué datos cruzan, su clasificación, quién es su dueño y cuánto tiempo pueden conservarse. Un dato cuya clasificación no se aportó se registra como `desconocida` y se eleva como pregunta; esta habilidad nunca le asigna una clasificación. **5 — Dar forma al despliegue.** Las unidades de ejecución, cuántas de cada una, qué estado guarda cada una, cómo se alcanza cada una y dónde están las fronteras de fallo. Constrúyelo solo desde el entorno declarado. Si no se declaró ninguno, describe las unidades y sus relaciones y marca su ubicación como `desconocida`. **6 — Registrar las decisiones.** Por cada elección cara de revertir: qué se decidió, qué la forzó, las alternativas consideradas y por qué se descartó cada una, y la condición que la revertiría. Una decisión sin alternativa descartada no fue una decisión; fue la primera idea, y se registra como tal. **7 — Trazar y podar.** Cada componente debe trazarse hasta una capacidad o hasta un requisito no funcional. El que no se trace a nada se marca en la sección de trazabilidad, no se mantiene en el diagrama. Cada capacidad debe alcanzar al menos un componente; la que no alcance ninguno es un hueco y se eleva como bloqueante. ## Salida `architecture-specification.md`, en este orden: - **1. Entrada y fecha** — de qué alcance y de qué conjunto de requisitos parte esta especificación, quién aportó cada uno y cuándo - **2. Contexto del sistema** — el sistema, sus actores externos y qué intercambia cada uno con él - **3. Componentes** — por componente: nombre, qué posee, qué explícitamente no posee y con qué se traza - **4. Interfaces** — por interfaz: los dos lados, la dirección, qué se intercambia, síncrona o asíncrona, y el comportamiento cuando el otro lado no está disponible - **5. Datos que cruzan fronteras** — por frontera: los datos, su clasificación, su dueño y su retención - **6. Forma de despliegue** — unidades de ejecución, su multiplicidad, el estado que guarda cada una, cómo se alcanza cada una y las fronteras de fallo - **7. Decisiones de arquitectura** — la decisión, qué la forzó, las alternativas descartadas y por qué, y qué la revertiría - **8. Trazabilidad** — de componente a requisito y de requisito a componente, con las entradas sin pareja listadas en ambos lados - **9. Preguntas abiertas** — la pregunta, qué bloquea, quién puede responderla ## Validación La especificación está lista cuando se cumple todo esto: - Cada componente de la sección 3 se traza hasta una capacidad o un requisito en la sección 8, o allí se marca que no se traza a nada - Cada capacidad del alcance de entrada alcanza al menos un componente - Cada interfaz de la sección 4 declara qué hace quien llama cuando el otro lado no está disponible - Cada decisión de la sección 7 nombra al menos una alternativa descartada y el motivo del descarte - Cada elemento de la sección 5 lleva una clasificación o el literal `desconocida` - La sección 9 no está vacía, o declara explícitamente que no queda nada pendiente Falla la ejecución si un componente no se traza a nada y no está marcado, o si se registra una decisión sin ninguna alternativa considerada. ## Gestión de fallos - **No hay alcance** — detente. Informa de que la especificación no tiene capacidades que asignar y de que una lista de componentes montada sin ellas describe una preferencia, no un sistema. - **No hay requisitos no funcionales** — produce las secciones 1 a 5 y 7 a 9, marca la sección 6 como `SIN RESTRICCIONES` y declara que una forma de despliegue que no se apoya en ningún requisito declarado de carga, disponibilidad o latencia no puede usarse para dimensionar nada. - **Sin acceso al sistema existente** — construye las secciones 2 y 3 solo con el material reportado, marca cada elemento como `reportado` y declara con claridad que no se verificó nada contra un sistema en marcha. - **Entradas contradictorias** — registra las dos, nombra ambas fuentes y eleva la contradicción a la sección 9 como bloqueante. No la resuelvas eligiendo. - **Material parcial** — produce cada sección que el material sostenga, marca el resto como `INCOMPLETO — pendiente de ` y entrega. Una especificación honesta sobre sus huecos se puede revisar; una que parece completa porque los rellenó, no.