git.stella-ops.org/docs/setup/setup-wizard-inventory.md

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.

1. CLI Architecture

1.1 Framework & Entry Points

Component	Path	Description
CLI Entry	src/Cli/StellaOps.Cli/Program.cs	Main entry point using System.CommandLine
Command Factory	src/Cli/StellaOps.Cli/Commands/CommandFactory.cs	Central command registration (53+ command groups)
Bootstrapper	src/Cli/StellaOps.Cli/Configuration/CliBootstrapper.cs	Configuration loading and DI setup
Options	src/Cli/StellaOps.Cli/Configuration/StellaOpsCliOptions.cs	CLI configuration POCOs
Profile Manager	src/Cli/StellaOps.Cli/Configuration/CliProfile.cs	Multi-profile support

1.2 Existing Admin Commands

File: src/Cli/StellaOps.Cli/Commands/Admin/AdminCommandGroup.cs

Current stella admin subcommands:

• admin policy export|import|validate|list - Policy management
• admin users list|add|revoke|update - User management
• admin feeds list|status|refresh|history - Feed management
• admin system status|info - System health and info

1.3 Doctor Commands

File: src/Cli/StellaOps.Cli/Commands/DoctorCommandGroup.cs

stella doctor run [--mode quick|normal|full] [--category <cat>] [--format text|json|markdown]
stella doctor list [--category <cat>] [--verbose]
stella doctor export --output <path>.zip [--include-logs]

1.4 Configuration System

Priority Resolution (CliBootstrapper.cs):

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

Key Environment Variables:

• STELLAOPS_BACKEND_URL - Backend API URL
• STELLAOPS_AUTHORITY_URL - Authority service URL
• STELLAOPS_POSTGRES_CONNECTION - Database connection
• STELLAOPS_OFFLINE_KITS_DIRECTORY - Offline kit path

---

2. Doctor System (Diagnostic Framework)

2.1 Core Engine

Component	Path
Engine	src/__Libraries/StellaOps.Doctor/Engine/DoctorEngine.cs
Registry	src/__Libraries/StellaOps.Doctor/Engine/CheckRegistry.cs
Executor	src/__Libraries/StellaOps.Doctor/Engine/CheckExecutor.cs
Models	src/__Libraries/StellaOps.Doctor/Models/

2.2 Plugin System (9 Plugins, 48+ Checks)

Plugin	Path	Category	Checks
Core	StellaOps.Doctor.Plugins.Core	Core	9 checks (config, disk, memory, crypto)
Database	StellaOps.Doctor.Plugins.Database	Database	8 checks (connectivity, migrations, schema)
ServiceGraph	StellaOps.Doctor.Plugins.ServiceGraph	ServiceGraph	6 checks (gateway, Valkey)
Security	StellaOps.Doctor.Plugins.Security	Security	9 checks (OIDC, TLS, Vault)
Integration	StellaOps.Doctor.Plugins.Integration	Integration	8+ checks (GitHub, GitLab, registries)
Observability	StellaOps.Doctor.Plugins.Observability	Observability	4 checks (OTLP, metrics)
Cryptography	StellaOps.Doctor.Plugins.Cryptography	Cryptography	8+ checks (FIPS, eIDAS, HSM)
Docker	StellaOps.Doctor.Plugins.Docker	Docker	5 checks (daemon, network)
AI	StellaOps.Doctor.Plugins.AI	AI	4+ checks (LLM providers)
Notify	StellaOps.Doctor.Plugin.Notify	Notify	5 checks (email, Slack, webhooks)

2.3 Doctor Web Service

Component	Path
Web Service	src/Doctor/StellaOps.Doctor.WebService/
Endpoints	src/Doctor/StellaOps.Doctor.WebService/Endpoints/DoctorEndpoints.cs
Angular UI	src/Web/StellaOps.Web/src/app/features/doctor/

REST API:

• POST /api/v1/doctor/run - Start diagnostic run
• GET /api/v1/doctor/run/{runId} - Get run results
• GET /api/v1/doctor/checks - List available checks
• WebSocket /api/v1/doctor/stream - Real-time streaming

