Skip to content

USER_MANUAL.md

Latest commit

 

History

History
116 lines (68 loc) · 10.5 KB

USER_MANUAL.md

File metadata and controls

116 lines (68 loc) · 10.5 KB
Raw

Evolith Tracker: User Manual

The operating model of the platform: what it governs, how the SDLC funnel works, how gates and control criteria are configured, and exactly when a governed repository and its evolith.yaml come into play.

New here? Start with the Quick Start.

1. Scope

Evolith Tracker is an SDLC governance control plane with advisory technical-architecture support. Its unit of governance is the Initiative; it does not manage implementation detail (tasks, backlogs, user stories, epics). Products, tenants and initiatives are governance context, never entities inside the Core - the Core is a stateless evaluation engine that receives an evaluation context and returns a result.

2. The two planes of governance

This is the single most important idea in the platform. Governance is delivered on two independent planes.

Plane 1 - SDLC / process governance (always on)

Phases, gates, control criteria, evidence, multi-PO approvals and audit. This is the Tracker's own state machine and it applies to every tenant and initiative. It requires no code repository and no evolith.yaml. Most governance value lives here.

Plane 2 - Technical-architecture conformance (opt-in)

The Evolith Core evaluates a governed repository (a "satellite") against the rulesets, reading the repository's evolith.yaml to know what it is evaluating. This plane only engages when there is a satellite to evaluate.

The switch

Each gate policy carries a requiresCoreVerdict flag:

  • requiresCoreVerdict: false (the default) - the gate is resolved by evidence plus approvals. The Core is never called; no evolith.yaml is needed.
  • requiresCoreVerdict: true - the gate additionally requires a passing Core verdict. This only makes sense for an initiative whose product points at a satellite repository.

A tenant that runs only business initiatives, with no governed repositories, operates entirely on Plane 1 and never sees an evolith.yaml. Turning on Plane 2 is a per-gate decision, made where technical-architecture conformance actually matters (typically the Design and Construction gates of software initiatives).

3. Multi-tenancy

This is a multi-tenant SaaS: a tenant sees only its own information. Every operational surface is scoped to the authenticated tenant; the tenant name is shown read-only in the top chrome, never a raw identifier.

The single exception is a platform operator (for example Evolith Platform - root), which holds a cross-tenant capability and may switch the tenant it operates on via the top-bar switcher. The backend enforces this: an override to another tenant is accepted only for a principal holding the platform capability; any other cross-tenant attempt is rejected. Under the local dev-bypass provider every session is a platform operator, which is why the switcher appears locally.

4. The SDLC funnel and the three entry paths

An initiative flows through: Intake -> Discovery -> Design -> Construction -> QA -> Release -> Done. Phase names are lowercase in the API (discovery, design, construction, qa, release, done). Phase order is enforced - a later gate stays not-ready until the earlier gates are approved.

Initiatives enter by one of three paths, and all three converge on the same rich Discovery initiative:

  1. Strategic intake - the initiative arrives from a PPM, already funded and prioritized, with its business case asserted. Run the advisory feasibility filter, then promote to Discovery. (The Tracker is a receiver here; it never recomputes the business case.)
  2. Opportunity - a pre-Discovery candidate captured with useful context (problem, expected value, estimated size, sponsor, target product, strategic theme). Triage it, then promote the strongest into an initiative so the promoted initiative is seeded rather than empty.
  3. Manual - create the initiative directly with its full Discovery detail.

The initiative type is derived from product scope: zero products -> tenant-wide; one -> single-product; two or more -> cross-product. Type drives which gate criteria and per-product facets apply.

5. Gates and control criteria

Gate governance is a configurable engine with three parts:

  • Gate policy (configuration, per tenant and phase) - the control criteria: gate mode, required evidence, approver chain, and whether a Core verdict is mandatory (requiresCoreVerdict). Configure these on the Gate governance screen.
  • Gate submission (process, per initiative and phase) - a request to pass a gate, carrying evidence and moving through decisions. RETURNED is non-terminal and reworkable; only APPROVED and REJECTED are terminal.
  • Evidence and approvals - evidence records are attached and verified; the approver chain is derived from the initiative type and product ownership, and each required approver decides.

For the discovery and design gates the submission is created directly; for construction, QA and release the phase artifacts are completed and the gate auto-attaches the complete artifact items as evidence. Approving a gate advances the phase progression.

6. evolith.yaml and satellites

