Archik: Arquitetura como Código em YAML
bacharSalleh/archik
Arquitetura-como-código legível por IA com validação e rastreabilidade
Ver no GitHubMCP server que torna arquitetura de sistemas em YAML puro, fornecendo um mapa estrutural que agentes IA (Claude, Cursor, Windsurf) podem ler nativamente. Inclui validação automática, canvas interativo, rastreabilidade de casos de uso até testes, e detecção de drift entre diagrama e código.
Instalação
npx convez-ai bacharSalleh/archik1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter arquitetura sincronizada com código via validação em CI/CD
- Fornecer mapa estrutural para agentes IA raciocinar sobre sistema
- Rastrear cobertura de testes desde caso de uso até implementação
- Detectar drift entre diagrama e grafo de importações do código
Veredito

Ferramenta madura e opinionada para times que querem arquitetura como artefato vivo, legível por máquinas e humanos. Integração MCP nativa com Claude torna-a particularmente útil para fluxos IA-assistidos, mas curva de aprendizado é significativa.
README
A tradução para o português deste README ainda está na fila.
What is archik?
Your architecture lives in plain YAML. A CLI is the only way to edit it, a validator rejects every drift before merge, and a live canvas renders it in the browser. AI agents (Claude Code, or anything that speaks MCP) read the same YAML as their map of your system — so they reason about structure instead of guessing from filenames.
One chain runs from a stakeholder request all the way to a passing test, and every link is mechanically checked:
Actor → Use case → Slice → Tests on disk → Seq diagram → Nodes → Source code on disk
Features
- 📐 Plain-YAML diagrams — no DSL, no coordinates; layout is computed by ELK on every render, so diffs stay meaningful
- 🖥️ Live canvas —
archik devopens a browser canvas that reloads on every file change; headless SVG render for docs and CI - 🤖 AI-native — installable Claude Code skill + 12 slash commands, and an MCP server for Cursor, Windsurf, Copilot, Claude Desktop, Zed
- ✅ Validator, not convention — schema, cross-file references,
sourcePathexistence, use-case/actor/seq integrity, ECB rules - 🔍 Traceability —
archik traceproves which use case slices are tested and realized;--fail-ongates CI - 🌿 Git-aware —
archik diff origin/mainshows what a branch changes architecturally;archik affectedmaps changed files to nodes, slices, and tests (--runexecutes them);archik hooks installgates every commit - 🤝 Team-ready — semantic merge driver for YAML, node ownership with CODEOWNERS sync, and governance constraints (architecture fitness rules)
- 🔬 Verified at every altitude —
validateproves the model is consistent,drift --edgesproves it matches the code's import graph,otel checkproves it matches production traffic - 🧬 Self-evolving — opt-in
archik evolutionloop (observe → reflect → propose → validate → apply → measure) learns from your accepts, rejects, and failures and proposes its own upgrades behind a human approval gate;archik patternsships the same design patterns for your systems - 🚀 Fast adoption —
archik import compose/import mermaidbootstrap a diagram from what you already have;/archik:spawnmirrors an existing source tree - 📦 Zero runtime dependencies in the published package
Installation
Requires Node.js ≥ 20.
npx archik@latest init # scaffolds .archik/main.archik.yaml
# + installs the Claude skill and /archik:* commands
Or as a Claude Code plugin:
/plugin marketplace add bacharSalleh/archik
/plugin install archik@archik
Both paths install the same skill and slash commands. The plugin still uses the archik npm binary, so Node is needed either way.
Quick start
npx archik init # 1. scaffold
npx archik start # 2. open the live canvas (http://localhost:5173)
Then, in Claude Code:
/archik:bootstrap # 3. always your first message — detects project
# state and routes to the right next step
Day-to-day:
| You type | You get |
|---|---|
/archik:suggest <feature> | A staged diagram change, shown as a green/red diff overlay on the canvas — accept or reject |
/archik:usecase <name> | A use case with flows, slices, and test paths |
/archik:trace | "Are we done?" — the coverage matrix |
Already have docker-compose or Mermaid diagrams? Skip the blank canvas:
npx archik import compose --out .archik/main.archik.yaml
npx archik import mermaid docs/architecture.mmd --out .archik/main.archik.yaml
Compose services become nodes (postgres → database, redis → cache, kafka → stream, …), build contexts become sourcePaths, and depends_on becomes edges. The Mermaid importer parses the flowchart subset: shaped nodes map to kinds, subgraphs become module parents, arrows become labelled edges.
The YAML
version: "1.0"
name: Support Hub
nodes:
- id: api
kind: service
name: Support API
sourcePath: src/api # must exist on disk — validator-enforced
description: REST API serving the customer support frontend.
owner: team-support # optional — who to talk to
- id: claude
kind: llm
name: Claude
description: LLM backend for draft generation.
edges:
- id: api-claude
from: api
to: claude
relationship: invokes
One file per layer, every link cross-checked by the validator:
| Layer | File | Captures |
|---|---|---|
| Structure | .archik/main.archik.yaml | Services, databases, queues, agents, LLMs, edges |
| Actors | *.archik.actors.yaml | Who initiates use cases |
| Requirements | .archik/usecases/*.archik.uc.yaml | Flows + slices that name test paths |
| Behaviour | *.archik.seq.yaml | UML-subset sequence diagrams |
| Progress | *.archik.alphas.yaml | Essence/SEMAT alphas, machine-verified |
Full schema: npx archik schema (also schema seq | uc | actors).
Everyday workflow
# What am I touching on this branch? Which tests cover it?
npx archik affected --since main
# …and run exactly those tests (vitest/jest/playwright/mocha auto-detected)
npx archik affected --since main --run
# What does this branch change architecturally?
npx archik diff origin/main # add --out diff.svg for the visual
# Is the diagram still telling the truth?
npx archik validate && npx archik drift
# Do the EDGES match the code? (TS/JS import-graph verification)
npx archik drift --edges # shadow + phantom edge detection
# Are we done?
npx archik trace
affected walks the chain backwards: changed files → nodes (via sourcePath) → use case slices (via tests and sequence-diagram participants) → tests to run — and flags changed files no node or test claims.
drift --edges scans the imports under every node's sourcePath and reports shadow edges (code imports across nodes with no declared edge) and phantom edges (structural edges with no import in either direction). Gate every commit locally with:
npx archik hooks install # pre-commit: archik validate
AI integration
Claude Code (deepest integration): archik init installs a skill that enforces one hard rule — Claude talks to archik only through the CLI, never by editing YAML directly. Reads go through archik q, writes through archik suggest set, and you approve every structural change on the canvas.
Everything else (MCP): archik mcp runs a stdio Model Context Protocol server exposing the same contract — 20 tools covering schema, queries, trace, validate, drift, affected, and the suggestion lifecycle, plus resources (archik://schema, archik://stats, archik://trace, archik://validate, archik://drift) and prompts (propose-change, review-architecture) that encode the same working loop the Claude Code skill teaches:
// .cursor/mcp.json, claude_desktop_config.json, etc.
{
"mcpServers": {
"archik": { "command": "npx", "args": ["archik", "mcp"] }
}
}
Team workflow
Semantic merges. Stop resolving line-based YAML conflicts — nodes and edges are id-keyed, so most merges are mechanical:
npx archik merge-driver --install # once per clone; .gitattributes line is committed
Both branches added nodes → keep both. One side changed a field → take it. Same field changed differently, or modify-vs-delete → a real conflict, reported precisely.
Ownership. owner: team-billing on a node answers "who do I talk to": archik q describe payments-db, archik q list --owner team-billing. And archik owners sync writes one CODEOWNERS rule per owned node into a managed block (hand-authored rules untouched), with archik owners check as the CI gate so review routing can't drift from the model.
Governance constraints. Architecture fitness rules, enforced by archik validate on every run:
constraints:
- id: billing-isolation
description: Only billing-context nodes may write to billing-db.
forbidEdge:
relationship: writes
from: { notParent: billing }
to: { id: billing-db }
- id: services-owned
description: Every service and worker declares an owning team.
requireOwner: { kinds: [service, worker] }
Intentional exceptions are grandfathered by id in an except list — visible in review, never silent.
Verified against production
Map nodes to your tracing backend's service names (metadata.otelService, node id as the fallback), export the service-dependency graph, and let archik compare:
curl -s "http://jaeger:16686/api/dependencies?endTs=$(date +%s)000&lookback=86400000" > deps.json
npx archik otel check --graph deps.json
Undeclared production calls — traffic the diagram doesn't admit to — fail the check; declared wire edges that saw no traffic are reported informationally. That completes the truth chain: validate proves the model is consistent, drift --edges proves it matches the code, otel check proves it matches production.
Self-evolution
Archik can learn from how you use it. Everything is opt-in, local-only, and human-gated:
archik evolution enable # start observing (events stay on your machine)
# ... normal work: suggestions accepted/rejected, validate/drift runs ...
archik evolution reflect # recurring friction → pending proposals with evidence
archik evolution proposals # read them
archik evolution approve <id># apply: a learned.md note, or a sidecar diff you still review
archik evolution report # did it help? last 7 days vs the 7 before
Approved lessons land in .archik/evolution/learned.md — the Claude skill reads it at session start (and MCP agents via archik://learned), so the AI gets smarter across sessions without anyone editing prompts. Rejecting a proposal is recorded too; the loop learns from "no".
Building a self-evolving system of your own? The same patterns ship as a library:
archik patterns list # evolution-loop, sidecar-approval-gate,
archik patterns show evolution-loop # learned-overlay, truth-chain, feedback-pipeline
archik patterns apply evolution-loop # stage the blueprint into YOUR diagram (gated)
Deep dives in docs/advanced-topics. In Claude Code: /archik:self-evolving <your idea>.
CI
Plain commands:
archik validate # schema + cross-file integrity + constraints
archik drift # diagram vs source tree
archik trace --fail-on partial # block merge on incomplete traceability
archik render --theme light --out docs/architecture.svg
Or the GitHub Action, which runs all three and posts a sticky PR comment with the architecture diff vs the base branch:
# .github/workflows/archik.yml
name: archik
on: [pull_request]
permissions:
contents: read
pull-requests: write
jobs:
archik:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: bacharSalleh/archik@main
with:
trace-fail-on: partial # optional gate; omit for report-only
Inputs: path, working-directory, validate, drift, trace-fail-on, compare-ref, comment, github-token, version.
CLI reference
Every command supports --help; agent-facing commands support --json.
| Command | What it does |
|---|---|
archik init | Scaffold + install the Claude skill and slash commands |
archik dev / start / stop / status | Live canvas lifecycle (foreground / detached) |
archik validate [path] | Schema + cross-file + constraints (exit 1 on error) |
archik render --out <svg> | Headless SVG render (--seq <path> for sequence diagrams) |
archik watch | Re-render SVG on every change |
archik q <sub> | Query: describe deps dependents impact list edges stats usecases describe-usecase actors sequences |
archik diff <a> [b] | Diff two files or git refs; one arg = that ref vs working tree |
archik affected | Changed files → nodes, slices, tests to run (--since <ref>, --files, --run to execute them) |
archik trace | Coverage matrix (--fail-on partial|none for CI) |
archik drift | sourcePath / test-path gaps vs the source tree (--edges verifies edges vs the TS/JS import graph) |
archik otel check --graph <f> | Verify edges against a production service-dependency graph |
archik suggest <sub> | Suggestion sidecar lifecycle: show set accept reject |
archik alpha <sub> | Essence alphas: show, promote (machine-checked), demote |
archik evolution <sub> | Self-evolution loop: enable status reflect proposals propose approve reject report |
archik patterns <sub> | Self-evolution pattern library: list show <id> apply <id> |
archik import compose|mermaid [file] | Bootstrap a document from docker-compose or a Mermaid flowchart |
archik merge-driver --install | Semantic git merge for *.archik.yaml |
archik hooks install | Pre-commit hook running archik validate (--with-drift optional) |
archik owners sync|check | Keep CODEOWNERS in step with node owners |
archik mcp | MCP server over stdio (tools + resources + prompts) for non-Claude-Code agents |
archik schema [seq|uc|actors] | Print the document schemas |
archik upgrade | Upgrade + refresh installed skill/commands |
Default file resolution: .archik/main.archik.yaml, falling back to the legacy architecture.archik.yaml (both present = error).
When to use it (and when not to)
Use archik when your project has more than ~5 components, you ship with an AI agent and want it to reason about structure, you want "are we done?" to be mechanically answerable, or you want CI to fail on architectural drift.
Skip it when it's a one-file script, the diagram is for a slide deck (use Mermaid), or you have no build step or CI.
| archik | Mermaid / PlantUML | Structurizr | |
|---|---|---|---|
| Source format | Plain YAML | Custom DSL | Structurizr DSL |
| AI-editor integration | Skill + MCP | None | None |
| Use cases / test traceability | Mechanical | No | No |
| Drift detection | Yes | No | No |
| Governance constraints | Yes | No | No |
| Validator | Schema + cross-file + ECB | Syntax only | Syntax only |
Contributing
See CONTRIBUTING.md. Development:
npm install
npm run archik -- --help # run the CLI from source
npm test # vitest
npm run typecheck
License
MIT © Bashar