Setup Wizard - Repository Inventory

This document captures the current state of setup-related components in the Stella Ops codebase, providing evidence for the Setup Wizard design. It is an orientation map, not a mirror of source: each section points at the authoritative file(s) under src/. When this doc and the code disagree, the code wins — verify enum members, DTO fields, config keys, and endpoint signatures against the cited source before relying on a detail.

1. CLI Architecture

1.1 Framework & Entry Points

The CLI is built on System.CommandLine. Entry point src/Cli/StellaOps.Cli/Program.cs delegates to a central command factory; configuration and DI are wired by a bootstrapper; profiles support multiple environments.

1.2 Existing Admin Commands

stella admin groups management subcommands (policy, users, feeds, system). For the live subcommand tree and arguments, see src/Cli/StellaOps.Cli/Commands/Admin/AdminCommandGroup.cs.

1.3 Doctor Commands

stella doctor exposes run / list / export (diagnostic runs, check listing, evidence bundle). Flags such as run mode, category filter, and output format are defined in src/Cli/StellaOps.Cli/Commands/DoctorCommandGroup.cs — read it for the current flag set.

1.4 Configuration System

Priority resolution (highest → lowest), per CliBootstrapper.cs:

  1. Command-line arguments
  2. Environment variables (STELLAOPS_* prefix)
  3. Configuration files (appsettings.json / appsettings.yaml)
  4. Code defaults

Environment variables follow the STELLAOPS_* convention (backend/authority URLs, Postgres connection, offline-kit directory, etc.). The authoritative key set is the StellaOpsCliOptions binding in src/Cli/StellaOps.Cli/Configuration/StellaOpsCliOptions.cs.

2. Doctor System (Diagnostic Framework)

2.1 Core Engine

A registry/executor engine runs categorized checks. Core types: DoctorEngine, CheckRegistry, CheckExecutor, and models under src/__Libraries/StellaOps.Doctor/Engine/ and Models/.

2.2 Plugin System

Checks ship as category plugins (Core, Database, ServiceGraph, Security, Integration, Observability, Cryptography, Docker, AI, Notify). Each plugin is a StellaOps.Doctor.Plugins.<Category> (Notify is StellaOps.Doctor.Plugin.Notify) library. For the current plugin set and per-plugin check inventory, enumerate the StellaOps.Doctor.Plugins.* projects under src/__Libraries/ — do not trust a static count here, as checks are added frequently.

2.3 Doctor Web Service

A web service surfaces diagnostics over REST + a streaming endpoint, consumed by an Angular UI.

