Search/AdvisoryAI and DAL conversion to EF finishes up. Preparation for microservices consolidation.
This commit is contained in:
master
@@ -600,4 +600,126 @@ This document is living. Improve it by:
|
||||
Never try to build test large amount of projects at the same time. This leads to memory exhausting. Solutions like src/StellaOps.sln has > 1000 projects.
|
||||
Always set to build minimum projects at parallel.
|
||||
|
||||
---
|
||||
|
||||
## 15. Module Creation Gate
|
||||
|
||||
### 15.1 Canonical domain roots (post-consolidation baseline)
|
||||
|
||||
The following top-level directories under `src/` are the approved domain roots after the 2026 domain-first consolidation (Sprints 200-220). No new top-level `src/` directory may be created without passing the gate in 15.2.
|
||||
|
||||
| Domain root | Domain scope | Absorbed modules (post-consolidation) |
|
||||
|---|---|---|
|
||||
| `src/AdvisoryAI/` | AI-assisted advisory chat and unified knowledge search | — |
|
||||
| `src/Attestor/` | Trust domain: attestation evidence, signing, provenance | Signer, Provenance |
|
||||
| `src/Authority/` | Identity domain: OAuth/OIDC, issuer directory, tenant management | IssuerDirectory |
|
||||
| `src/BinaryIndex/` | Binary artifact indexing and symbol resolution | Symbols |
|
||||
| `src/Concelier/` | Advisory ingestion domain: feed aggregation, excititor, proof service | Feedser, Excititor |
|
||||
| `src/Cryptography/` | Crypto plugin host and regional implementations (FIPS, GOST, SM, eIDAS) | — |
|
||||
| `src/Doctor/` | Platform health diagnostics | — |
|
||||
| `src/EvidenceLocker/` | Long-term evidence retention and legal hold | — |
|
||||
| `src/ExportCenter/` | Offline distribution domain: export, mirror, air-gap | Mirror, AirGap |
|
||||
| `src/Findings/` | Findings domain: risk engine, vulnerability explorer | RiskEngine, VulnExplorer |
|
||||
| `src/Graph/` | Knowledge graph indexing | — |
|
||||
| `src/Integrations/` | SCM/CI/registry/secrets plugin host | Extensions |
|
||||
| `src/Notify/` | Notification domain | Notifier |
|
||||
| `src/Orchestrator/` | Orchestration domain: scheduling, task execution, packs registry | Scheduler, TaskRunner, PacksRegistry |
|
||||
| `src/Platform/` | Console backend and cross-service aggregation | — |
|
||||
| `src/Policy/` | Policy domain: policy engine, unknowns handling | Unknowns |
|
||||
| `src/ReachGraph/` | Reachability graph analysis | — |
|
||||
| `src/ReleaseOrchestrator/` | Core release control plane (the product's primary capability) | — |
|
||||
| `src/Remediation/` | Remediation workflow tracking | — |
|
||||
| `src/Scanner/` | Fact collection domain: scanning, cartography, SBOM generation | Cartographer, SbomService |
|
||||
| `src/Signals/` | Runtime instrumentation and signal processing | RuntimeInstrumentation |
|
||||
| `src/Telemetry/` | Observability stack | — |
|
||||
| `src/Timeline/` | Timeline indexing and event aggregation | TimelineIndexer |
|
||||
| `src/Tools/` | Internal tooling: bench, verifier, SDK, dev portal | Bench, Verifier, Sdk, DevPortal |
|
||||
| `src/VexLens/` | VEX domain: adjudication, VexHub aggregation | VexHub |
|
||||
| `src/Web/` | Frontend SPA (Angular) | — |
|
||||
| `src/Cli/` | CLI tool | — |
|
||||
| `src/__Libraries/` | Shared cross-domain libraries (including crypto plugins: SmRemote, CryptoPro, Zastava) | — |
|
||||
| `src/__Tests/` | Shared cross-domain test infrastructure | — |
|
||||
|
||||
### 15.2 New module creation gate (mandatory)
|
||||
|
||||
A new top-level `src/` directory may only be created when ALL of the following conditions are met:
|
||||
|
||||
1. **Domain analysis required.** Written justification proving the new module cannot be a subdomain of an existing domain root (15.1). Must reference the architecture overview (`docs/modules/platform/architecture-overview.md`) and explain why every candidate parent domain is insufficient. This analysis must appear in a sprint file.
|
||||
|
||||
2. **Bounded context evidence.** The proposed module has a distinct bounded context with:
|
||||
- Its own data ownership — PostgreSQL schema(s) that no other domain needs to write to.
|
||||
- Its own deployable runtime identity — a WebService or Worker with a separate Docker image.
|
||||
- No tight coupling to an existing domain's internal models (no `ProjectReference` to another domain's `.Persistence` project).
|
||||
|
||||
3. **Five-year maintenance test.** Justify why the module will still be a separate concern in five years. If the capability is likely to merge into an existing domain as the product matures, it must start as a subdomain under that domain's root now. The consolidation from ~60 to ~33 modules happened because this test was not applied at creation time.
|
||||
|
||||
4. **Sprint and review gate.** The creation must be tracked in a sprint file (`docs/implplan/SPRINT_*.md`) with explicit task, completion criteria, and documented review approval. The sprint must be approved before the directory is created.
|
||||
|
||||
5. **Minimum documentation.** The new module must ship with:
|
||||
- `src/<Module>/AGENTS.md` — module-local agent contract
|
||||
- `docs/modules/<module>/architecture.md` — architecture dossier
|
||||
- An entry in `docs/INDEX.md` (or its successor)
|
||||
- An update to this section's canonical domain list (15.1)
|
||||
|
||||
Enforcement: PRs that create new `src/` top-level directories without a linked sprint task demonstrating all five conditions will be rejected.
|
||||
|
||||
### 15.3 Subdomain expansion (lighter gate)
|
||||
|
||||
Adding a new library, worker, or service project within an existing domain root (e.g., `src/Scanner/StellaOps.Scanner.NewCapability/`) requires only:
|
||||
- A sprint task documenting the addition and its purpose.
|
||||
- An update to the domain's `AGENTS.md`.
|
||||
- Adherence to the domain's existing naming conventions and persistence contracts.
|
||||
|
||||
This gate is lighter than 15.2 because subdomain expansion does not fragment the domain model.
|
||||
|
||||
---
|
||||
|
||||
## 16. Domain ownership and boundary rules
|
||||
|
||||
### 16.1 Single database, schema isolation
|
||||
|
||||
All services share the PostgreSQL database `stellaops_platform` at the configured database host. Domain isolation is enforced through PostgreSQL schemas, not separate databases. This is an architectural invariant chosen for operational simplicity (one backup target, one connection pool, one migration pipeline).
|
||||
|
||||
Rules:
|
||||
- Each domain owns one or more PostgreSQL schemas (e.g., `vuln`, `vex_raw`, `proofchain`, `scheduler`).
|
||||
- Schema ownership is documented in the domain's architecture dossier (`docs/modules/<domain>/architecture.md`).
|
||||
- No service may write to schemas owned by another domain. Cross-domain data access uses HTTP/gRPC APIs, never direct writes to another domain's tables.
|
||||
- Read access to another domain's schema is permitted only through documented, versioned views or explicit cross-domain query contracts recorded in both domains' architecture docs.
|
||||
|
||||
### 16.2 DbContext ownership
|
||||
|
||||
Each domain owns its EF Core DbContext(s). Rules:
|
||||
- A DbContext must map only to schemas owned by its domain.
|
||||
- Multiple DbContexts within a domain are permitted when there is a documented security, isolation, or lifecycle reason (e.g., Authority separates key material from session data; Attestor separates signer keys from attestation evidence). The reason must be recorded in the domain's architecture dossier.
|
||||
- DbContext consolidation within a domain (merging two contexts that map to the same domain's schemas) is permitted through a sprint task. It requires compiled model regeneration and targeted integration tests.
|
||||
- DbContext consolidation across domains is prohibited. If two domains need to share data, they must use APIs.
|
||||
|
||||
### 16.3 EF compiled model discipline
|
||||
|
||||
EF compiled models are committed to the repository (required for offline-first and air-gap deployments). Rules:
|
||||
- Compiled models live under `<Persistence-Project>/EfCore/CompiledModels/`.
|
||||
- After any entity mapping, schema, or DbContext change, the compiled model must be regenerated using `dotnet ef dbcontext optimize`.
|
||||
- The `.csproj` must include a `<Compile Remove>` entry for `CompiledModels/*AssemblyAttributes.cs` to prevent duplicate assembly attribute errors at build time.
|
||||
- Compiled model regeneration must be an explicit completion criterion in any sprint task that modifies entity mappings, adds entities, or merges DbContexts.
|
||||
|
||||
### 16.4 Cross-domain dependency rules
|
||||
|
||||
Allowed patterns:
|
||||
- Domain A's WebService calls Domain B's public HTTP/gRPC API. This is a runtime dependency, documented in both domains' architecture docs.
|
||||
- Domain A references Domain B's `.Client` library (a thin API client package). The `.Client` library is owned and published by Domain B.
|
||||
- Shared libraries under `src/__Libraries/` provide cross-domain utilities (e.g., `StellaOps.Infrastructure.Postgres`, `StellaOps.Cryptography`). These must not contain domain-specific business logic.
|
||||
|
||||
Prohibited patterns:
|
||||
- Domain A references Domain B's `.Persistence` project directly (this couples A's code to B's internal schema model).
|
||||
- Domain A writes to Domain B's PostgreSQL schema directly (bypasses B's business rules and audit controls).
|
||||
- A shared library under `src/__Libraries/` depends on a domain-specific project (creates hidden coupling).
|
||||
|
||||
Enforcement: PRs introducing new `ProjectReference` edges from one domain to another domain's `.Persistence` or internal-only projects will be rejected with a pointer to this section.
|
||||
|
||||
### 16.5 Schema migration ownership
|
||||
|
||||
- Each domain owns its SQL migration scripts (typically under the persistence project's `Migrations/` directory).
|
||||
- Migrations must be idempotent and deterministic (replay-safe for offline/air-gap environments).
|
||||
- Cross-domain migrations are prohibited. If a schema change in Domain A affects consumers in Domain B, Domain A publishes the migration; Domain B updates its read contracts or API integration independently.
|
||||
- Migration version numbering follows the pattern established per domain and must be monotonically increasing.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user