Skip to content

PRODUCT_VISION.md

Latest commit

 

History

History
429 lines (322 loc) · 35.8 KB

PRODUCT_VISION.md

File metadata and controls

429 lines (322 loc) · 35.8 KB
Raw

Product Vision Manifest: EVOLITH TRACKER

Bilingual Navigation: English (this document) · Versión en Español

1. What is Evolith Tracker?

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.

2. Governed Composition

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.

3. The Architectural Pillars (The Engine)

  • 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.

4. Funnel 0 (Strategic Intake): The Strategic Entry Port

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.

4.1 Positioning: What Evolith Is Not

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.

4.2 Business Case Receiver

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.

4.3 The Handshake API: PPM ⇄ Evolith Integration Flow

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).

Step-by-Step Flow

  1. 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.

  2. 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.

  3. Baseline Anchoring (Funnel 0 → Evidence Graph): Upon successful ingestion, Funnel 0 creates a new Initiative aggregate, stamps an immutable baseline record in the Evidence Graph, and resolves the stakeholder list against the UMS identity provider. The initiative enters PENDING_FEASIBILITY state.

  4. 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.

  5. 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_ref referencing 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.

  6. 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_ref back 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.

4.4 Integration Sequence Diagram

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
Loading

Governance Note: Every state transition in Funnel 0 — from PENDING_FEASIBILITY to ADMITTED or REJECTED — 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.

5. The Value Stream: The 5 Modular Blocks

Tracker models the SDLC through 5 consecutive gates (Phase Gates), where it acts as the sole final authority to allow transitions:

  1. Discovery & Ideation Hub: Validate ROI and KPIs; ensure the proposed solution aligns with the "Build vs Compose" strategy.
  2. Architecture Spec-Driven (Design): Consolidate contracts (OpenAPI/AsyncAPI) and approved ADRs.
  3. Construction Tracking: Validate evidence from external repositories and CI/CD against design contracts (strict Architecture Drift control).
  4. Automated QA & Integration: Reception of test results, security, and deep integration via ports.
  5. Dynamic Release Planner: Command board for deployments. In case of a block, agents propose a contingency flow ("Re-Do") and a human authorizes.

6. The Analytical Brain (Scorecards)

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.

7. The Federated Governance Model: Hub-and-Spoke Architecture

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.

7.1 The Hub: Evolith Core as the Constitutional Authority

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.

7.2 The Spokes: Satellites and the Inheritance Contract

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.

7.3 The Anti-Corruption Layers: Ecosystem Integrity Enforcement

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:

Boundary 1: Evolith Core → Evolith Tracker

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.

Boundary 2: Upstream PPM (e.g., Meisterplan) → Evolith Funnel 0

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.

Boundary 3: External Providers → Evolith Tracker (Ports & Adapters)

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.

Boundary 4: Evolith Tracker → UMS (Identity Provider)

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.

7.4 The Feedback Loop: Satellites Inform Core

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.

7.5 Architecture Diagram: Hub-and-Spoke Ecosystem

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
Loading

7.6 Key Invariants Summary

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, never in the Core 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 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

8. Target Audience & User Personas

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 Delivery 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.

9. Value Proposition & Differentiators

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.

10. Managing Architecture Drift

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.

10.1 Proactive Enforcement Mechanisms

  1. 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.json manifest.
    • 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.

  2. Construction Tracking (Delivery 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 Delivery Gate fails, blocking code compilation or PR merging.

  3. 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_CLARIFICATION and halt phase progression.

10.2 Drift Enforcement Protocol

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.

11. Go-to-Market (GTM) & Open-Core Strategy

Evolith operates on a strategic Open-Core business model designed to drive developer adoption while capturing high-value enterprise IT spend.

11.1 The Hook: evolith_arch32 (Open Source)

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.

11.2 The Bridge: Operational Complexity

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.

11.3 The Monetization: Evolith Tracker (Enterprise SaaS)

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.