- What is Evolith?
- Why Evolith?
- Core Concepts
- Product Ecosystem
- How It Works
- Architecture Overview
- Main Components
- Quick Start
- Documentation
- Use Cases
- Roadmap
- Contributing
- License
Evolith is an executable architectural governance framework. It encodes how software is built — across multiple architecture styles — as verifiable rules, ADRs, and phase gates that teams, platforms, and AI agents can actually run.
Governance in Evolith is not a document. It is an operational capability exposed through a CLI, an MCP server, and a REST API.
Most projects accumulate ADRs and architecture docs that nobody reads and nobody enforces. Systems drift. Decisions are forgotten. Consistency breaks silently.
Evolith makes governance executable:
- Rules are validated automatically, not reviewed manually.
- Phase gates block progression until quality criteria are met.
- AI agents and CI pipelines consume the same governance artifacts as humans.
- Architecture decisions are traceable from ADR to production code.
| Concept | What it is |
|---|---|
| SDLC Phases | The five stages from idea to production: Discovery → Design → Construction → QA → Delivery |
| Gates | Automated checkpoints that close each phase before the next begins |
| Topologies | Architecture styles (e.g., modular monolith, microservices, event-driven, agentic-AI) |
| ADRs | Architecture Decision Records — the authoritative log of architectural choices |
| Blueprints | Canonical design templates for each topology |
| Rulesets | Machine-readable rules enforced by the CLI and Core API |
| OPA Policies | Open Policy Agent policies for fine-grained governance checks |
| Artifacts | Structured outputs at each phase: specs, schemas, manifests, contracts |
| AI Agents | Specialized agents (Winston and others) that participate in the SDLC as first-class contributors |
Full details: Core Concepts · Topologies
Evolith ships as a suite of coordinated products built on a common foundation.
| Product | Role |
|---|---|
| Evolith Core | Provider-neutral constitution: principles, ADRs, rulesets, topologies, and contracts |
| Smart CLI | Local enforcement — validate code, run gates, manage ADRs, serve MCP |
| Core API | REST service for remote governance queries and evaluation |
| MCP Services | Governance as live context for LLMs and AI agents (27 tools, 9 resources, 8 prompts) |
| Evolith Tracker | Business lifecycle governance — phases, owners, funding, and ROI |
| Rulesets | Machine-readable enforcement rules per topology |
| OPA Policies | Fine-grained policy checks integrated into the pipeline |
| Schemas & Manifests | Structured contracts for artifacts and topology definitions |
Developer / AI Agent
│
▼
Smart CLI ──────────────────────────────► MCP Server
(local enforcement) (AI agent context)
│
▼
Core API ────────────────────────────► Evolith Tracker
(remote governance) (business lifecycle)
│
▼
Rulesets · OPA Policies · ADRs · Blueprints
(the shared governance artifacts)
- Smart CLI validates code locally against rulesets and runs phase gates.
- Core API exposes the same governance remotely for CI pipelines and orchestrators.
- MCP Server feeds governance context to LLMs and AI agents in real time.
- Evolith Tracker coordinates the business side — who owns what, what's funded, what ships when.
All products share the same artifacts defined in Evolith Core.
Evolith governs 8 topologies across four axes:
| Axis | Topologies |
|---|---|
| Progressive | modular-monolith · distributed-modules · microservices |
| Integration | event-driven |
| Execution | serverless · edge-computing |
| Data | data-mesh |
| AI | agentic-ai |
Each topology has its own ADRs, OPA policies, AI rulesets, and UMS contracts. Systems migrate between topologies as the business scales — this is Progressive Architecture.
Full reference: Architecture hub
evolith/
├── reference/core/ # Engineering constitution and principles
├── reference/architecture/ # Topologies, blueprints, and ADRs
├── reference/governance/ # SDLC phases, gates, standards, and glossary
├── reference/products/ # Smart CLI, Core API, MCP, Tracker, UMS
└── reference/operations/ # SRE, infra, quality gates
Entry point for each area: Global Master Index
# Install Smart CLI
npx @evolith/smart-cli@1.1.4 init
# Validate your code against your topology's rulesets
smart-cli validate
# Validate a specific SDLC phase
smart-cli validate --phase qa
# Manage Architecture Decision Records
smart-cli adr create
smart-cli adr list
# Serve governance as live context for AI agents
smart-cli mcp serveSmart CLI ships 20 commands and is configured via evolith.yaml. Full reference: Smart CLI hub
| Area | Link |
|---|---|
| Core constitution | Evolith Core hub |
| SDLC governance | SDLC Governance Center |
| Topologies | Topologies hub |
| Smart CLI | Smart CLI hub |
| Core API | Core API hub |
| MCP Services | MCP Services hub |
| Evolith Tracker | Tracker hub |
| Operations & SRE | Operations hub |
| Onboarding by role | Getting Started by Role |
| Ecosystem glossary | Glossary |
| Gap tracking | Gap Tracking Board |
| All artifacts | Global Master Index |
For engineering teams Enforce architecture decisions automatically. Run phase gates in CI. Keep ADRs alive and traceable.
For platform teams Query governance remotely via Core API. Integrate rulesets into deployment pipelines. Block non-compliant artifacts before they reach production.
For AI-assisted development Feed governance context to LLMs through MCP. Let AI agents validate their own outputs against architecture rulesets before committing.
For growing products Start with a modular monolith. Migrate to distributed modules or microservices when the business demands it — Evolith tracks the transition and enforces consistency at every step.
See the active gap tracking board for current priorities and open items:
Read these before opening a PR:
- Contributing Guide
- Security Policy
- AGENTS.md — conventions for AI agent contributors
- Repository Taxonomy — what goes where
Published under the MIT License.