What it is

evolith.yaml is the manifest of a governed repository (a satellite), living at the repository root. It declares what the repository is and how it is governed:

{
  "coreRef":    { "version": "1.0.0", "path": "../evolith" }, // which Core governs it
  "governance": { "version": "1.0.0" },
  "product":    { "name": "checkout", "type": "enterprise-application", "phase": "phase-0" },
  "tools":      { "runtime": "nodejs", "architecture": "clean", "database": "postgresql", "api": "rest", "ci": "github" }
}

The Core reads it to know what it is evaluating. Its ruleset validator requires the manifest at the satellite root (rule GOV-000; the OPA contract SVC-01); without it the Core reports a blocking "Missing evolith.yaml" violation.

Does each product need one?

evolith.yaml is per governed repository, not per product in the abstract. A product needs one manifest for each governed repository it owns - usually one product maps to one repository and one manifest, but a product may span several repositories (each its own satellite) or use a monorepo (a single manifest at the root). A product with no repository yet - an idea in Discovery, or a non-software initiative - has none and needs none, because there is no code for the Core to evaluate.

The Product aggregate already models RepositoryUrl (and Topology): that repository URL is the pointer to the satellite.

What about products and tenants without satellites?

They keep full governance - Plane 1 covers them completely. Their gates simply run with requiresCoreVerdict: false and never call the Core, so an evolith.yaml is never involved. Nothing is missing and nothing breaks: architecture conformance is an advisory layer that plugs in only where governed code exists.

7. The advisory Core evaluation

Beyond gate conformance, the Core provides advisory support that the Tracker surfaces:

  • Topology recommendation and design blueprint maturity - computed from the initiative's own Tracker data (blueprint facets). These do not require a satellite.
  • Repository conformance - the deeper check that evaluates a satellite's evolith.yaml plus sources against the rulesets. This is the only layer that requires a satellite.

The Tracker builds the context; the Core evaluates what it receives. The Tracker connects to a product's satellite repository using the per-product repository access (URL + encrypted credentials), reads the manifest and a curated set of sources and docs, assembles them into an inline evaluation context, and sends that context to the Core. The Core receives opaque tenant/product/initiative identifiers plus the assembled content, and evaluates the received content - it does not clone, read a filesystem, resolve a workspaceRef to a path, or touch the network. It stays stateless.

Concretely: configure a product's repository access (Products -> a product -> Repository access), then POST /api/products/{id}/evaluate-architecture. The Tracker fetches the repo via the provider API (GitHub first), builds evaluationInput.files (including evolith.yaml), and posts it to the Core, which mounts those files as the satellite in memory and runs the same rulesets. If the repo has no evolith.yaml, the Core returns a genuine advisory result reporting the missing manifest (GOV-000). Each run is recorded as a Core evaluation transaction. (The legacy workspaceRef/satellitePath inputs remain supported for backward compatibility, but inline content is the canonical path.)

8. Products, opportunities and tenant configuration

  • Products - the catalog; each product carries a topology, a repository URL (its satellite pointer) and an owner. A product code is unique within a tenant.
  • Opportunities - the pre-Discovery candidate register, capturing lightweight but useful context so a promoted opportunity seeds a rich initiative. An opportunity code is unique within a tenant.
  • Tenant intelligence - each tenant's own governance configuration: model routing, corpus references, agent registrations and settings. This is a configuration surface, kept separate from data and process surfaces.
  • Connectors (PPM intake) - registered per tenant, in the tenant's own parameters, feeding the Strategic intake.
  • Regionalization & localization - the tenant's country, locale, currency and time zone drive money and date formatting. These are moving from free-text fields to validated master catalogs (countries, territorial hierarchies with official codes/ubigeo, ISO 4217 currencies, IANA time zones), so a user selects valid values instead of typing them. This lives in the Geo / master-data bounded context (geo schema), accessed only through the IMasterDataDirectory port and designed to be extracted later as a shared evolith_mms service. See T-032 and the Geo diagram.

9. Seeding demo data

node src/apps/tracker-api/seed/seed-e2e.mjs

Populates three coherent tenants across the whole funnel (see the Quick Start for details). Use it to explore complete flows - phases, artifacts, control criteria, gate submissions, evidence and configurations - and, for a platform operator, to compare tenants side by side through the top-bar switcher.

10. Running locally

See the Quick Start, section 3, and the "Local development commands" block in the repository README.