2.4 Check ID Convention

check.{category}.{subcategory}.{specific}

Examples:

• check.config.required
• check.database.migrations.pending
• check.integration.scm.github.auth
• check.services.valkey.connectivity

---

3. Database & Migrations

3.1 Migration Framework

Component	Path
Runner	src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationRunner.cs
Startup Host	src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/StartupMigrationHost.cs
Categories	src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationCategory.cs
CLI Service	src/Cli/StellaOps.Cli/Services/MigrationCommandService.cs

3.2 Migration Categories

Category	Prefix	Execution	Purpose
Startup	001-099	Automatic at boot	Schema creation (idempotent)
Release	100-199	Manual CLI	Breaking changes (blocks boot if pending)
Seed	S001-S999	Automatic at boot	Initial data (idempotent)
Data	DM001-DM999	Background jobs	Data migrations

3.3 Schema Isolation (Per-Module)

Module	Schema	Migration Path
Authority	authority	src/Authority/__Libraries/StellaOps.Authority.Persistence/Migrations/
Concelier	vuln	src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Migrations/
Scheduler	scheduler	src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Migrations/
Notify	notify	src/Notify/__Libraries/StellaOps.Notify.Persistence/Migrations/
Scanner	scanner	src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/
Attestor	attestor	src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Migrations/
Policy	policy	src/Policy/__Libraries/StellaOps.Policy.Persistence/Migrations/
ReleaseOrchestrator	release	src/ReleaseOrchestrator/__Libraries/.../Persistence/Migrations/

3.4 Existing CLI Commands

stella migrations-run --module <Module> --category <Category> [--dry-run] [--force]

---

4. Redis/Valkey Infrastructure

4.1 Connection Configuration

Component	Path
Primary Factory	src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyConnectionFactory.cs
Options	src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/Options/ValkeyTransportOptions.cs
Transport Plugin	src/Router/__Libraries/StellaOps.Messaging.Transport.Valkey/ValkeyTransportPlugin.cs

4.2 Usage Patterns

Usage	Component	Purpose
Message Queues	ValkeyMessageQueue	Redis Streams with consumer groups
Distributed Cache	ValkeyCacheStore	TTL-based caching
Rate Limiting	ValkeyRateLimitStore	Token bucket algorithm
Idempotency	ValkeyIdempotencyStore	Duplicate prevention
DPoP Nonces	RedisDpopNonceStore	Auth token security

4.3 Health Checks

File: src/__Libraries/StellaOps.Doctor.Plugins.ServiceGraph/Checks/ValkeyConnectivityCheck.cs

Configuration sources checked:

• Valkey:ConnectionString
• Redis:ConnectionString
• ConnectionStrings:Valkey
• ConnectionStrings:Redis

---

5. Integrations System

5.1 Core Architecture

Component	Path
Web Service	src/Integrations/StellaOps.Integrations.WebService/
Core Models	src/Integrations/__Libraries/StellaOps.Integrations.Core/
Contracts	src/Integrations/__Libraries/StellaOps.Integrations.Contracts/
Persistence	src/Integrations/__Libraries/StellaOps.Integrations.Persistence/

5.2 Integration Types

File: src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs

Type	Range	Examples
Registry	100-109	Harbor, ECR, GCR, ACR, Docker Hub, Quay
SCM	200-204	GitHub App, GitLab Server, Bitbucket, Gitea
CI/CD	300-306	GitHub Actions, GitLab CI, Jenkins, Argo
RepoSource	400-405	npm, PyPI, Maven, NuGet, Crates.io
RuntimeHost	500-502	eBPF Agent, ETW Agent
FeedMirror	600-602	StellaOps Mirror, NVD, OSV

5.3 Plugin Contract

File: src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs

public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
{
    IntegrationType Type { get; }
    IntegrationProvider Provider { get; }
    Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct);
    Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct);
}

5.4 Existing Plugins

Plugin	Path
GitHub App	src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/
Harbor	src/Integrations/__Plugins/StellaOps.Integrations.Plugin.Harbor/
InMemory	src/Integrations/__Plugins/StellaOps.Integrations.Plugin.InMemory/

