Arquitectura en vivo

Cada proyecto puede tener su arquitectura: las piezas del sistema (base de datos, API, frontend, email, pagos, colas, servicios externos…) y sus conexiones. Se guarda como datos, no como dibujo: la pestaña Arquitectura del proyecto la dibuja ordenada sola, y también se exporta a Mermaid para un README.

Solo la ve el equipo del proyecto, no sus clientes, porque incluye direcciones internas.

Crearla

Lo más rápido es pedírselo a tu agente con el skill fxc-scan. También se importa un JSON a mano:

fxc arch import arquitectura.json --project-id <id>

{
  "nodes": [
    { "key": "web", "kind": "frontend", "name": "Tienda web", "provider": "Next.js", "url": "https://tienda.example.com" },
    { "key": "api", "kind": "api", "name": "API", "provider": "Fastify" },
    { "key": "db", "kind": "database", "name": "PostgreSQL", "provider": "RDS" },
    { "key": "stripe", "kind": "payments", "name": "Pagos", "provider": "Stripe" }
  ],
  "edges": [
    { "from": "web", "to": "api", "protocol": "https" },
    { "from": "api", "to": "db", "protocol": "sql" },
    { "from": "stripe", "to": "api", "label": "webhooks" }
  ]
}

Campo	Notas
key	Obligatorio y estable entre importaciones: así se conservan posiciones y tareas enlazadas
kind	frontend, api, database, cache, queue, storage, email, payments, auth, cdn, worker, external u other
name	Obligatorio
provider, environment, url, host, notes	Opcionales. Nunca credenciales: una URL con usuario o contraseña se rechaza
tasks	Ids de tareas a enlazar. Si se omite, se conservan los enlaces que ya tenga la pieza

Importar reemplaza la arquitectura: las piezas que no vengan se borran y las conexiones se rehacen.

Verla en vivo

Una pieza se ilumina por tres motivos, de más a menos fuerte:

1. Tarea enlazada en marcha. Una tarea enlazada a la pieza (fxc arch link <tarea> <pieza>) está en un estado con animación de progreso: la pieza se barre con el color de ese estado.
2. Foco de un agente. El agente avisa que está trabajando ahí (fxc arch focus <pieza> --task <tarea>, o focus_pieces por MCP). Muestra «Agente trabajando aquí» y se apaga solo a los 10 minutos, o con fxc arch unfocus.
3. Deducción por nombre (beta). Una tarea en marcha nombra la pieza («revisar los webhooks de Stripe») aunque nadie la haya enlazado. Se ve punteada y se puede apagar desde el diagrama.

Todo llega en vivo, sin recargar la página. Cuando el agente termina con fxc tasks finish en su rama, la tarea pasa a revisión y sus piezas dejan de barrerse (ver Ramas y PR).

Indicador de escaneo

Mientras el skill fxc-scan lee un repositorio para deducir su arquitectura, la página de Arquitectura muestra «Escaneando el repositorio…» con una animación sutil sobre el diagrama (o sobre el estado vacío si aún no hay diagrama) y quién lanzó el escaneo. La lista de proyectos muestra una pequeña etiqueta Escaneando en ese proyecto.

fxc arch scan start --project-id <id> --label acme/tienda   # el skill lo llama al empezar
fxc arch import arquitectura.json --project-id <id>         # éxito: importar cierra el escaneo solo
fxc arch scan end --project-id <id> --failed                # solo si el escaneo no pudo terminar

Al terminar, la página se refresca sola con el diagrama nuevo. El escaneo vive en memoria y caduca solo a los 10 minutos: si el agente se corta a medias, el aviso desaparece sin que nadie lo cierre (volver a llamar a scan start lo renueva). Por MCP: start_architecture_scan y end_architecture_scan.

Comandos

fxc arch get --project-id <id>
fxc arch mermaid --project-id <id>
fxc arch link <tareaId> stripe --project-id <id>
fxc arch focus stripe api --task <tareaId> --minutes 15 --project-id <id>
fxc arch unfocus --all --project-id <id>
fxc arch scan start --project-id <id> [--label <texto>]
fxc arch scan end --project-id <id> [--failed]