# 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`

```bash
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

```bash
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`

```csharp
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

```csharp
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`

```csharp
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`

```csharp
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`

```csharp
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<T> 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