---

6. Notification System

6.1 Core Components

Component	Path
Web Service	src/Notify/StellaOps.Notify.WebService/
Engine	src/Notify/__Libraries/StellaOps.Notify.Engine/
Models	src/Notify/__Libraries/StellaOps.Notify.Models/
Queue	src/Notify/__Libraries/StellaOps.Notify.Queue/

6.2 Channel Types

File: src/Notify/__Libraries/StellaOps.Notify.Models/NotifyChannel.cs

• Slack - Incoming webhooks
• Teams - Incoming webhooks
• Email - SMTP
• Webhook - Generic HTTP POST
• PagerDuty / OpsGenie - Incident management
• InApp - In-application inbox

6.3 Channel Configuration

public sealed record NotifyChannelConfig
{
    public string SecretRef { get; }      // authref:// URI
    public string? Target { get; }        // Channel/email list
    public string? Endpoint { get; }      // Webhook URL
    public ImmutableDictionary<string, string> Properties { get; }
}

---

7. Vault/Secrets System

7.1 Vault Connectors

Connector	Path
HashiCorp Vault	src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/HashiCorpVaultConnector.cs
Azure Key Vault	src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AzureKeyVaultConnector.cs
AWS Secrets Manager	src/ReleaseOrchestrator/__Libraries/.../Connectors/Vault/AwsSecretsManagerConnector.cs

7.2 Secret Resolution

File: src/ReleaseOrchestrator/__Libraries/.../Plugin/Integration/ITenantSecretResolver.cs

public interface ITenantSecretResolver : ISecretResolver
{
    ITenantSecretResolver ForTenant(Guid tenantId);
    Task<string?> ResolveFromVaultAsync(Guid integrationId, string secretPath, CancellationToken ct);
}

7.3 Credential Provider Schemes

File: src/ReleaseOrchestrator/__Agents/StellaOps.Agent.Core/Credentials/CredentialResolver.cs

• env://VAR_NAME - Environment variable
• file:///path/to/secret - File system
• vault://integration-id/path - Vault lookup

---

8. Environment & Agent System

8.1 Environment Model

File: src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Environment/Models/Environment.cs

public sealed record Environment
{
    public Guid Id { get; init; }
    public Guid TenantId { get; init; }
    public string Name { get; set; }           // "dev", "staging", "prod"
    public string DisplayName { get; set; }
    public int OrderIndex { get; init; }       // Pipeline order
    public bool IsProduction { get; init; }
    public int RequiredApprovals { get; set; }
    public bool RequireSeparationOfDuties { get; set; }
    public Guid? AutoPromoteFrom { get; set; }
}

8.2 Target Model (Deployment Target)

File: src/ReleaseOrchestrator/__Libraries/.../Environment/Models/Target.cs

Target Type	Description
DockerHost	Docker Engine
ComposeHost	Docker Compose project
EcsService	AWS ECS service
NomadJob	HashiCorp Nomad job

8.3 Agent Model

File: src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Agent/Models/Agent.cs

public sealed record Agent
{
    public Guid Id { get; init; }
    public string Name { get; init; }
    public AgentStatus Status { get; set; }    // Pending, Active, Inactive, Stale, Revoked
    public AgentCapability[] Capabilities { get; init; }  // Docker, Compose, Ssh, WinRm
    public string? CertificateThumbprint { get; set; }    // mTLS
    public DateTimeOffset? LastHeartbeatAt { get; set; }
}

8.4 Agent Registration

File: src/ReleaseOrchestrator/__Libraries/.../Agent/Registration/RegistrationTokenService.cs

• One-time tokens with 24-hour expiry
• mTLS certificate issuance on registration
• Heartbeat monitoring (30-second intervals, 90-second stale timeout)

---

9. Existing Onboarding System

9.1 Platform Onboarding Service

File: src/Platform/StellaOps.Platform.WebService/Services/PlatformOnboardingService.cs

Default Steps:

1. connect-scanner
2. configure-policy
3. first-scan
4. review-findings
5. invite-team

Endpoints:

