sdl-knowledge

# SDL Knowledge ## Identity You understand the Solution Design Language (SDL) — a YAML-based architecture specification format used by arch0 to capture complete system designs. SDL transforms raw requirements into a validated, normalized intermediate representation that drives deterministic artifact generation. ## Core Principle SDL sits between requirements gathering and artifact generation. The manifest captures *what the user said*. SDL transforms that into *what the system will build* — with smart defaults filled in, incompatibilities caught, and warnings surfaced. --- ## What SDL Is SDL is a machine-readable YAML specification. This plugin uses the `v1.1` path for architecture workflows. Older `v0.1` material should be treated as obsolete and upgraded rather than reused for new generation. - Solution metadata and stage (MVP / Growth / Enterprise) - Product personas and core user flows - Architecture style and project structure (frontend, backend, mobile) - Authentication strategy and provider - Data layer (databases, cache, queues, search, storage) - Third-party integrations (payments, email, SMS, analytics, monitoring, CDN) - Non-functional requirements (availability, scaling, security, compliance) - Deployment configuration (cloud, runtime, networking, CI/CD, IaC) - Constraints (budget, team, timeline, compliance, existing infrastructure) - Inter-service communication patterns, configuration strategy, and error handling - Testing, observability, technical debt, and evolution roadmap - Artifact generation preferences ## When to Generate SDL Generate SDL **after** requirements gathering and manifest building (Step 3), **before** deliverable generation (Step 4). SDL is Step 3.5 in the blueprint lifecycle. ## SDL Version Version policy: - Use `v1.1` for all new SDL generation in this plugin. - Treat `v0.1` as obsolete input that should be upgraded before use. --- ## SDL Schema See `references/sdl-schema.md` for the complete field-by-field schema reference with all enum values. ### Required Root Sections | Section | Key Required Fields | |---------|-------------------| | `sdlVersion` | Must be `"1.1"` | | `solution` | `name`, `description`, `stage` | | `architecture` | `style`, `projects` | | `data` | `primaryDatabase.type`, `primaryDatabase.hosting` | | `product` | Core section carried forward into v1.1, include when user/persona context is known | | `auth` | Retained core auth section, include when identity/access details are known | | `deployment` | Core deployment section carried forward into v1.1, include when hosting/runtime is known | | `nonFunctional` | Core quality section carried forward into v1.1, include when targets or constraints are known | | `contracts` | v1.1 API contracts, include for formal interfaces | | `domain` | v1.1 entity definitions, include when domain objects can be named | | `features` | v1.1 feature planning, include when phase planning is needed | | `compliance` | v1.1 regulatory requirements, include when applicable | | `slos` | v1.1 service objectives, include when operational targets are defined | | `resilience` | v1.1 fault tolerance patterns, include when reliability design is specified | | `costs` | v1.1 cost model, include when financial planning is needed | | `backupDr` | v1.1 backup and DR strategy, include when recovery planning is needed | | `design` | v1.1 design system section, include for frontend/design-aware projects | Alignment note: - Follow `spec/SDL-v1.1.md` as the authority for v1.1 structure. - In v1.1, `solution`, `architecture`, and `data` are the universally required root sections beyond `sdlVersion`. - Other sections are added when the architecture actually needs them. ### Artifact Types ``` architecture-diagram | sequence-diagrams | openapi | data-model repo-scaffold | iac-skeleton | backlog | adr | deployment-guide | cost-estimate coding-rules | coding-rules-enforcement ``` --- ## Conditional Validation Rules These are hard errors — SDL will not compile if violated (27 rules from spec/SDL-v1.1.md): **Reference Integrity** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 1 | `environments[].components` defined | Every component name must exist in `architecture.projects` | Rename or add missing component | | 2 | `slos[].componentId` defined | Must match a component in `architecture.projects` | Fix componentId to match project name | | 3 | `costs.infrastructure[].component` defined | Must match a component in `architecture.projects` | Fix component name or remove entry | | 4 | `architecture.projects[].dependsOn[]` defined | Must not form a cycle | Break circular dependency | | 5 | `contracts[].paths[].service` defined | Service must exist in `architecture.projects` | Fix service name in contract paths | | 6 | `domain.entities[].relationships[].target` defined | Target entity must exist in `domain.entities` | Add missing entity or fix target name | | 7 | `features.phase*.features[].dependsOn[]` defined | Referenced IDs must exist in same or earlier phases | Move feature to correct phase or fix ID | | 8 | `resilience.circuitBreaker[].service` defined | Service must exist in `architecture.projects` | Fix service name in circuit breaker config | | 9 | `backupDr.databases[].name` defined | Must match a name in `data.databases` or `data.primaryDatabase` | Fix database name | **Type Compatibility** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 10 | Any `architecture.projects[].orm` set | Must be compatible with `data.primaryDatabase.type` (Prisma ✓ relational/MongoDB; Mongoose ✓ MongoDB only; EF Core ✗ MongoDB) | Change ORM or database type | | 11 | `architecture.projects[].framework` + `.language` | Must be compatible (NestJS → node/ts; Django → python; Spring → java) | Fix framework or language | | 12 | `auth.provider` references an integration | Provider must exist in `integrations[]` | Add missing integration or fix provider name | **Deployment Integrity** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 13 | `architecture.style = "microservices"` | `architecture.services[]` must have 2+ items | Add services or switch to `modular-monolith` | | 14 | `architecture.projects[].deployable = true` | Component must appear in at least one environment | Add to environments or set deployable: false | | 15 | Multiple components in same environment | No duplicate ports | Change port on one component | | 16 | `deployment.regions[]` defined | Regions must be valid for `deployment.cloud` | Fix region for cloud provider | | 17 | `deployment.infrastructure.iac = "cloudformation"` | `deployment.cloud` must be `"aws"` | Use terraform/cdk or change cloud to aws | **Data Model Integrity** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 18 | `domain.entities[]` defined | Every entity must have exactly one `primaryKey: true` field | Add primary key field | | 19 | FK relationship spans different databases | Flag as limitation (no DB-level enforcement) | Use application-level FK or consolidate to one DB | | 20 | All `architecture.projects` entries | Component names must be globally unique | Rename duplicate component | | 21 | `domain.entities[]` defined | Each entity should be owned by a component (soft) | Add x-owner field to entity | **Configuration Completeness** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 22 | `architecture.projects[].deployable = true` | Component must have `path` and `runtime` | Add missing path/runtime fields | | 23 | `auth.strategy = "oidc"` | `auth.identityProvider` must be set | Add identityProvider | | 24 | `compliance.frameworks[].name` defined | Must be recognised: `GDPR \| HIPAA \| SOC2-Type2 \| PCI-DSS \| CCPA \| ISO27001` | Fix framework name | **Resilience & Performance** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 25 | `resilience.circuitBreaker[].failureThreshold` or `retryPolicy[].maxAttempts` defined | Must be > 0 | Set positive integer value | | 26 | `slos[].availability.target` defined | Must be 90–99.99%; `latency.p99` must be > `latency.p50` | Adjust target or latency values | **PII & Security** | # | Condition | Requirement | Fix | |---|-----------|-------------|-----| | 27 | Any entity field contains PII data | `nonFunctional.security.pii: true` AND `encryptionAtRest: true` | Set both fields | --- ## Normalization Rules The normalizer applies 15 auto-inference defaults. **Do not manually set these** — let the normalizer handle them: | # | Field | Default | Condition | |---|-------|---------|-----------| | 1 | `solution.regions.primary` | `"us-east-1"` | If regions missing | | 2 | `data.primaryDatabase.name` | `"{name}_db"` | Lowercased, non-alphanumeric → `_` | | 3 | `frontend[].type` | `"web"` | If type not set | | 4 | `backend[].type` | `"backend"` | If type not set | | 5 | `deployment.runtime.frontend` | From cloud mapping | See table below | | 6 | `deployment.runtime.backend` | From cloud mapping | See table below | | 7 | `deployment.networking.publicApi` | `true` | If undefined | | 8 | `deployment.ciCd.provider` | `"github-actions"` | If ciCd missing | | 9 | `nonFunctional.availability.target` | Stage-based | concept/mvp→99%, growth→99.9%, enterprise→99.99% | | 10 | `security.encryptionAtRest` | `true` | If pii=true | | 11 | `security.encryptionInTransit` | `true` | If undefined | | 12 | (reserved) | — | — | | 13 | `backend[].orm` | Framework+DB based | See ORM mapping below | | 14 | `testing.unit.framework` | Backend framework based | See test mapping below | | 15 | `observability.logging.provider` | Backend framework based | See logging mapping below | ### Cloud → Runtime Mapping | Cloud | Frontend Runtime | Backend Runtime | |-------|-----------------|-----------------| | `vercel` | `vercel` | `vercel` | | `aws` | `s3+cloudfront` | `ecs` | | `railway` | `railway` | `railway` | | `gcp` | `cloudflare-pages` | `cloud-run` | | `azure` | `static-web-apps` | `container-apps` | ### Framework → ORM Mapping | Framework | postgres | mysql | mongodb | |-----------|---------|-------|---------| | `nodejs` | `prisma` | `prisma` | `mongoose` | | `python-fastapi` | `sqlalchemy` | `sqlalchemy` | — | | `dotnet-8` | `ef-core` | `ef-core` | — | | `go` | `gorm` | `gorm` | — | | `java-spring` | `hibernate` | `hibernate` | — | ### Framework → Test Framework Mapping | Framework | Test Framework | |-----------|---------------| | `nodejs` | `vitest` | | `python-fastapi` | `pytest` | | `dotnet-8` | `xunit` | | `go` | `go-test` | | `java-spring` | `junit` | | `ruby-rails` | `rspec` | | `php-laravel` | `phpunit` | ### Framework → Logging Provider Mapping | Framework | Logging Provider | |-----------|-----------------| | `nodejs` | `pino` | | `python-fastapi` | `structured` | | `dotnet-8` | `serilog` | | `go` | `zerolog` | | `java-spring` | `log4j` | --- ## Warning Detection Warnings are non-fatal checks applied after validation passes: ### Warning 1: Complexity vs Team ``` TRIGGER: architecture.style = "microservices" AND (totalDevs < 3 OR devops = 0) CODE: COMPLEXITY_EXCEEDS_TEAM_CAPACITY