Live architecture

Every project can have an architecture: the system’s pieces (database, API, frontend, email, payments, queues, external services…) and their connections. It’s stored as data, not as a drawing: the project’s Architecture tab lays it out automatically, and you can also export it to Mermaid for a README.

Only the project team can see it, not its clients, because it includes internal addresses.

Create it

The fastest way is to ask your agent, using the fxc-scan skill. You can also import a JSON file by hand:

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" }
  ]
}

Field	Notes
key	Required, and stable across imports: that’s how positions and linked tasks are preserved
kind	frontend, api, database, cache, queue, storage, email, payments, auth, cdn, worker, external or other
name	Required
provider, environment, url, host, notes	Optional. Never credentials: a URL with a username or password is rejected
tasks	Ids of tasks to link. If omitted, the piece keeps the links it already has

Importing replaces the architecture: pieces missing from the file are deleted and connections are rebuilt.

See it live

A piece lights up for three reasons, from strongest to weakest:

1. A linked task in progress. A task linked to the piece (fxc arch link <tarea> <pieza>) is in a status with the progress animation: the piece gets a sweep in that status’s color.
2. An agent’s focus. The agent announces it’s working there (fxc arch focus <pieza> --task <tarea>, or focus_pieces over MCP). The piece shows “Agent working here” and turns off on its own after 10 minutes, or with fxc arch unfocus.
3. Inferred from the name (beta). A task in progress mentions the piece (“review the Stripe webhooks”) even though nobody linked it. It’s drawn dotted, and you can turn it off from the diagram.

Everything updates live, no page reload needed. When the agent wraps up with fxc tasks finish on its branch, the task moves to review and its pieces stop sweeping (see Branches and PRs).

Scan indicator

While the fxc-scan skill reads a repository to deduce its architecture, the Architecture page shows “Scanning the repository…” with a subtle animation over the diagram (or over the empty state if there is no diagram yet) and who started the scan. The projects list shows a small Scanning badge on that project.

fxc arch scan start --project-id <id> --label acme/shop   # the skill calls it when it starts
fxc arch import architecture.json --project-id <id>       # success: the import ends the scan by itself
fxc arch scan end --project-id <id> --failed              # only if the scan could not finish

When it ends, the page refreshes by itself with the new diagram. The scan lives in memory and expires by itself after 10 minutes: if the agent is cut off halfway, the notice disappears without anyone closing it (calling scan start again renews it). Over MCP: start_architecture_scan and end_architecture_scan.

Commands

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 <text>]
fxc arch scan end --project-id <id> [--failed]