• GET /api/v1/platform/onboarding/status
• POST /api/v1/platform/onboarding/complete/{step}
• POST /api/v1/platform/onboarding/skip

9.2 Quickstart Documentation

Document	Path
Quickstart	docs/quickstart.md
CLI Quickstart	docs/CONCELIER_CLI_QUICKSTART.md
Install Guide	docs/INSTALL_GUIDE.md
Developer Onboarding	docs/DEVELOPER_ONBOARDING.md

---

10. UI Architecture

10.1 Angular Application

Component	Path
Root	src/Web/StellaOps.Web/src/app/app.component.ts
Routes	src/Web/StellaOps.Web/src/app/app.routes.ts
Config	src/Web/StellaOps.Web/src/app/app.config.ts

10.2 Existing Settings Pages

Page	Path
AI Preferences	src/Web/StellaOps.Web/src/app/features/settings/ai-preferences.component.ts
Environment Settings	src/Web/StellaOps.Web/src/app/features/release-orchestrator/environments/components/environment-settings/
Trivy DB Settings	src/Web/StellaOps.Web/src/app/features/trivy-db-settings/

10.3 Wizard Reference Implementation

SBOM Source Wizard (6-step multi-form wizard):

File: src/Web/StellaOps.Web/src/app/features/sbom-sources/components/source-wizard/source-wizard.component.ts

Features:

• Signal-based state management
• Step-by-step validation
• Connection testing
• Multi-form with conditional rendering
• TypeScript 1204 lines

---

11. Configuration Samples

Sample	Path
Concelier	etc/concelier.yaml.sample
Authority	etc/authority.yaml.sample
Docker Compose	devops/compose/dev.env.example
Air-gap	devops/compose/airgap.env.example

---

12. Setup Wizard Backend (Platform Service)

12.1 API Endpoints

The Platform Service now exposes setup wizard endpoints at /api/v1/setup/*:

Endpoint	Method	Description
/api/v1/setup/sessions	GET	Get current setup session for tenant
/api/v1/setup/sessions	POST	Create new setup session
/api/v1/setup/sessions/resume	POST	Resume existing or create new session
/api/v1/setup/sessions/finalize	POST	Finalize setup session
/api/v1/setup/steps/execute	POST	Execute a setup step
/api/v1/setup/steps/skip	POST	Skip an optional setup step
/api/v1/setup/definitions/steps	GET	List all step definitions

12.2 Backend Components

Component	Path	Description
Contracts	src/Platform/StellaOps.Platform.WebService/Contracts/SetupWizardModels.cs	Step definitions, session state, API models
Service	src/Platform/StellaOps.Platform.WebService/Services/PlatformSetupService.cs	Session management, step execution, Doctor integration
Store	src/Platform/StellaOps.Platform.WebService/Services/PlatformSetupService.cs	In-memory tenant-scoped session store
Endpoints	src/Platform/StellaOps.Platform.WebService/Endpoints/SetupEndpoints.cs	HTTP endpoint handlers with Problem+JSON errors
Policies	src/Platform/StellaOps.Platform.WebService/Constants/PlatformPolicies.cs	Setup-specific authorization policies

12.3 Scopes and Authorization

Scope	Policy	Usage
platform.setup.read	SetupRead	Read session state and step definitions
platform.setup.write	SetupWrite	Create/resume sessions, execute/skip steps
platform.setup.admin	SetupAdmin	Admin operations (list all sessions)

---

13. Gaps Identified

13.1 Missing Components

Gap	Description
stella setup command	No dedicated interactive setup command exists
First-run detection	No blocking wizard on first launch
Wizard UI wiring	UI mock exists, needs wiring to backend endpoints
Doctor integration	Backend service has placeholder, needs real Doctor calls

13.2 Partial Implementations

Component	Current State	Gap
Setup Service	In-memory store	Postgres persistence not implemented
Doctor checks	48+ checks exist	Step execution uses mock pass results
Migrations	Automatic at startup	No interactive verification step
Integrations	Plugin architecture exists	No default suggestion logic

---

14. Key Architectural Patterns to Follow

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