Bilingual Navigation: English (this document) · Versión en Español
Evolith Tracker is the Governance Control Plane for AI-Native software engineering. It is not a traditional task manager (not a Jira or Trello) nor does it intend to replace specialized industry tools. Its purpose is to digitize, automate, and audit the entire software development lifecycle (SDLC) by strictly applying Evolith's architectural rules.
It inverts the traditional development equation: AI builds and executes; external tools operate; Evolith governs and orchestrates.
Evolith Tracker adopts the Governed Composition model. This means we build the irreducible governance kernel (Phase Gates, traceability, Core rules, and the Evidence Graph) and consume mature commodity capabilities through Ports and Adapters.
- Core defines: Rules, schemas, taxonomies, and contracts (
evolith_arch32). - Providers execute: Repositories, CI/CD, work management systems (Jira), LLM observability, and Analytics tools.
- CLI / MCP evaluates: Executes stateless technical validations (Technical Evaluation Result).
- Tracker decides: Centralizes and consolidates evidence to issue the canonical decision (Gate Decision) and advance the phase.
- Multi-Tenant Progressive Monolith Ecosystem: Prepared for Cloud SaaS with absolute data isolation per
TenantID. - Dependency Inversion (Ports & Adapters): Its core is shielded. External providers (e.g., Langfuse, Jira, GitHub) connect through an Anti-Corruption Layer (ACL) ensuring their schemas do not contaminate the Tracker's domain.
- Delegated Identity (UMS): Consumes AuthN, AuthZ, and roles (RACI) directly from the independent SaaS UMS.
- Upstream Governance: Evolith Core contains the immutable guidelines. The Tracker inherits, applies, and can propose improvements (ADRs) to the Core based on operational evidence.
Governance does not begin at the first line of code, nor even at Discovery — it begins the moment an idea earns the right to consume engineering capacity. Funnel 0 (Strategic Intake) is that entry port: the contract boundary where a business decision becomes a governed engineering initiative.
Evolith is not a financial or portfolio tool. It does not replace Project Portfolio Management (PPM) platforms such as Meisterplan, and it does not perform capacity planning, financial modeling, or "what-if" prioritization. Those decisions remain upstream, owned by the business.
| Concern | Owner | Tool |
|---|---|---|
| Portfolio prioritization & capacity planning | Portfolio Manager | PPM (e.g., Meisterplan) |
| Financial modeling & ROI calculation | Finance / PMO | PPM / ERP |
| Engineering governance & SDLC auditability | Engineering | Evolith Tracker |
| Technical feasibility & architectural risk | Loop Engineer (AI Agent) | Evolith Tracker |
Within the Governed Composition model: the PPM proposes; Evolith governs.
Funnel 0 acts as the Business Case Receiver: the authoritative endpoint that captures, validates, and anchors the strategic intent behind every initiative before it is allowed to enter the SDLC. Evolith receives the business case — it does not compute it.
At intake, Tracker persists the following four non-negotiable inputs into the immutable Evidence Graph within Phase 0 (Strategic Intake) to establish the strategic baseline:
| Input | Meaning | Downstream Impact (Phase 1 onwards) |
|---|---|---|
| Expected ROI | The value hypothesis the initiative is accountable to | Stored strictly in Phase 0; used by external PPM to correlate value realization with technical metrics via opportunity_ref |
| Budget | The financial envelope authorized upstream by the PPM | Stored strictly in Phase 0; used by external PPM to track cost vs effort metrics via opportunity_ref |
| Risk Level | Inherent risk classification (Low / Medium / High / Critical) | Calibrates Phase Gate rigor and approval thresholds |
| Initial Stakeholders | Accountable parties (RACI) | Resolved against the delegated identity provider (UMS); drives notification and approval routing |
By receiving — rather than computing — the business case, Evolith preserves a clean separation of concerns: the PPM owns whether and why to invest (and all associated financial/portfolio metrics); Evolith owns the technical execution governance (without any cost or budget logic in its execution core). Any correlation between technical effort/drift and financial budget/ROI is performed outside of Evolith's core engine, bridged by the opportunity_ref token.
Funnel 0 connects to upstream PPM tools through a bidirectional Handshake API — a port-and-adapter contract that injects approved initiatives downstream and returns live delivery telemetry upstream. The integration is structurally asymmetric: the PPM pushes once (initiative injection); Evolith streams continuously (telemetry feedback throughout the entire lifecycle).
-
What-if Evaluation (PPM-owned): Inside the PPM, portfolio managers run scenario and capacity simulations, balancing initiatives against strategic budget and resource constraints. This step is entirely within the business domain; Evolith is not invoked and has no visibility.
-
Initiative Injection (PPM → Funnel 0 via Handshake API): Once the portfolio manager approves an initiative in the PPM, a machine-to-machine push is triggered to the Handshake API endpoint. The payload carries the four business case inputs (ROI, Budget, Risk Level, Stakeholders) in the PPM's native schema. Evolith's Anti-Corruption Layer (ACL) normalizes this payload into the Tracker's canonical domain model — no external schema bleeds into the Tracker core.
-
Baseline Anchoring (Funnel 0 → Evidence Graph): Upon successful ingestion, Funnel 0 creates a new
Initiativeaggregate, stamps an immutable baseline record in the Evidence Graph, and resolves the stakeholder list against the UMS identity provider. The initiative entersPENDING_FEASIBILITYstate. -
Technical Feasibility Evaluation (Loop Engineer): The Loop Engineer — Evolith's AI-Native engineering agent — is dispatched automatically. It evaluates the injected initiative across three dimensions: (a) technical viability, (b) architectural fit ("Build vs Compose" alignment), and (c) architectural risk given the current system topology. It produces a structured Feasibility Verdict with a justification attached to the Evidence Graph.
-
Gate Decision: Promote or Reject:
- If Feasible: The initiative is promoted out of Funnel 0 and enters the Discovery & Ideation Hub (Gate 1) as a fully-formed, governed initiative. Crucially, to enforce strict domain boundaries and prevent economic contamination, the technical Initiative does not inherit or copy any financial data (ROI, Budget). Instead, it stores an optional, read-only pointer
opportunity_refreferencing the Phase 0 Opportunity/external PPM record. The technical baseline is strictly non-financial (e.g., technical risk classification, initial scope boundaries). - If Not Feasible: Funnel 0 issues a structured rejection response back to the PPM via the Handshake API, including the technical rationale from the Loop Engineer. The initiative is archived with full audit trail — it can be re-submitted after remediation.
- If Feasible: The initiative is promoted out of Funnel 0 and enters the Discovery & Ideation Hub (Gate 1) as a fully-formed, governed initiative. Crucially, to enforce strict domain boundaries and prevent economic contamination, the technical Initiative does not inherit or copy any financial data (ROI, Budget). Instead, it stores an optional, read-only pointer
-
Continuous Telemetry Feedback (Evolith → PPM): Throughout the initiative's entire SDLC journey, Evolith streams technical delivery telemetry (effort deviation, technical debt/architectural drift, velocity, gate decisions) decorated with the
opportunity_refback to the external layers via the Handshake API. These integration events allow the external PPM or BI gateway to translate engineering evidence into financial impact (cost overrun, ROI adjustments). This keeps the Evolith core execution engine 100% clean of financial logic.
sequenceDiagram
autonumber
actor PM as Portfolio Manager
participant MP as Meisterplan PPM
participant ACL as Evolith ACL Adapter
participant F0 as Evolith Funnel 0
participant EG as Evidence Graph
participant LE as Loop Engineer
participant DH as Discovery Hub Gate 1
rect rgb(240, 248, 255)
Note over PM,MP: PPM Domain — Business Decision (Evolith not involved)
PM->>MP: Run What-if scenario and capacity planning
MP-->>PM: Optimized portfolio snapshot (ROI, budget, risk scores)
PM->>MP: Approve initiative for engineering intake
end
rect rgb(255, 248, 240)
Note over MP,F0: Handshake API — Initiative Injection
MP->>ACL: POST /handshake/intake (PPM native schema)
ACL->>F0: Normalized InitiativePayload (ROI, Budget, RiskLevel, Stakeholders)
activate F0
F0->>EG: Persist immutable baseline record
EG-->>F0: baseline_id confirmed
F0->>F0: Resolve Stakeholders via UMS
F0->>F0: Set state to PENDING_FEASIBILITY
end
rect rgb(240, 255, 248)
Note over F0,LE: Technical Feasibility Evaluation
F0->>LE: Dispatch FeasibilityRequest (initiative_id, baseline_id)
activate LE
LE->>LE: Assess technical viability
LE->>LE: Evaluate Build vs Compose fit
LE->>LE: Analyse architectural risk
LE-->>F0: FeasibilityVerdict (status, rationale, risk_score)
deactivate LE
F0->>EG: Append FeasibilityVerdict to Evidence Graph
end
rect rgb(255, 240, 248)
Note over F0,DH: Gate Decision
alt Verdict is FEASIBLE
F0->>DH: PromoteInitiative (strategic baseline intact)
DH-->>F0: Gate 1 admission acknowledged
F0->>F0: Set state to ADMITTED
else Verdict is NOT_FEASIBLE
F0-->>ACL: Rejection payload (technical rationale)
ACL-->>MP: Handshake API — Rejection response
F0->>F0: Set state to REJECTED and archive
end
deactivate F0
end
rect rgb(248, 248, 240)
Note over DH,MP: Continuous Telemetry Feedback Loop
DH-->>ACL: Telemetry stream (gate decisions, metrics)
ACL-->>MP: Handshake API — Delivery telemetry
Note over MP: Next What-if cycle grounded in real engineering evidence
end
Governance Note: Every state transition in Funnel 0 — from
PENDING_FEASIBILITYtoADMITTEDorREJECTED— is appended to the immutable Evidence Graph with a timestamp, actor identity (human or agent), and the full decision payload. This ensures that Funnel 0 decisions are fully auditable and traceable to the originating PPM approval.
Tracker models the SDLC through 5 consecutive gates (Phase Gates), where it acts as the sole final authority to allow transitions:
- Discovery & Ideation Hub: Validate technical fit, KPIs, scope boundaries, and Build-vs-Compose alignment. ROI and budget remain anchored in Funnel 0/PPM and are referenced only through
opportunity_ref. - Architecture Spec-Driven (Design): Consolidate contracts (OpenAPI/AsyncAPI) and approved ADRs.
- Construction Tracking: Validate evidence from external repositories and CI/CD against design contracts (strict Architecture Drift control).
- Automated QA & Integration: Reception of test results, security, and deep integration via ports.
- Dynamic Release Planner: Command board for deployments. In case of a block, agents propose a contingency flow ("Re-Do") and a human authorizes.
Tracker consolidates the immutable Evidence Graph. Through Analytics ports, it exposes validated metrics of the entire value stream:
- DORA & SPACE Metrics
- Architecture Adherence Index: Early warnings of architecture deviation detected during pre-deployment phases.
The Evolith ecosystem is not a single monolithic platform — it is a federated constellation of specialized systems bound together by a constitutional governance contract. Understanding how Evolith Core (evolith_arch32), Evolith Tracker, and satellite products interact is essential to understanding why the architecture is both resilient and extensible.
Evolith Core (evolith_arch32) is the root authority of the entire ecosystem. It is not a runtime service the Tracker calls for business logic; it is the governance constitution that defines the non-negotiable rules all satellites must inherit and enforce. Its authority is manifested through four canonical assets that it publishes and maintains:
| Asset | What it defines | How it propagates |
|---|---|---|
| Architecture Decision Records (ADRs) | Technology choices, architectural patterns, and constraints applicable across all satellites | Published via the Core API Exposure Layer; fetched at runtime and cached by each satellite |
| Rulesets | Phase Gate criteria, artifact requirements, compliance thresholds (e.g., CFR < 2%) | Queried by Tracker's CoreIntegrationService per SDLC phase; cached with a 5-minute TTL to ensure near-real-time accuracy |
| Artifact Schema Catalog | Canonical definitions for every SDLC artifact (PRD, ADR, BusinessCase, TechnicalBlueprint, etc.) | Synchronized via the Core Artifact Sync mechanism; Tracker never defines schemas — it consumes and validates against them |
| Taxonomy / Glossary | The authoritative vocabulary and classification system shared across all products | Cached with a 24-hour TTL; ensures terminological consistency throughout the ecosystem |
A critical architectural invariant governs this relationship: the Tracker must never fork, copy, or store Core content as a local second source of truth. Core data is always fresh from the source, validated against the current Core version, and invalidated atomically when a new Core version is detected.
Each satellite product — including Evolith Tracker — inherits the Core's baseline by default. This is not optional compatibility; it is the Decision Inheritance Contract formalized in each satellite's evolith.satellite.json manifest and DECISIONS.md log.
The contract operates on three operations:
| Operation | Meaning | Example |
|---|---|---|
| Adopt | Satellite accepts the upstream decision verbatim | T-003: Hexagonal Architecture (Ports & Adapters), T-005: TypeORM Data Mapper |
| Extend | Satellite adds satellite-specific detail without contradicting the upstream rule | T-010: Agent framework configurable per tenant (Core uses BMAD internally; Tracker is framework-agnostic) |
| Override | Satellite explicitly diverges from the upstream decision with documented justification | T-002: Microfrontend topology in Phase 1 (deviation for UI scalability) |
Any deviation that is not formally registered as an Override in DECISIONS.md is an undocumented divergence — a governance violation that can be surfaced by automated ADR compliance checks.
The fundamental risk in a federated architecture is schema contamination — the leakage of external data models into the satellite's core domain, which gradually erodes domain integrity and creates brittle coupling. Evolith addresses this through a mandatory Anti-Corruption Layer (ACL) at every integration boundary.
Every integration boundary in the ecosystem has a dedicated ACL:
Core publishes rulesets, artifact definitions, and taxonomies in its own canonical schema. The Tracker's CoreIntegrationService translates these into the Tracker's own domain types. No Core schema type bleeds into the Tracker's domain model or UI view-models. If Core updates a schema in a breaking way, the ACL absorbs the change — Tracker's internal domain remains stable.
The Handshake API's ACL Adapter normalizes the PPM's native payload (initiative metadata in Meisterplan's schema) into the Tracker's canonical InitiativePayload domain object before it enters Funnel 0. Neither the portfolio tool's entity model nor its field naming conventions pollute the Tracker's domain.
Third-party providers — GitHub, Jira, Langfuse, .harness — connect exclusively through Adapter implementations of the Tracker's Port interfaces. The Port defines the contract in the Tracker's domain language; the Adapter translates between the Tracker's contract and the provider's API. Replacing a provider (e.g., GitHub → GitLab) requires only a new Adapter; the core domain is entirely unaffected.
AuthN, AuthZ, and RACI roles are consumed from the external UMS SaaS. The Tracker resolves stakeholder identities and applies RBAC based on roles fetched from UMS, but never stores user credentials locally. The UMS ACL maps UMS role schemas to the Tracker's internal StakeholderRole domain type.
Architectural Invariant: No Core schema may reach the Tracker UI in raw form. View-models exposed to the frontend are always translated through an ACL, ensuring the UI is decoupled from both Core and backend domain models. This is enforced as a non-negotiable boundary invariant in
evolith.satellite.json.
The governance relationship is not unidirectional. The Hub-and-Spoke model includes a structured upward feedback channel through which satellites contribute operational intelligence back to Core:
- ADR Candidates: When Tracker discovers a recurring architectural pattern that is not yet covered by an upstream ADR, it raises a formal ADR Candidate proposal via the Core Feedback API. If accepted, the pattern is promoted to a Core-level ADR and automatically inherited by all satellites.
- Ruleset Gaps: When a Phase Gate evaluation fails because an applicable Core ruleset criterion is missing or incomplete, Tracker submits a Ruleset Gap proposal to Core for review.
- CLI/SDK Gaps: When AI agents require Core capabilities not currently exposed through the Core API or MCP server, the gap is logged and submitted as a structured proposal.
This feedback loop ensures the Core evolves from real-world evidence generated by its satellites — not from theoretical design alone.
flowchart TB
subgraph CORE["Evolith Core evolith_arch32 — Root Authority"]
direction LR
ADR_REG["ADR Registry"]
RULESET["Ruleset Engine"]
SCHEMA_CAT["Artifact Schema Catalog"]
TAXONOMY["Taxonomy and Glossary"]
CORE_API["Core API Exposure Layer"]
FEEDBACK_API["Feedback API"]
end
subgraph TRACKER["Evolith Tracker — Governance Control Plane"]
direction TB
subgraph ACL_CORE["ACL: Core Adapter"]
CIS["CoreIntegrationService"]
CACHE["CoreCacheService TTL-keyed"]
end
subgraph DOMAIN["Tracker Domain"]
F0["Funnel 0 Strategic Intake"]
GATES["Phase Gates 1 to 5"]
EG["Evidence Graph immutable"]
TA["TenantConfig per-tenant"]
end
subgraph ACL_PPM["ACL: PPM Adapter"]
HS_API["Handshake API"]
end
subgraph PORTS["Ports and Adapters"]
SCM_PORT["SCM Port"]
CICD_PORT["CI and CD Port"]
OBS_PORT["Observability Port"]
UMS_PORT["UMS Port"]
end
FEEDBACK_SVC["CoreFeedbackService"]
end
subgraph PPM["Upstream PPM Meisterplan"]
PM_TOOL["Portfolio Manager"]
WHATIF["What-if Scenarios"]
end
subgraph SATELLITES["Other Satellite Products"]
SAT1["Satellite A"]
SAT2["Satellite B"]
end
subgraph PROVIDERS["External Execution Providers"]
GITHUB["GitHub / GitLab SCM"]
HARNESS_CI[".harness CI and CD"]
LANGFUSE["Langfuse LLM Obs"]
UMS_SVC["UMS Identity SaaS"]
end
CORE_API -->|"Rulesets ADRs Schemas TTL-cached"| CIS
CIS --> CACHE
CACHE --> GATES
CACHE --> F0
PM_TOOL -->|"POST handshake/intake PPM schema"| HS_API
HS_API -->|"Normalized InitiativePayload"| F0
F0 --> EG
F0 --> GATES
GATES --> EG
GATES -->|"Telemetry stream"| HS_API
HS_API -->|"Delivery telemetry"| PM_TOOL
SCM_PORT -->|"Adapter"| GITHUB
CICD_PORT -->|"Adapter"| HARNESS_CI
OBS_PORT -->|"Adapter"| LANGFUSE
UMS_PORT -->|"Adapter"| UMS_SVC
FEEDBACK_SVC -->|"ADR Candidates Ruleset Gaps"| FEEDBACK_API
CORE_API -->|"Inherited governance"| SAT1
CORE_API -->|"Inherited governance"| SAT2
classDef coreStyle fill:#1abc9c,stroke:#16a085,color:white
classDef trackerStyle fill:#2980b9,stroke:#1a5276,color:white
classDef aclStyle fill:#8e44ad,stroke:#6c3483,color:white
classDef ppmStyle fill:#e67e22,stroke:#ca6f1e,color:white
classDef providerStyle fill:#7f8c8d,stroke:#626567,color:white
classDef satStyle fill:#27ae60,stroke:#1e8449,color:white
classDef domainStyle fill:#2c3e50,stroke:#1a252f,color:white
class ADR_REG,RULESET,SCHEMA_CAT,TAXONOMY,CORE_API,FEEDBACK_API coreStyle
class CIS,CACHE,SCM_PORT,CICD_PORT,OBS_PORT,UMS_PORT,PORTS,FEEDBACK_SVC trackerStyle
class ACL_CORE,ACL_PPM,HS_API aclStyle
class PM_TOOL,WHATIF,PPM ppmStyle
class GITHUB,HARNESS_CI,LANGFUSE,UMS_SVC providerStyle
class SAT1,SAT2 satStyle
class F0,GATES,EG,TA domainStyle
The following invariants are enforced as non-negotiable constraints across the entire ecosystem, regardless of which satellite is in scope:
| # | Invariant | Enforcement Mechanism |
|---|---|---|
| I-1 | The Tracker decides the gates; Core only produces evaluations and evidence | Satellite manifest boundary contract |
| I-2 | The Core is the authority of rules; the Tracker must not redefine Core rules | Decision Inheritance (Adopt / Extend / Override) + DECISIONS.md audit |
| I-3 | No Core schema may leak raw to the Tracker UI | ACL in CoreIntegrationService; view-model translation enforced at BFF layer |
| I-4 | The BFF/Application Gateway lives in the Tracker-facing perimeter, never as direct satellite-to-Core internals | ADR-0074 / ADR-0075 (Core API Exposure Layer + NestJS BFF) |
| I-5 | All Core communication routes through Tier 1 Kong Edge → Tier 2 NestJS BFF using the B2B API Gateway pattern | T-015; direct internal Core calls are forbidden for all satellites |
| I-6 | Tenant isolation and PII stripping are enforced on every composed request | Enforced at the BFF layer per TenantID |
| I-7 | Core data is never persisted locally as a second source of truth | CoreCacheService uses TTL-keyed caches; version-keyed invalidation on Core version change |
Evolith Tracker is designed for enterprise B2B environments where software engineering organizations require automated, continuous, and auditable governance. Access control, permissions, and roles (RACI) are strictly managed via a centralized User Management System (UMS) integrated into our multi-tenant SaaS architecture. All workspace data, evidence, and policies are fully isolated per TenantID.
The table below outlines the core user personas, their current pain points without Evolith, and the specific value proposition/benefit they receive.
| Persona | Pain Points (Without Evolith) | Value Proposition (With Evolith Tracker) | UMS & Tenant Context |
|---|---|---|---|
| Chief Technology Officer (CTO) | • Lack of real-time visibility into SDLC compliance and quality across teams. • Inability to correlate strategic ROI and budget with actual technical delivery. • High audit overhead and regulatory compliance costs. |
• Unified executive dashboard showing real-time DORA and SPACE metrics mapped to business goals. • Automated governance gates that guarantee policy compliance without manual auditing. • High-level visibility into systemic architectural risks. |
Tenant Owner / Administrator: • Full visibility over all tenant workspaces. • Configures organizational-level rulesets and policies. |
| Corporate Architect | • Manual architecture reviews that slow down releases. • Inability to prevent architecture drift and rule violations at scale. • Difficulty tracking ADR adoption and compliance across dozens of repositories. |
• Active enforcement of architectural guidelines at gates via automated rule engines. • Real-time detection of architectural drift and violation alerts. • Automated synchronization of ADR compliance reports directly with Evolith Core. |
Domain Architect / Governor: • Configures local ADR inheritance (Adopt, Extend, Override). • Approves exception bypasses at quality gates. |
| Software Developer | • Friction and cognitive load from manually submitting evidence for compliance gates. • Unclear and shifting quality requirements before a production release. • Interruptions due to slow, manual PR reviews and approvals. |
• Zero-friction automated background evidence collection (Jira, GitHub, Langfuse, Harness). • Clear, upfront rulesets evaluated locally via CLI/MCP tool before pushing code. • Streamlined path to production with instant automated gate decisions. |
Contributor / Engineer: • Read/write access within their assigned repositories and codebases under their specific tenant. |
| Product Manager (PM) | • Disconnect between business cases (ROI, budget, risk) and engineering execution. • Hard to track if the features being built align with the approved strategic scope. • High manual effort to update Meisterplan/PPM tool with project progress. |
• Direct bi-directional integration with PPM tools (Handshake API) for automated status updates. • Automated alignment tracking between business cases (Funnel 0) and active development stories. • Instant access to feasibility and risk analysis. |
Product Owner / Manager: • Full access to Funnel 0, Discovery, and Release metrics within their tenant. • Manages business cases. |
| Loop Engineer (AI Agent) | • Operates blindly without structured technical context, architecture rules, or feedback. • Inability to run self-checks on proposed designs against the organization's policies. |
• Formalized role under the orchestration layer with explicit tool access and guidelines. • Receives structured contexts (ADRs, schemas, taxonomies) to run pre-validation checks. • Automatically generates structured feasibility and risk verdicts into the Evidence Graph. |
Governed Machine Actor: • Access restricted through scoped API keys mapped to the tenant. • Automated action logs written to the tenant audit log. |
Traditional software engineering setups rely on a fragmented web of disconnected tools (e.g., Jira for project management, GitHub for code storage, SonarQube for static quality analysis). While each of these tools performs its isolated task, they operate as passive, retrospective systems of record.
Evolith Tracker represents a paradigm shift. It replaces passive tooling with an active, AI-Native governance plane injected directly into the SDLC. The table below highlights how Evolith Tracker transforms engineering governance compared to traditional, fragmented setups.
| Dimension | Fragmented Toolchain (Jira + GitHub + SonarQube) | Evolith Tracker (AI-Native Governance) | The Business Impact |
|---|---|---|---|
| Governance Enforcement | Reactive & Post-Factum Violations, quality issues, or architectural drift are discovered after code is committed or deployed, requiring costly rework. |
Active & Gate-Enforced Quality gates programmatically block progression. Code cannot advance to the next phase unless the Evidence Graph verifies rule compliance. |
Drastic Risk Reduction Ensures 100% compliance with organizational standards before capacity is consumed or code is deployed. |
| Traceability & Auditing | Siloed & Manual Correlating a Jira ticket to a PR, a quality report, and a business case requires manual cross-referencing of disconnected logs. |
Unified Evidence Graph Every phase transition, test result, and AI verdict is permanently linked in a tamper-proof, single source of truth. |
Instant Auditability Zero manual effort required to reconstruct project history, proving compliance for financial or regulatory audits. |
| AI Integration | Ad-hoc Bots & Chat assistants Developers use disjointed AI assistants (Copilots) that lack system-level context and operate outside the governance framework. |
Governed AI Agents (Loop Engineer) AI agents are native, authenticated participants (governed by UMS). They run automated feasibility and risk evaluations at the gates. |
Predictable Automation AI agents propose changes and check feasibility under safe, monitored guardrails, preventing rogue code or architecture drift. |
| Architectural Control | Advisory & Easy to Bypass Architecture standards are documented in wikis or ADR files, which are frequently ignored or manually bypassed during crunch times. |
Strict Manifest Inheritance Every repository inherits a structured contract ( evolith.satellite.json). Rules are verified automatically at every phase gate. |
Elimination of Architecture Drift Maintains architectural integrity across thousands of repositories automatically, protecting long-term maintainability. |
| Multi-Tenancy & Isolation | Custom-configured Silos Multi-tenant control requires managing separate instances, custom plugins, and manually setting up permissions per project. |
Native Multi-Tenant Architecture All workspaces, policies, and audit trails are natively partitioned via TenantID and secured through UMS out of the box. |
SaaS-Ready Compliance Allows enterprise customers to run isolated governance structures in a shared cloud infrastructure safely. |
In large-scale enterprise environments, Architecture Drift—the progressive divergence of active software implementations from canonical standards and architectural rules—is a primary source of technical debt, operational risk, and security vulnerabilities.
Evolith Tracker prevents architecture drift by acting as a proactive enforcement engine rather than a passive auditor. It combines strict SDLC phase gates, structural contract validation, and automated AI agents to block, alert, and force remediation before non-compliant changes can reach production.
-
Spec-Driven Design (Discovery Gates):
- Evaluates initiative specifications (PRDs, OpenAPI models, and ADR configurations) before development begins.
- Ensures that all planned APIs, dependencies, and boundary extensions conform to the rules propagated by Evolith Core and the local
evolith.satellite.jsonmanifest. - Action: Any schema inconsistency or illegal rule override (violating the decision inheritance contract) blocks the promotion of the initiative from the Discovery phase to the Construction phase.
-
Construction Tracking (Construction Gates):
- Continuously monitors active code commits, pull requests, and telemetry from SCM and CI/CD tools.
- Automatically cross-references incoming changes against the approved Technical Architecture Design (TAD).
- Action: If a developer bypasses standard ports, injects unauthorized external libraries, or modifies internal bounded context scopes, the Construction Gate fails, blocking code compilation or PR merging.
-
Automated AI Agents (Loop Engineer & Analyst Agent):
- Loop Engineer: Inspects codebase state and proposed changes to evaluate structural viability and architectural risk. It writes a structured Feasibility Verdict to the Evidence Graph.
- Analyst Agent: Assesses business and requirement alignment, ensuring code changes do not drift from the approved project scope.
- Action: If either agent detects high architectural risk or scope drift, they flag the initiative as
NEEDS_CLARIFICATIONand halt phase progression.
When drift is detected, the Tracker applies a tiered enforcement protocol based on the severity of the deviation:
| Severity | Description | Action | Remediation |
|---|---|---|---|
| Low | Minor formatting anomalies or outdated documentation. | Alert & Log: Triggers Slack/GitHub notifications and logs the anomaly in the Evidence Graph. | Autocorrects documentation where possible or flags as a warning for the next PR cycle. |
| Medium | Extraneous library addition or minor API contract variation. | PR Block & Warning: Fails the CI/CD quality gate; blocks PR merging. | Developer must either revert the change or submit a localized ADR candidate via the Core feedback loop. |
| High | Violation of core invariants (e.g. bypassing BFF, direct Core database access, cross-tenant leak). | Hard Block & Alarm: Instantly locks the gate; halts pipeline execution and alerts the Architecture Board. | Requires explicit human architect override or code rollback. |
While the enforcement mechanisms above prevent drift from reaching production, a complete governance system must also detect, track, manage, and remediate drift wherever it occurs — across all environments, sources, and timelines. This is the role of the Architecture Drift Monitor, a core capability of Evolith Tracker.
Architecture Drift is a cross-cutting concern that spans four distinct components in the Evolith ecosystem. Understanding this separation is essential:
| Component | Responsibility |
|---|---|
| Evolith Tracker | Manages the operational lifecycle of drift by tenant/product/initiative. Persistence, visualization, ownership, remediation, exceptions, metrics and audit. |
| Evolith Core | Evaluates stateless whether drift exists by comparing the approved baseline against the observed state. Returns findings, severity, decision and recommendations. |
| Agent Runtime | Orchestrates adapters, scans, tools, evidence collection and calls to Core. |
| OPA / Rulesets | Determine whether drift is allowed, blocked, requires an ADR, requires approval or requires remediation. |
| ADRs / Blueprints | Function as the approved architectural baseline. |
This separation ensures that:
- Tracker remains the operational governance layer — it does not evaluate drift, it manages drift.
- Core remains stateless — it compares baseline vs observed state and returns a verdict without persisting anything.
- Agent Runtime orchestrates detection — Tracker does not scan infrastructure directly; it consumes results.
Architecture Drift occurs when a product, service, microservice, API, infrastructure, dependency, runtime, data flow or integration diverges from its approved architecture baseline.
The approved baseline can come from:
- Architecture Blueprint
- C4 diagrams
- ADRs (Architecture Decision Records)
- Approved dependencies
- Approved APIs
- Approved data flows
- Approved infrastructure topology
- OPA policies
- Rulesets
- Security policies
- SDLC gates
- Architecture Plan
The observed state can come from:
- Pull Requests
- Git repositories
- IaC files (Terraform, Pulumi, CloudFormation)
- Kubernetes manifests
- Runtime inventory
- Cloud inventory
- OpenTelemetry
- API discovery
- Dependency scans
- SBOM
- Container scans
- CI/CD pipelines
- Manual assessments
- Agent Runtime scans
Architecture drift can be detected from multiple sources, each feeding into Tracker via Agent Runtime adapters:
manual
pull_request
smart_cli
mcp
agent_runtime
ci_cd
github_action
iac_scan
kubernetes_scan
cloud_inventory
api_discovery
dependency_scan
sbom_scan
runtime_telemetry
opentelemetry
security_scan
The following taxonomy of drift types is supported:
infrastructure_drift
network_drift
container_orchestration_drift
runtime_service_drift
api_surface_drift
dependency_drift
library_drift
third_party_call_drift
database_connection_drift
data_flow_drift
business_logic_drift
policy_drift
blueprint_drift
adr_drift
security_boundary_drift
deployment_topology_drift
Each drift finding moves through a defined lifecycle of states:
detected → under_review → triaged → accepted_exception
→ remediation_planned → remediating → pending_core_validation → resolved
→ false_positive → archived
→ reopened (from any terminal state)
State descriptions:
| State | Description |
|---|---|
detected |
Drift has been identified by a detection source |
under_review |
A human or agent is reviewing the finding |
triaged |
Priority and impact have been assessed |
accepted_exception |
Drift is knowingly accepted with an exception record |
remediation_planned |
A remediation plan has been created |
remediating |
Active work is underway to resolve the drift |
pending_core_validation |
Remediation applied; awaiting Core re-evaluation |
pending_approval |
Resolution requires explicit approval |
resolved |
Drift has been verified as resolved |
false_positive |
Finding was incorrectly flagged |
risk_accepted |
Organizational risk acceptance decision made |
reopened |
Previously resolved drift has reoccurred |
archived |
Finding is closed and archived for audit |
| Severity | Description | Default Action |
|---|---|---|
critical |
Violation of core invariants (e.g., cross-tenant data leak, bypassing BFF) | Hard block, immediate alarm, architecture board escalation |
high |
Violation of significant architectural rules (e.g., unauthorized dependency, API contract break) | Gate block, PR block, owner notification |
medium |
Moderate deviation (e.g., minor API surface change, extraneous library) | PR block, warning, ADR candidate required |
low |
Minor deviation (e.g., documentation mismatch, formatting) | Alert, log, auto-correct if possible |
informational |
Non-blocking observation | Log, trend analysis |
The functional model introduces these entities:
ArchitectureDriftFinding — The primary entity representing a single drift detection event.
Key fields:
{
"id": "uuid",
"tenant_id": "uuid",
"product_id": "uuid",
"initiative_id": "uuid?",
"environment": "production|staging|development|qa",
"baseline_ref": "blueprint://product/v4",
"baseline_version": "v4.2",
"observed_state_ref": "source://...",
"drift_type": "infrastructure_drift",
"severity": "high",
"status": "detected",
"owner": "user-uuid",
"source": "iac_scan",
"detected_at": "2026-07-01T00:00:00Z",
"last_seen_at": "2026-07-01T00:00:00Z",
"resolved_at": null,
"core_evaluation_id": "uuid",
"policy_result": {},
"opa_result": {},
"related_blueprint_id": "uuid",
"related_adr_ids": ["ADR-001", "ADR-018"],
"related_gate_id": "uuid",
"related_artifacts": [],
"evidence_refs": [],
"recommendation": "string",
"remediation_task_id": "uuid?",
"exception_id": "uuid?",
"approval_id": "uuid?",
"correlation_id": "corr-123",
"trace_id": "trace-456"
}Supporting entities:
- ArchitectureBaseline — The approved baseline configuration for a product/environment
- ObservedArchitectureState — The actual state observed by scanners/adapters
- DriftEvidence — Evidence supporting the drift finding (logs, diffs, reports)
- DriftPolicyEvaluation — Result of policy/ruleset evaluation for a finding
- DriftRemediationTask — A task created to remediate a specific finding
- DriftException — An approved exception allowing controlled drift
- DriftApproval — Approval record for drift decisions
- DriftTrend — Aggregated drift metrics over time
- DriftRiskScore — Computed risk score for a product/tenant based on drift posture
Tracker calls Core statelessly for each drift evaluation:
POST /api/v1/evaluate
Content-Type: application/json
X-Tenant-ID: tenant-001
Authorization: Bearer <b2b-api-key>{
"type": "architecture_drift",
"context": {
"tenant_id": "tenant-001",
"product_id": "product-001",
"initiative_id": "init-001",
"environment": "production"
},
"approved_baseline": {
"blueprint_ref": "blueprint://product/product-001/v4",
"adr_refs": ["ADR-001", "ADR-018"],
"ruleset_refs": ["ruleset://architecture-boundaries"],
"opa_bundle_ref": "opa://architecture-drift"
},
"observed_state": {
"services": [],
"apis": [],
"dependencies": [],
"data_flows": [],
"infra": []
}
}Core response:
{
"drift_detected": true,
"decision": "blocked",
"severity": "high",
"approval_required": true,
"findings": [],
"recommendations": [],
"trace": {
"correlation_id": "corr-123"
}
}Tracker persists the evaluation result, creates ArchitectureDriftFinding records, and enables the operational workflow (assignment, remediation, exception, approval, audit).
Agent Runtime orchestrates detection using adapters. Future planned adapters include:
IaCDriftAdapter— Scans Terraform/Pulumi/CloudFormation against approved topologyKubernetesDriftAdapter— Compares K8s manifests/state against approved cluster specCloudInventoryAdapter— Scans cloud resources against approved inventoryRuntimeServiceDiscoveryAdapter— Detects unauthorized services at runtimeApiSurfaceDiscoveryAdapter— Discovers API endpoints and compares against contractDependencyDriftAdapter— Scans dependencies against approved bill of materialsDataFlowDriftAdapter— Observes inter-service communication against approved data flowsOpenTelemetryDriftAdapter— Uses traces to detect topology changesGitHubPullRequestDriftAdapter— Analyzes PR diffs for potential drift
Tracker receives results from Agent Runtime and associates them with tenant/product/initiative/environment.
Smart CLI:
evolith drift scan --product product-001 --env production
evolith drift evaluate --baseline blueprint://product/v4 --observed observed-state.json
evolith drift list --product product-001
evolith drift get DRIFT-001
evolith drift explain DRIFT-001
evolith drift remediate DRIFT-001 --planMCP Tools:
drift.scan
drift.evaluate
drift.list
drift.get
drift.explain
drift.remediation.plan
drift.exception.request
Chat Prompts:
"What drift does this product have?"
"Explain why this drift is critical."
"What ADR do I need to resolve this drift?"
"Which products have the most drift this month?"
"What drift is blocking this initiative?"
| Metric | Description |
|---|---|
| Drift density by product | Number of open findings per product normalized by size |
| Mean time to remediate (MTTR) | Average time from detection to resolution |
| Critical drift aging | Time since detection for critical findings |
| % of drift with owner | Findings assigned to an accountable owner |
| % of drift with evidence | Findings backed by concrete evidence |
| % of drift linked to ADR | Findings that have an associated ADR decision |
| % of drift resolved before release | Findings closed before a product release |
| Products with stable baseline | Products with zero critical/high drift |
| Products with repeated drift | Products where previously resolved drift reappears |
| Policy violation trend | Evolution of policy violations over time |
Evolith Tracker is the operational governance layer that enables organizations to monitor the lifecycle, traceability, compliance and architectural integrity of products and initiatives across tenants.
With Architecture Drift Tracking, Tracker helps teams detect when the implemented, deployed or proposed architecture diverges from the approved baseline, enabling early remediation, accountable exceptions, evidence-based decisions and continuous architectural governance.
| Persona | Primary Need |
|---|---|
| Corporate Architect | See drift across all products, understand trends, enforce ADR compliance |
| Technical Lead | Own and resolve drift findings for their product, manage remediation backlog |
| Governance Lead | Approve drift exceptions, monitor risk acceptance, audit drift lifecycle |
| Product Owner | Understand drift impact on initiative timelines and gate progression |
| Developer | Get early feedback on drift before PR merges, understand what is wrong |
High-level dashboard showing:
- Total drift findings
- Critical/high findings count
- Findings by tenant, product, environment
- Findings by drift type
- Open vs resolved trend
- Aging distribution
- Risk score overview
- Top impacted products
- Policy violations
- Pending approvals and remediations
Per-product drill-down showing:
- Current architecture baseline and version
- Associated blueprint and ADRs
- Monitored environments
- Active and historical findings
- Drift trend over time
- Product risk score
- Affected gates and related initiatives
- Remediation backlog
- Active exceptions
Cross-tenant summary showing:
- Products with highest drift
- Drift by environment, severity, and type
- Monthly trend
- Top owners by finding count
- Active exceptions per product
- Remediation compliance rate
Per-initiative analysis showing:
- Drift detected during the initiative
- Proposed changes generating drift
- Affected gates
- Required ADRs
- Blueprints that must be updated
- Blocking policies
- Missing evidence
- Required approvals
Full detail page for a single finding showing:
- Summary, severity, status
- Tenant, product, initiative, environment context
- Expected baseline vs observed state
- Visual diff
- Policy result and OPA result
- Core evaluation result
- Related ADRs, blueprint, gates
- Evidence timeline
- Recommendations
- Owner, timeline, comments
- Actions: assign, remediate, approve, exception, re-evaluate
Registry of approved baselines:
- Baseline ID, product, version
- Associated blueprints, ADRs, policies
- Approved APIs, dependencies, data flows, topology
- Approved environments
- Last validation timestamp and status
Kanban-style board with columns:
- Detected → Under Review → Planned → In Remediation → Pending Validation → Resolved → Accepted Exception
Control center for exceptions:
- Exception ID, linked finding, reason
- Risk owner, expiration date
- Approval record and compensating controls
- Status and review schedule
DriftSummaryCards — KPI cards (total, critical, high, aging)
DriftSeverityChart — Severity distribution (pie/bar)
DriftTrendChart — Open vs resolved over time
DriftTypeDistribution — Drift type breakdown
DriftFindingsTable — Sortable/filterable findings table
DriftFindingDetailPanel — Full detail side panel or page
BaselineDiffViewer — Visual expected vs observed diff
PolicyEvaluationPanel — Policy evaluation results
EvidenceTimeline — Chronological evidence for a finding
RemediationKanban — Kanban board for remediation workflow
ExceptionApprovalPanel — Exception request and approval
ProductDriftHealthScore — Health score card per product
TenantDriftOverview — Cross-tenant drift summary
Findings table supports filtering by:
- Tenant, Product, Initiative
- Environment, Severity, Status
- Drift Type, Owner
- Policy, Gate, ADR, Blueprint
- Date range, Source
Each finding supports:
- Open detail
- Assign owner
- Change status
- Create remediation task
- Request Core re-evaluation
- Create ADR
- Link existing ADR
- Link blueprint
- Request approval
- Accept risk / create exception
- Mark false positive
- Add evidence
- Add comment
- Export report
- Open related initiative/product/gate
Evolith operates on a strategic Open-Core business model designed to drive developer adoption while capturing high-value enterprise IT spend.
The baseline architecture framework—Evolith Upstream (evolith_arch32)—is fully open-source. It provides the global engineering community with:
- Standardized architectural taxonomies, schemas, and templates.
- Baseline ruleset engines and local CLI validation utilities.
- Clean-architecture templates and patterns (such as the Ports & Adapters layouts).
Strategic Value: Developers, startups, and corporate architecture boards adopt evolith_arch32 to standardize their codebase topologies, write clear ADRs, and align their local development workflows. It acts as a frictionless developer-acquisition channel, establishing Evolith as the industry-standard taxonomy for AI-Native governance.
As organizations scale from small teams using open-source templates to large-scale enterprise deployments, they encounter operational complexity:
- Managing multi-tenant compliance and workspace segregation.
- Tracking real-time status across hundreds of repositories and team backlogs.
- Auditing phase gates and consolidating evidence for regulatory frameworks (e.g., SOC2, ISO).
- Orchestrating automated AI agents (like the Loop Engineer) safely across proprietary codebases.
Evolith Tracker is the commercial, multi-tenant B2B SaaS platform that solves these scale challenges. It wraps the open-source architecture foundations in an enterprise-grade operational plane:
[ Free Open-Core Hook ] [ Paid Enterprise SaaS ]
evolith_arch32 Evolith Tracker
------------------- ------------------
• Standard Taxonomies =======> • Automated SDLC Gates
• Local CLI Validator • Multi-Tenant Isolation (TenantID)
• ADR & Schema Templates • Centralized Evidence Graph
• UMS Roles & RACI Integration
• PPM Integrations (Meisterplan)
• Governed AI Agents (Loop Engineer)
By providing a clear upgrade path from a local, manually validated architecture setup to a fully automated, auditable governance control plane, Evolith transforms developer goodwill into enterprise software revenue.