Why Archkeep
Architecture rarely fails all at once. It erodes.
A team agrees on layers, ownership and dependency boundaries. Then the repository changes: a convenient import crosses a boundary, a temporary exception becomes permanent, documentation drifts from reality, and coding agents make the same problem scale faster.
The build can still pass. Tests can still pass. A linter can still report clean.
The missing question is:
Does the code still conform to the architecture we chose?
Archkeep turns that question into a machine-checkable contract.
The core idea
ARCHITECTURE INTENT
↓
OBSERVED REALITY
↓
DETERMINISTIC EVIDENCE
↓
AUTHORITATIVE VERDICT
You declare the boundaries and dependency rules that matter. Archkeep statically observes the repository, builds the relevant graph and evidence, compares reality with intent, and returns a deterministic verdict.
The same authority can be used by humans, CI and coding agents.
Why it is different
| Tool | Answers |
|---|
| Compiler | Does it build? |
| Tests | Does it behave? |
| Linter | Does the code follow language/style rules? |
| Dependency tooling | How is the code connected? |
| AI code review | Does a model think this change looks reasonable? |
| Archkeep | Does the code conform to the architecture we chose? |
Archkeep does not replace these tools. It owns the architectural boundary between them.
How it fits agentic development
Human declares architecture
↓
Coding agent
reads architecture context
↓
changes code
↓
Archkeep check
↓
deterministic verdict
↓
CI
Agents may inspect, explain and propose. They do not redefine the architecture when their changes disagree with it.
Core capabilities
- Architecture enforcement — dependency and boundary rules across polyglot repositories.
- Deterministic evidence — 24 commands with versioned, byte-stable JSON; reproducible verdicts with coverage and provenance.
- Governance — waivers, ADRs, fitness functions and explicit decisions.
- Architecture evolution — drift, change impact, history, health and debt.
- Agent integration — CLI, MCP, VS Code and architecture-aware agent skills.
Polyglot by design
Archkeep evaluates architecture across Go, Rust, Python, TypeScript/JavaScript, Vue, Java/Kotlin and C# repositories, while integrating with workspace systems such as Nx and Moon or discovering projects natively.
The goal is one architectural policy across language boundaries, not one enforcement mechanism per language.
Quick start
pnpm add -D @ecoma-io/archkeep
Register Archkeep with Nx, use the native archkeep.json workspace discovery, or configure the integration appropriate for your repository.
Then run:
pnpm exec archkeep check
For an existing repository, start with discovery:
pnpm exec archkeep discover
Node.js ≥ 22 is required. No language toolchain is required for static analysis.
→ Getting started
A small example
Declare a rule such as:
export const depConstraints = [
{
sourceTag: "layer:domain",
onlyDependOnLibsWithTags: ["layer:domain"],
description: "The domain outlives frameworks, queues and databases.",
},
];
If a domain project imports infrastructure:
libs/pricing/src/discount.go:14:2 onlyTagsConstraintViolation
A project tagged with "layer:domain" can only depend on libs tagged with layer:domain
import "github.com/acme/mq-client/publish" (static) pricing → mq-client
constraint sourceTag layer:domain → onlyDependOnLibsWithTags [layer:domain]
rule The domain outlives frameworks, queues and databases.
The important part is not only that the check fails. The verdict carries the evidence and points back to the architectural rule that caused it.
Used in the Ecoma ecosystem
Archkeep is dogfooded by:
Documentation
Contributing
The most valuable contribution is a missed violation: a real architectural boundary that Archkeep failed to detect.
See CONTRIBUTING.md, Code of Conduct and SECURITY.md.
License
Apache License 2.0
