Bilingual Navigation: Versión en Español
↑ Evolith E2E Product Vision · MD3 — click to enlarge
Evolith Core is not a documentation corpus. It is an executable governance framework —
a topology-agnostic, runtime-neutral technical standard that dictates how software is built,
distributed through CLI, MCP, and Service CORE API interfaces, and enforced by verifiable rulesets.
Progressive Architecture: the framework's ability to scale systems by mutating between topologies according to the business lifecycle, preventing over-engineering and guaranteeing architectural coherence through automated execution.
Evolith Core exists to become the definitive enterprise-grade operating system for software architecture governance: global, stack-agnostic, topology-aware, and executable by humans, delivery platforms, and AI agents. It defines the technical constitution that every product, satellite repository, and orchestration system can inherit without being coupled to a language, cloud provider, runtime, database engine, or product-specific commercial model.
Its mission is to turn architectural governance into an operational capability. ADRs, rulesets, policies, contracts, reference implementations, and AI instructions are not passive documents; they are authoritative technical artifacts exposed through mandatory execution channels so teams can validate, query, scaffold, and enforce the selected architecture before code reaches production.
Evolith Core is a multi-topology reference corpus and executable governance framework for modern B2B engineering organizations. It no longer governs only the path from simple monoliths to microservices. It governs the deliberate mutation of systems across modular monoliths, distributed services, Cloud-Native Serverless, Event-Driven, Data Mesh, Edge Computing, and Agentic / AI-First Architectures when product maturity, operational complexity, and platform economics justify the shift.
In Evolith, "progressive" means the capacity of the framework to scale systems by mutating between topologies according to the lifecycle of the business, preventing over-design and preserving architectural coherence through automatic execution. The framework defines the technical What and How; business timing, ownership, funding, ROI, and prioritization remain outside Core and are governed by Evolith Tracker through its ACL and Funnel 0.
Evolith Core governs through a multi-topology reference corpus. Each topology is a fully isolated bounded context with its own ADRs, OPA policies, AI rulesets, and UMS contracts. The repository flows from the most general surface to the most specific artifact, across three domains:
| Level | Surface | Use it to |
|---|---|---|
| 1. Portal | This README | Choose a domain or a starting path |
| 2. Domain hubs | Evolith Core · Evolith SDLC · Evolith Products | Understand each domain's goal, objectives, and boundaries |
| 3. Area hubs | Architecture, ADRs, Standards, SDLC phases, Product designs, Topologies | Locate the family of artifacts for one concern |
| 4. Detail documents | ADRs, templates, standards, rulesets, guides, OPA policies, UMS contracts | Apply one specific, authoritative artifact |
When you already know which artifact you need, skip the descent and open the Global Master Index.
Evolith Core governs and provides reference artifacts for the following architecture topologies, each residing in an isolated /topologies/ subdirectory with its own ADRs, OPA policies, AI rulesets, and UMS contracts:
| Topology | Description |
|---|---|
| Modular Monolith | Foundational topology for systems that start simple and mature without premature distribution |
| Cloud-Native Serverless | Event-driven, auto-scaling, pay-per-execution architectures on FaaS and managed services |
| Event-Driven | Async-first systems with message brokers, event sourcing, and CQRS |
| Data Mesh | Domain-oriented, self-serve data platforms with federated governance |
| Edge Computing | Distributed compute at the network edge with offline-first and low-latency constraints |
| Agentic / AI-First | Architectures designed for AI agents as first-class system actors with Model Context Protocol (MCP) integration |
Evolith Core exposes three mandatory access channels for any engineering team to interact with the governance framework programmatically:
| Interface | Purpose |
|---|---|
| CLI | Developers validate code locally against the rulesets of their chosen topology. smart-cli validate, smart-cli adr create, etc. |
| MCP (Model Context Protocol) | The fundamental API for injecting "Architectural Context" directly into AI agents (Copilot, Cursor, etc.), enabling the agent to understand governance rules before writing code |
| Service CORE API | Programmatic interface for orchestration systems (e.g., Evolith Tracker) to query patterns, UMS contracts, and OPA policies remotely |
The /topologies/ tree is the strict modular boundary for executable architecture governance. Every supported topology must be isolated as a complete bounded context and must expose the same artifact families:
/topologies/
/agentic-ai/
/adrs/
/opa-policies/
/ai-rulesets/
/ums-contracts/
/serverless/
/adrs/
/opa-policies/
/ai-rulesets/
/ums-contracts/
No topology may leak rules, contracts, or runtime assumptions into another topology. Shared concerns must be promoted into Core-level standards only when they are proven reusable across bounded contexts.
Critical rule: Phase 1 artifacts (technical ideation) within Core MUST remain 100% decoupled from any business data — budgets, ROI, costs, resourcing. Core exposes only the What and the How (technical). The Tracker (via its ACL and Funnel 0) is the sole component authorized to manage the When and the Who (business).
Goal: orient any reader — executive, architect, engineer, or AI agent — in less than five minutes.
Objectives: explain what Evolith is, route each role to its shortest reading path, and expose the full navigation index for direct access.
Primary entry points
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Executive One-Pager | Five-minute explanation of Evolith, UMS, and the value proposition | Communicate strategic value quickly | Executive summary |
| Getting Started by Role | Recommended reading paths for executives, architects, engineers, QA, SRE, product, and AI contributors | Accelerate onboarding by role | Onboarding guide |
| Product Vision | Strategic direction, roadmap, and maturity model | Align teams to long-term goals | Vision and strategy |
| SDLC Governance Center | Authoritative lifecycle phases, gates, artifacts, and traceability model | Govern the full development lifecycle | Governance hub |
| Global Master Index | Complete repository navigation when you already know what artifact you need | Locate any artifact quickly | Navigation index |
| Integration & Messaging Hub | Async messaging strategies, integration topologies, and pattern governance | Standardize messaging patterns | Architecture hub |
| Application Architecture Hub | Core application patterns (PoEAA) for decoupling data and logic | Standardize app structures | Architecture hub |
| Domain-Driven Design Hub | Strategic and tactical DDD patterns for microservices and bounded contexts | Align software with business domains | Architecture hub |
Getting Started by Role
Purpose: Self-guided onboarding — each profile finds their first reading based on their responsibility.
| Role | What they are looking for | Start here | Then review |
|---|---|---|---|
| Architect | Standards, ADRs, blueprints | Architecture Hub | ADR Matrix |
| Developer | How to implement following SDLC | Engineering Standards | UMS Reference Model |
| QA / SRE | Gates, quality, metrics, ops | Operations Hub | SDLC Quality Gates |
| Product / PM | PRD, traceability, roadmap | SDLC Governance Center | Product Vision |
| AI Agent (BMAD) | Rules, skills, assisted flow | AGENTS.md — agent rules | AI-Assisted Flow |
Goal: define the provider-neutral architecture constitution that every product and satellite repository inherits.
Objectives: centralize architecture directives and blueprints, preserve decision history through ADRs, align teams on standards and governance, and automate compliance with rulesets.
Domain hub: Evolith Core — what Core is, what it is not, its domains, and its dependency rule.
Architecture and Blueprints
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Architectural Directives & Hub | Single entry point to directives, blueprints, base stack and topologies | Guide corporate design | Architecture hub |
Architecture Decisions (ADRs)
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| General ADR Registry | Central hub grouping the decision matrix and all ecosystem ADRs | Maintain history and governance | Decisions hub |
Standards and Governance
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Standards and Governance Center | Main directory for manifestos, taxonomies, technical directives and observability | Align teams to unified policies | Governance hub |
| Infrastructure & Operations Hub | Consolidated access to deployments, SRE guides and infrastructure | Standardize deployments and operations | Operations hub |
Rulesets and Validation
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| General Rulesets Hub | Centralizes all automated architecture rules, schemas and CI validation | Validate automated compliance | Rules hub |
Goal: govern the full development lifecycle through five phases with explicit gates and verifiable evidence.
Objectives: map every phase to its mandatory and optional artifacts, standardize templates, enforce quality gates and traceability, and validate compliance automatically in CI.
Domain hub: SDLC Governance Center — phases, gates, artifacts, roles, and the traceability model.
The five phases below run from conception to operations; each section lists that phase's artifacts with their requirement level.
General SDLC References
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| SDLC Artifact Mapping | Artifact mapping | Link phases and deliverables | Standards and guidance |
Phase 01 - Conception and Discovery
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) | Requirement |
|---|---|---|---|---|
| Discovery Canvas | Discovery canvas | Define vision and feasibility | Documents and templates | Mandatory |
| Technical Feasibility Canvas | Technical feasibility | Specify NFRs and constraints | Documents and templates | Optional |
| Ballpark Estimation | High-level estimation | Project costs and times | Documents and templates | Optional |
| PRD - Product Requirements Document | Product requirements | Specify functional needs | Documents and templates | Mandatory |
| Evolith User Story | User story template | Standardize agile stories | Documents and templates | Mandatory |
| Agile Backlog | Backlog template | Organize deliverables | Documents and templates | Mandatory |
| CLI Impact Analysis | CLI impact analysis | Evaluate cross-repo changes | Documents and templates | Optional |
| Validation Schemas & Rules (Phase 1) | Validation schemas for Canvas, PRD, Backlog and Gate rules | Validate compliance in CI | Rules and schemas | Mandatory |
Phase 02 - Design and Architecture
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) | Requirement |
|---|---|---|---|---|
| ADR Template | ADR template | Document key decisions | Documents and templates | Optional |
| Functional Story Template | Functional story template | Detail behavior | Documents and templates | Mandatory |
| DDD Model Template | DDD model template | Model system domains | Documents and templates | Optional |
| Functional Story Writing Standard | Functional story standard | Ensure specs quality | Standards and guidance | Mandatory |
| SDLC Documentation Best Practices | Documentation best practices | Improve documentation quality | Standards and guidance | Mandatory |
| Validation Schemas & Rules (Phase 2) | Validation schemas for ADRs and Functional Stories | Validate data structure | Rules and schemas | Mandatory |
Phase 03 - Construction
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) | Requirement |
|---|---|---|---|---|
| Artifact Templates Hub | Templates hub | Centralize SDLC formats | Documents and templates | Mandatory |
| Technical Story Template | Technical story template | Structure technical tasks | Documents and templates | Mandatory |
| Construction-Focused SDLC Framework | Construction framework and Definition of Done (DoD) | Regulate technical execution | Standards and guidance | Mandatory |
| SDLC Quality Gates | Quality gates | Establish approval thresholds | Standards and guidance | Mandatory |
| Validation Schemas & Rules (Phase 3) | Schemas for Technical Stories, DoD rules, Thresholds and Dependency Pinning | Validate compliance in CI | Rules and schemas | Mandatory |
Phase 04 - Validation and QA
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) | Requirement |
|---|---|---|---|---|
| Test Summary Report Template | Test summary report | Consolidate QA results | Documents and templates | Mandatory |
| SDLC Traceability Model | Traceability model | Link requirements and tests | Standards and guidance | Mandatory |
| Validation Schemas & Rules (Phase 4) | Test summary report validation schema | Validate compliance in CI | Rules and schemas | Mandatory |
Phase 05 - Delivery and Operations
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) | Requirement |
|---|---|---|---|---|
| Release Notes Template | Release notes template | Communicate release changes | Documents and templates | Mandatory |
| Validation Schemas & Rules (Phase 5) | Release notes validation schema, CI/CD gates rules (ADR-0005) and GitFlow (ADR-0050) | Automate pipeline validation | Rules and schemas | Mandatory |
Goal: deliver the Core constitution as working products and prove it through applied references.
Objectives: direct the portfolio through the Product Suite, document each product's internal design, demonstrate real adoption through UMS and adoption cases, and tool the workflow with the Smart CLI.
Domain hubs: Product Suite (portfolio vision and strategy) · Product Designs (per-product internals)
Suite Tracking — pending work, audit, and maturity
The two canonical tracking surfaces for the suite — everything pending, audited, or measured lives in one of these:
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Gap Tracking Board | Single compact table for every gap, ordered by criticality, status, and complexity; each ID opens its detailed reference | See instantly what remains and open the explanation only when needed | Tracking board |
| Maturity Assessment | Single maturity evaluation: TOGAF ACMM matrix, WAF review, patterns/anti-patterns audit, and vision alignment | Measure how mature the suite is and where to invest | Maturity matrix and audit |
| Documentation Coverage Report | Bilingual documentation coverage status | Audit documentation completeness | Coverage report |
Evolith Product Suite
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Product Suite Hub | Single entry point to portfolio vision, strategy and positioning | Ecosystem direction | Product reference |
| Evolith Core Architecture | Complete C4 ecosystem design and platform conceptual vision | Architecture master blueprint | Architecture blueprint |
Evolith Tracker
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Evolith Tracker Hub | Central hub grouping Tracker product architecture and technical interfaces | Governance product | Product reference |
UMS (Applied Reference)
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| UMS Reference Hub | Consolidated access to UMS reference models, comparisons and architecture portal | Demonstrate real implementation | Applied reference |
Smart CLI
# Initialize new satellite repository
npx @evolith/smart-cli init
# Validate against Evolith standards
smart-cli validate
# Manage ADRs
smart-cli adr create
smart-cli adr list
# MCP server for AI assistants
smart-cli mcp serve| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Smart CLI Hub | Central access to CLI documentation, architecture, vision and state analysis | Understand the tool | Product reference |
Adoption Cases and Tools
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Adoption Cases | Adoption cases | Showcase success and learning | Applied reference |
- validate-docs.mjs - link, anchor, encoding, and Mermaid validation.
- check-bilingual-parity.mjs - EN/ES structure parity validation.
- impact-analysis-synchronizer.mjs - cross-repository impact synchronization.
Goal: make every document findable in two clicks or less, in both languages.
Objectives: maintain the master index as the complete navigation surface, audit EN/ES parity, and record documentation releases.
| Link (URL) | Description (brief explanation) | Goal / Objective | Typification (category or type) |
|---|---|---|---|
| Global Master Index | The single complete navigation surface: by intent, by role, by SDLC phase (every artifact per phase), and with agnostic Core separated from platform-specific | Locate any artifact quickly | Navigation index |
| Bilingual Index | Auto-generated EN/ES pairing status for the reference corpus | Audit bilingual coverage | Navigation index |
| Quick Access by Stack | Shortest path to React, .NET, and Node.js standards | Reduce navigation friction | Navigation index |
| Documentation Taxonomy | What kind of document belongs where | Keep the corpus organized | Governance reference |
Before contributing, read:
- Open Source Contributing Guide — How to contribute as a community member using the BMAD method
- AGENTS.md — Agent rules and conventions
- Repository Taxonomy — What goes where
- Child Repository Inheritance Guide — How products inherit
Published under the MIT License.