Endpoint shape (verify in DoctorEndpoints.cs): start a run, fetch run results by id, list available checks, and a WebSocket stream for live results, all under /api/v1/doctor/*.

2.4 Check ID Convention

Hierarchical, dotted: check.{category}.{subcategory}.{specific} (e.g. check.database.migrations.pending, check.integration.scm.github.auth).

3. Database & Migrations

3.1 Migration Framework

Startup-time runner with a hosted-service host; categories drive when/how each migration applies.

3.2 Migration Categories

Four categories, distinguished by file prefix and execution policy (see MigrationCategory.cs):

This forward-only policy is governed by ADR-004; recovery is by snapshot restore (see the migration-recovery runbook).

3.3 Schema Isolation (Per-Module)

Each module owns a Postgres schema and auto-migrates from embedded SQL on startup (repo invariant §2.7). Examples: Authority → authority, Concelier → vuln, Scheduler → scheduler, Notify → notify, Scanner → scanner, Attestor → attestor, Policy → policy, ReleaseOrchestrator → release. Migration SQL lives under each module’s *.Persistence/Migrations/ (Scanner: StellaOps.Scanner.Storage/Postgres/Migrations/). Treat src/ as the authority for the full module→schema map.

3.4 Existing CLI Commands

stella migrations-run --module <Module> --category <Category> [--dry-run] [--force] — see MigrationCommandService.cs for the live argument set.

4. Redis/Valkey Infrastructure

4.1 Connection Configuration

Valkey is the messaging/cache transport. Connection factory + options + plugin live in src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ (ValkeyConnectionFactory.cs, Options/ValkeyTransportOptions.cs, ValkeyTransportPlugin.cs).

4.2 Usage Patterns

Valkey backs several stores: message queues (Redis Streams + consumer groups), distributed cache (TTL), rate limiting (token bucket), idempotency, and DPoP nonces. Search the transport library and consumers for the concrete store types (Valkey*Store, RedisDpopNonceStore).

4.3 Health Checks

Connectivity check: src/__Libraries/StellaOps.Doctor.Plugins.ServiceGraph/Checks/ValkeyConnectivityCheck.cs. It probes the standard config keys (Valkey:ConnectionString, Redis:ConnectionString, and the ConnectionStrings:* equivalents) — see the file for the exact lookup order.

5. Integrations System

5.1 Core Architecture

A plugin-based integrations subsystem with its own web service, core models, contracts, and persistence under src/Integrations/ (StellaOps.Integrations.WebService/, __Libraries/StellaOps.Integrations.Core|.Contracts|.Persistence/).

5.2 Integration Types

IntegrationType is a banded enum (Registry 100s, SCM 200s, CI/CD 300s, RepoSource 400s, RuntimeHost 500s, FeedMirror 600s) covering registries, SCMs, CI systems, package sources, runtime agents, and feed mirrors. The authoritative member list is src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs.

5.3 Plugin Contract

Connectors implement IIntegrationConnectorPlugin (extends IAvailabilityPlugin): exposes Type/Provider and async TestConnectionAsync / CheckHealthAsync against an IntegrationConfig. Full signature: src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs.

5.4 Existing Plugins

Reference connectors live under src/Integrations/__Plugins/ (e.g. GitHub App, Harbor, InMemory). Enumerate that directory for the current set.

6. Notification System

6.1 Core Components

Notify has a web service plus engine, models, and queue libraries under src/Notify/ (StellaOps.Notify.WebService/, __Libraries/StellaOps.Notify.Engine|.Models|.Queue/).

6.2 Channel Types

Delivery channels (Slack, Teams, Email/SMTP, generic Webhook, incident tools, in-app inbox) are the NotifyChannelType enum in src/Notify/__Libraries/StellaOps.Notify.Models/NotifyEnums.cs (the NotifyChannel record itself is in NotifyChannel.cs). Read NotifyEnums.cs for the canonical member list.

6.3 Channel Configuration

NotifyChannelConfig carries a SecretRef (authref:// URI), optional Target/Endpoint, and a properties map. Definition: src/Notify/__Libraries/StellaOps.Notify.Models/NotifyChannel.cs.

7. Vault/Secrets System

7.1 Vault Connectors

Secret backends are pluggable connectors under src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/ (HashiCorpVaultConnector.cs, AzureKeyVaultConnector.cs, AwsSecretsManagerConnector.cs). Per repo policy (§1.5), HashiCorp Vault is the flagship/default; cloud-managed KMS connectors exist but must never be wired as defaults.

7.2 Secret Resolution

ITenantSecretResolver (extends ISecretResolver) scopes resolution per tenant and resolves vault paths by integration id. Contract: src/ReleaseOrchestrator/__Libraries/.../Plugin/Integration/ITenantSecretResolver.cs.

7.3 Credential Provider Schemes

Credentials are referenced by URI scheme — env://, file://, vault:// — resolved in src/ReleaseOrchestrator/__Agents/StellaOps.Agent.Core/Credentials/CredentialResolver.cs. See it for the exact scheme grammar.

8. Environment & Agent System

8.1 Environment Model

Environment models a pipeline stage (name, display name, order index, production flag, required approvals, separation-of-duties, optional auto-promote source). Full record: src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Environment/Models/Environment.cs.

8.2 Target Model (Deployment Target)

Target describes a deployment destination; target kinds include Docker host, Compose project, AWS ECS service, and Nomad job. Authoritative kinds: src/ReleaseOrchestrator/__Libraries/.../Environment/Models/Target.cs.

8.3 Agent Model

Agent carries identity, a Status lifecycle, a set of Capabilities (Docker/Compose/Ssh/WinRm), an mTLS certificate thumbprint, and heartbeat timestamps. Full record + enums: src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Agent/Models/Agent.cs.

8.4 Agent Registration

Registration uses short-lived one-time tokens with mTLS certificate issuance on join, plus heartbeat-based staleness detection. Logic: src/ReleaseOrchestrator/__Libraries/.../Agent/Registration/RegistrationTokenService.cs (token TTL, heartbeat/stale intervals defined there).

9. Existing Onboarding System

9.1 Platform Onboarding Service

A pre-existing onboarding flow (distinct from the setup wizard) tracks a fixed step sequence (connect scanner → configure policy → first scan → review findings → invite team) over GET status / POST complete/{step} / POST skip endpoints under /api/v1/platform/onboarding/*. Source of truth for steps + routes: src/Platform/StellaOps.Platform.WebService/Services/PlatformOnboardingService.cs.

9.2 Quickstart Documentation

Operator-facing entry docs: docs/quickstart.md, plus install/onboarding guides under docs/ (CLI quickstart, install guide, developer onboarding). Verify titles/paths in docs/ before linking.

10. UI Architecture

10.1 Angular Application

Standard Angular app rooted at src/Web/StellaOps.Web/src/app/ (app.component.ts, app.routes.ts, app.config.ts).

10.2 Existing Settings Pages

Reusable settings UIs already exist (AI preferences, environment settings, Trivy DB settings) under src/Web/StellaOps.Web/src/app/features/ — see settings/, release-jobengine/environments/, and trivy-db-settings/.

10.3 Wizard Reference Implementation

The SBOM Source Wizard is the canonical multi-step wizard pattern: signal-based state, per-step validation, connection testing, and conditional multi-form rendering. Reference: src/Web/StellaOps.Web/src/app/features/sbom-sources/components/source-wizard/source-wizard.component.ts.

11. Configuration Samples

Service config samples live under etc/ (concelier.yaml.sample, authority.yaml.sample); compose environment templates live under devops/compose/env/ (stellaops.env.example, regional compliance-*.env.example, testing.env.example, agent-core.env.example). Browse etc/*.sample and devops/compose/env/*.env.example for the full set.

12. Setup Wizard Backend (Platform Service)

12.1 API Endpoints

The Platform Service exposes setup-wizard endpoints under /api/v1/setup/*: session lifecycle (get/create/resume/finalize), step execution/skip, and step-definition listing. Handlers (with Problem+JSON errors) and exact routes: src/Platform/StellaOps.Platform.WebService/Endpoints/SetupEndpoints.cs.

12.2 Backend Components

12.3 Scopes and Authorization

Three setup scopes gate the API — platform.setup.read / .write / .admin, mapped to the SetupRead / SetupWrite / SetupAdmin policy constants in PlatformPolicies.cs. Note the repo gotcha (§1.5): policy names and scope claim values can diverge — confirm against PlatformPolicies.cs and the scope catalog (StellaOps.Auth.Abstractions/StellaOpsScopes.cs) rather than prose.

13. Gaps Identified

13.1 Missing Components

13.2 Partial Implementations

14. Key Architectural Patterns to Follow

  1. System.CommandLine for CLI commands
  2. Signal-based state in Angular components
  3. IOptions<T> with validation for configuration
  4. Plugin contracts for extensibility
  5. Doctor checks for health validation
  6. ITenantSecretResolverfor secret access
  7. HLC timestamps for audit ordering