# Developer Onboarding Technical Reference

**Source Advisories**:
- 01-Dec-2025 - Common Developers guides
- 29-Nov-2025 - StellaOps – Mid-Level .NET Onboarding (Quick Start)
- 30-Nov-2025 - Implementor Guidelines for Stella Ops
- 30-Nov-2025 - Standup Sprint Kickstarters

**Last Updated**: 2025-12-14

---

## 0. WHERE TO START (IN-REPO)

- `docs/README.md` (doc map and module dossiers)
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md` (end-to-end system model)
- `docs/18_CODING_STANDARDS.md` (C# conventions, repo rules, gates)
- `docs/19_TEST_SUITE_OVERVIEW.md` (test layers, CI expectations)
- `docs/technical/development/README.md` (developer tooling and workflows)
- `docs/10_PLUGIN_SDK_GUIDE.md` (plugin SDK + packaging)
- `LICENSE` (AGPL-3.0-or-later obligations)

## 1. CORE ENGINEERING PRINCIPLES

- **SOLID First**: Interface and dependency inversion required
- **100-line File Rule**: Files >100 lines must be split/refactored
- **Contracts vs Runtime**: Public DTOs/interfaces in `*.Contracts` projects
- **Single Composition Root**: DI wiring in `StellaOps.Web/Program.cs` and plugin `IoCConfigurator`
- **No Service Locator**: Constructor injection only
- **Fail-fast Startup**: Validate configuration before web host starts
- **Hot-load Compatibility**: Avoid static singletons that survive plugin unload

### 1.1 Product Non-Negotiables

- **Determinism first**: stable ordering + canonicalization; no hidden clocks/entropy in core algorithms
- **Offline-first**: no silent network dependency; every workflow has an offline/mirrored path
- **Evidence over UI**: the API + signed artifacts must fully explain what the UI shows
- **Contracts are contracts**: version schemas; add fields with defaults; never silently change semantics
- **Golden fixtures required**: any change to scanning/policy/proofs must be covered by deterministic fixtures + replay tests
- **Respect service boundaries**: do not re-implement scanner/policy logic in downstream services or UI

## 2. REPOSITORY LAYOUT RULES

- No "Module" folders or nested solution hierarchies
- Tests mirror `src/` structure 1:1
- No test code in production projects
- Feature folder layout: `Scan/ScanService.cs`, `Scan/ScanController.cs`

## 3. NAMING & STYLE CONVENTIONS

### 3.1 Namespaces & Files

- **Namespaces**: File-scoped, `StellaOps.*`
- **Classes/records**: PascalCase
- **Interfaces**: `I` prefix (`IScannerRunner`)
- **Private fields**: `camelCase` (no leading `_`)
- **Constants**: `SCREAMING_SNAKE_CASE`
- **Async methods**: End with `Async`

### 3.2 Usings

- Outside namespace
- Sorted
- No wildcards

## 4. C# FEATURE USAGE

- Nullable reference types enabled
- Use `record` for immutable DTOs
- Prefer pattern matching over long `switch` cascades
- `Span`/`Memory` only when measured as necessary
- Use `await foreach` instead of manual iterator loops

## 5. DI POLICY

### 5.1 Composition Root

- **One composition root** per process
- Plugins contribute via `[ServiceBinding]` or `IoCConfigurator : IDependencyInjectionRoutine`
- Default lifetime: **scoped**
- Singletons only for stateless, thread-safe helpers
- Never use service locator or manually build nested service providers

### 5.2 Service Binding Attributes

```csharp
[ServiceBinding(typeof(IMyContract), ServiceLifetime.Scoped)]
public class MyService : IMyContract
{
    // Implementation
}
```

### 5.3 Advanced DI Configuration

```csharp
public class MyPluginIoCConfigurator : IDependencyInjectionRoutine
{
    public void Configure(IServiceCollection services, IConfiguration config)
    {
        services.AddScoped<IMyContract, MyService>();
        services.Configure<MyOptions>(config.GetSection("MyPlugin"));
    }
}
```

## 6. ASYNC & THREADING

- All I/O is async; avoid `.Result` / `.Wait()`
- Library code uses `ConfigureAwait(false)`
- Control concurrency with channels or `Parallel.ForEachAsync`

## 7. TEST LAYERS

- **Unit**: xUnit
- **Property-based**: FsCheck
- **Integration**: API with Testcontainers, DB/merge with Mongo + Redis
- **Contracts**: gRPC breakage checks with Buf
- **Frontend**: Jest (unit), Playwright (e2e), Lighthouse (performance/a11y)
- **Non-functional**: k6 (load), Docker (chaos), dependency/license scanning, SBOM reproducibility

## 8. QUALITY GATES

- API unit test coverage ≥ ~85%
- API P95 latency ≤ ~120ms
- Δ-SBOM warm scan P95 ≤ ~5s
- Lighthouse perf ≥ ~90, a11y ≥ ~95

## 9. PLUGIN SYSTEM

### 9.1 Plugin Templates

```bash
dotnet new stellaops-plugin-schedule -n MyPlugin.Schedule
```

### 9.2 Plugin Publishing

- Publish signed artifacts to `src/backend/Stella.Ops.Plugin.Binaries/<MyPlugin>/`
- Backend verifies Cosign signature
- Enforces `[StellaPluginVersion]` compatibility
- Loads plugins in isolated `AssemblyLoadContext`s

### 9.3 Plugin Signing

```bash
dotnet publish -c Release -p:PublishSingleFile=true -o out
cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
```

## 10. POLICY DSL (stella-dsl@1)

### 10.1 Goals

- Deterministic
- Declarative
- Explainable
- Offline-friendly
- Reachability-aware

### 10.2 Structure

- One `policy` block per `.stella` file
- Contains: `metadata`, `profile` blocks, `rule` blocks, optional `settings`

### 10.3 Context Namespaces

- `sbom`
- `advisory`
- `vex`
- `env`
- `telemetry`
- `secret`
- `profile.*`

### 10.4 Helpers

- `normalize_cvss`
- `risk_score`
- `vex.any`
- `vex.latest`
- `sbom.any_component`
- `exists`
- `coalesce`

### 10.5 Rules

- Always include clear `because` when changing `status` or `severity`
- Avoid catch-all suppressions (`when true` + `status := "suppressed"`)
- Use `stella policy lint/compile/simulate` in CI
- Test in sealed (offline) mode

## 11. PR CHECKLIST

1. Use **Conventional Commit** prefixes (`feat:`, `fix:`, `docs:`)
2. Run `dotnet format` and `dotnet test` (both must be green)
3. Keep files within 100-line guideline
4. Update XML-doc comments for new public API
5. Update docs and JSON schema for contract changes
6. Ensure analyzers and CI jobs pass

## 12. ONBOARDING DETERMINISM REQUIREMENTS

- Use fixed seeds and pinned toolchain versions
- Avoid live network calls; prefer cached feeds/mirrors
- Note mirror paths in examples

## 13. SPRINT READINESS CHECKLIST

- Scanner regressions verification
- Postgres slice validation
- DSSE/Rekor sweep complete
- Pin tool versions in scripts

## 14. MODULE-SPECIFIC GUIDANCE

### 14.1 Scanner Module

- Reachability algorithms only in Scanner.WebService
- Cache lazy and keyed by deterministic inputs
- Output includes explicit evidence pointers
- UI endpoints expose reachability state in structured form

### 14.2 Authority Module

- Trust roots: pinned via out-of-band distribution
- Key rotation: maintain version history in trust store
- Revocation: maintain revoked_keys list in trust anchors

### 14.3 Excititor (VEX) Module

- VEX schema includes pointers to all upstream artifacts
- No duplication of SBOM/scan content inside VEX
- DSSE used as standard envelope type

### 14.4 Policy Module

- Facts and policies serialized separately
- Lattice code in allowed services only
- Merge strategies named and versioned
- Artifacts record which lattice algorithm used

### 14.5 Sbomer Module

- Emit SPDX 3.0.1 and CycloneDX 1.6 with stable ordering and deterministic IDs
- Persist raw bytes + canonical form; hash canonical bytes for digest binding
- Produce DSSE attestations for SBOM linkage and generation provenance

### 14.6 Feedser Module

- Treat every feed import as a versioned snapshot (URI + time + content hashes)
- Support deterministic export/import for offline bundles
- Imports are idempotent (same snapshot digest is a no-op)

### 14.7 Concelier Module

- Never mutate evidence; attach business context and build views only
- Never re-implement scanner/policy risk logic; consume signed decisions + proofs

### 14.8 UI / Console

- UI is an explainer and navigator; the evidence chain must be retrievable via API and export
- Any UI state must be reproducible from persisted evidence + graph revision identifiers

### 14.9 Zastava / Advisory AI

- AI consumes evidence graph IDs/digests; it is never a source of truth for vulnerability states
- Pipelines must never pass/fail based on AI text; enforcement is always policy + lattice + evidence
- Any AI output must reference evidence IDs and remain optional/offline-safe

## 15. COMMON PITFALLS & SOLUTIONS

### 15.1 Avoid

- ❌ Service Locator pattern
- ❌ Static mutable state
- ❌ Async void (except event handlers)
- ❌ Blocking on async code (.Result, .Wait())
- ❌ Non-deterministic ordering
- ❌ Hard-coded timestamps
- ❌ Environment variables in core algorithms

### 15.2 Prefer

- ✅ Constructor injection
- ✅ Immutable data structures
- ✅ async Task
- ✅ await or Task.Run for CPU-bound work
- ✅ Stable sorting with explicit comparers
- ✅ Explicit `asOf` parameters
- ✅ Configuration objects passed as parameters

## 16. DEBUGGING WORKFLOW

### 16.1 Local Development

```bash
# Run all services
docker-compose up -d

