Skip to content

QUICK_START.md

Latest commit

 

History

History
65 lines (45 loc) · 3.71 KB

QUICK_START.md

File metadata and controls

65 lines (45 loc) · 3.71 KB
Raw

Evolith Tracker: Quick Start

A five-minute path to a running platform, seeded demo data, and the mental model you need to read every screen.

For the full operational guide, see the User Manual.

1. What Evolith Tracker is

Evolith Tracker is an SDLC governance control plane with advisory technical-architecture support. It moves an initiative through a governed funnel — Intake, Discovery, Design, Construction, QA, Release, Done — and, where a governed code repository exists, asks the Evolith Core for an advisory architecture verdict.

2. The 60-second mental model: two planes of governance

Everything you see on screen belongs to one of two independent planes:

Plane Governs Needs a code repository / evolith.yaml?
1 - SDLC / process (always on) Phases, gates, control criteria, evidence, multi-PO approvals, audit No. It is the Tracker's own state machine.
2 - Technical-architecture conformance (opt-in) The Evolith Core evaluating a governed repository (its evolith.yaml plus code against the rulesets) Yes. Only when there is a satellite repository to evaluate.

The switch between them is the requiresCoreVerdict flag on a gate policy: false resolves the gate with evidence and approvals only; true additionally requires a Core verdict, which needs a satellite repository. A tenant that only runs business initiatives (no repositories) lives entirely in Plane 1 and never encounters an evolith.yaml.

3. Run the stack locally

# 1. Core services (advisory engine, MCP, agent runtime) and Postgres
#    are provided as containers (core-api on :3001, mcp on :3002,
#    agent-runtime on :3003, postgres on :5432).

# 2. Tracker API (BFF -> Core), from the repository root
cd src/apps/tracker-api
dotnet build
ASPNETCORE_ENVIRONMENT=Development \
ASPNETCORE_URLS=http://localhost:5100 \
AgentRuntime__ApiKey=local-dev-key \
dotnet run --project Tracker.Presentation

# 3. Tracker web (React 19 + Vite), in another shell
cd src
npm install
npx nx serve tracker-web   # http://localhost:4200

The dev-bypass auth provider is active by default, so no identity provider is required locally.

4. Seed coherent demo data

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

This populates three tenants (ACME - logistics, Globex - fintech, Initech - healthcare). Each gets products, gate policies, a tenant-intelligence configuration, PPM connectors, and roughly ten initiatives spread across the whole SDLC funnel via all three entry paths - with gate submissions, evidence, decisions and phase progressions driven through the real state machine. The script is idempotent (codes are prefixed SEED-).

5. First tour

  1. Open http://localhost:4200. Under dev-bypass you are a platform operator, so the top bar shows a tenant switcher - move between ACME, Globex and Initech to see each tenant's own funnel. A regular tenant sees only its own data, read-only.
  2. Strategic intake: initiatives arriving from a PPM, already funded. Run the advisory feasibility filter, then promote to Discovery.
  3. Opportunities: the pre-Discovery candidate register. Triage, then promote the strongest.
  4. Initiatives: the traceability axis - every initiative through its five SDLC phases.
  5. Gate governance: configure how each phase gate is governed (mode, required evidence, approver chain, and whether a Core verdict is mandatory).

6. Where to go next

  • User Manual - the full operating model: multi-tenancy, the funnel, gates and control criteria, evolith.yaml and satellites, and when the Core evaluation applies.
  • DECISIONS.md - accepted architecture decisions.
  • Master Index - complete documentation navigation.