convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
bacharSalleh

Archik: Arquitetura como Código em YAML

bacharSalleh/archik

Arquitetura-como-código legível por IA com validação e rastreabilidade

Ver no GitHub
BomPluginScore · de 0 a 100

MCP 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/archik

1 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

Estrelas
12
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 1 mês
Versão
v0.22.2
Issues abertas
12
Contribuidores
3

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 dev opens 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, sourcePath existence, use-case/actor/seq integrity, ECB rules
  • 🔍 Traceability — archik trace proves which use case slices are tested and realized; --fail-on gates CI
  • 🌿 Git-aware — archik diff origin/main shows what a branch changes architecturally; archik affected maps changed files to nodes, slices, and tests (--run executes them); archik hooks install gates every commit
  • 🤝 Team-ready — semantic merge driver for YAML, node ownership with CODEOWNERS sync, and governance constraints (architecture fitness rules)
  • 🔬 Verified at every altitude — validate proves the model is consistent, drift --edges proves it matches the code's import graph, otel check proves it matches production traffic
  • 🧬 Self-evolving — opt-in archik evolution loop (observe → reflect → propose → validate → apply → measure) learns from your accepts, rejects, and failures and proposes its own upgrades behind a human approval gate; archik patterns ships the same design patterns for your systems
  • 🚀 Fast adoption — archik import compose / import mermaid bootstrap a diagram from what you already have; /archik:spawn mirrors 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 typeYou 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:

LayerFileCaptures
Structure.archik/main.archik.yamlServices, databases, queues, agents, LLMs, edges
Actors*.archik.actors.yamlWho initiates use cases
Requirements.archik/usecases/*.archik.uc.yamlFlows + slices that name test paths
Behaviour*.archik.seq.yamlUML-subset sequence diagrams
Progress*.archik.alphas.yamlEssence/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.

CommandWhat it does
archik initScaffold + install the Claude skill and slash commands
archik dev / start / stop / statusLive 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 watchRe-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 affectedChanged files → nodes, slices, tests to run (--since <ref>, --files, --run to execute them)
archik traceCoverage matrix (--fail-on partial|none for CI)
archik driftsourcePath / 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 --installSemantic git merge for *.archik.yaml
archik hooks installPre-commit hook running archik validate (--with-drift optional)
archik owners sync|checkKeep CODEOWNERS in step with node owners
archik mcpMCP server over stdio (tools + resources + prompts) for non-Claude-Code agents
archik schema [seq|uc|actors]Print the document schemas
archik upgradeUpgrade + 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.

archikMermaid / PlantUMLStructurizr
Source formatPlain YAMLCustom DSLStructurizr DSL
AI-editor integrationSkill + MCPNoneNone
Use cases / test traceabilityMechanicalNoNo
Drift detectionYesNoNo
Governance constraintsYesNoNo
ValidatorSchema + cross-file + ECBSyntax onlySyntax 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

Ver o original no GitHub

Bom para

Relacionados