# Run specific service
dotnet run --project src/Scanner/StellaOps.Scanner.WebService

# Attach debugger
# Use VS Code launch.json or Visual Studio F5
```

### 16.2 Log Correlation

```csharp
using var activity = Activity.Current;
activity?.SetTag("scan.id", scanId);
_logger.LogInformation("Processing scan {ScanId}", scanId);
```

### 16.3 OpenTelemetry

```csharp
services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddAspNetCoreInstrumentation()
        .AddNpgsql()
        .AddOtlpExporter());
```

## 17. PERFORMANCE OPTIMIZATION

### 17.1 Database

- Use indexes for hot queries
- Batch inserts/updates
- Use `COPY` for bulk data
- Avoid N+1 queries

### 17.2 Memory

- Use `Span<T>` for hot paths
- Pool large objects
- Dispose `IDisposable` promptly
- Profile with dotMemory

### 17.3 Caching

- Cache deterministically (keyed by input hashes)
- Use distributed cache (Valkey/Redis) for shared state
- TTL appropriate to data volatility

## 18. SECURITY GUIDELINES

### 18.1 Input Validation

- Validate all user inputs
- Use allowlists, not denylists
- Sanitize for SQL, XSS, path traversal

### 18.2 Authentication & Authorization

- Never roll your own crypto
- Use standard protocols (OAuth2, OIDC)
- Implement principle of least privilege

### 18.3 Secrets Management

- Never commit secrets
- Use environment variables or KMS
- Rotate credentials regularly

## 19. DOCUMENTATION STANDARDS

### 19.1 XML Documentation

```csharp
/// <summary>
/// Scans the specified artifact for vulnerabilities.
/// </summary>
/// <param name="artifactId">The artifact identifier.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>Scan results with reachability analysis.</returns>
/// <exception cref="ArgumentNullException">If artifactId is null.</exception>
public Task<ScanResult> ScanAsync(string artifactId, CancellationToken ct);
```

### 19.2 Architecture Decision Records (ADRs)

```markdown
# ADR-XXX: Title

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What is the issue?

## Decision
What did we decide?

## Consequences
What are the implications?
```

## 20. CI/CD INTEGRATION

### 20.1 Build Pipeline

```yaml
stages:
  - restore
  - build
  - test
  - analyze
  - package
  - deploy
```

### 20.2 Required Checks

- Unit tests pass
- Integration tests pass
- Code coverage ≥85%
- No high/critical vulnerabilities
- SBOM generated
- Determinism tests pass

## 21. MIGRATION GUIDE

### 21.1 From .NET 8 to .NET 10

- Update `<TargetFramework>net10.0</TargetFramework>`
- Review breaking changes
- Update NuGet packages
- Test thoroughly

### 21.2 Database Migrations

```bash
# Create migration
dotnet ef migrations add MigrationName -p src/Module -s src/WebService

# Apply migration
dotnet ef database update -p src/Module -s src/WebService
```

---

**Document Version**: 1.0
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17