| name | sdl-knowledge |
| description | Solution Design Language (SDL) specification — schema, validation, normalization, and generation rules |
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
MESSAGE: "Microservices with {N} service(s) may be too complex for {D} developer(s)"
FIX: "Consider modular-monolith for MVP — plan microservices migration when team grows"
Warning 2: Timeline vs Scope
TRIGGER: (projectCount × flowCount × 1.5) / totalDevs > timelineWeeks
CODE: TIMELINE_TOO_AGGRESSIVE
MESSAGE: "{P} project(s) with {F} core flow(s) may not fit in {W} weeks"
FIX: "Reduce scope, extend timeline, or add developers"
Warning 3: Multi-Persona without Auth
TRIGGER: auth section missing AND personas > 1 AND (any has admin role OR count > 2)
CODE: MISSING_RECOMMENDED_FIELD
MESSAGE: "{N} personas defined but no auth configuration"
FIX: "Add an auth section with strategy and roles"
Warning 4: Budget vs Infrastructure
TRIGGER: estimated monthly cost > budget ceiling
(startup=$500, scaleup=$2000, enterprise=$10000)
CODE: BUDGET_INFRASTRUCTURE_MISMATCH
MESSAGE: "Estimated cost (~${X}/mo) may exceed {budget} ceiling (${Y}/mo)"
FIX: "Consider managed/serverless options or upgrade budget tier"
Warning 5: Microservices with Small Team
TRIGGER: architecture.style = "microservices" AND team.developers < 3
CODE: MICROSERVICES_TEAM_TOO_SMALL
MESSAGE: "Microservices architecture with only {N} developer(s) — operational overhead is high"
FIX: "Use modular-monolith for MVP; migrate to microservices as team grows"
Warning 6: Cross-Database Foreign Keys
TRIGGER: domain.entities[].relationships[].target entity lives in different database
CODE: CROSS_DATABASE_FOREIGN_KEY
MESSAGE: "{entity}.{field} → {target} spans databases — no DB-level enforcement"
FIX: "Enforce referential integrity at application layer; consider consolidating entities"
Warning 7: Unused Integrations
TRIGGER: integration defined in integrations[] but not referenced in any component's dependsOn[]
CODE: UNUSED_INTEGRATION
MESSAGE: "Integration '{name}' is defined but not referenced by any component"
FIX: "Add to relevant component's dependsOn[], or remove if not needed"
Warning 8: Missing Observability for Production
TRIGGER: solution.stage = "growth" OR "enterprise" AND observability section absent
CODE: MISSING_OBSERVABILITY
MESSAGE: "{stage}-stage project has no observability configuration"
FIX: "Add observability section with logging, tracing, and metrics; run /architect:setup-monitoring"
Warning 9: Loose SLO Targets
TRIGGER: solution.stage = "growth" OR "enterprise" AND any slos[].availability.target < 99%
CODE: LOOSE_SLO_TARGET
MESSAGE: "SLO target {X}% is below recommended minimum for {stage} stage"
FIX: "Raise availability target or document reason for lower target"
Warning 10: High Cost Variance
TRIGGER: costs.scenarios.high > costs.scenarios.low × 10
CODE: HIGH_COST_VARIANCE
MESSAGE: "Cost scenarios vary {X}x (low: ${L}/mo vs high: ${H}/mo)"
FIX: "Review usage assumptions; choose tiers with more predictable pricing"
Warning 11: Compliance Gaps
TRIGGER: solution.stage = "growth" OR "enterprise" AND compliance section absent
OR constraints.compliance defined but compliance.frameworks[] absent
CODE: COMPLIANCE_NOT_ADDRESSED
MESSAGE: "Stage or constraints suggest compliance needs but no compliance section defined"
FIX: "Add compliance section or run /architect:compliance for gap analysis"
Warning 12: Design Tokens Missing for Production
TRIGGER: solution.stage = "growth" OR "enterprise" AND design section absent
CODE: DESIGN_TOKENS_MISSING
MESSAGE: "{stage}-stage project has no design tokens defined"
FIX: "Run /architect:design-system to generate a complete design token set"
Error Codes
Parse Errors
| Code | Trigger | Fix |
|---|
EMPTY_INPUT | Empty YAML string | Provide valid YAML |
INVALID_YAML | Result is not an object | Start with key-value pairs |
YAML_PARSE_ERROR | Syntax error | Fix indentation, colons, special characters |
Schema Errors
| Code | Trigger | Fix |
|---|
MISSING_REQUIRED | Required field absent | Add the field |
INVALID_ENUM | Value not in allowed list | Use allowed value |
INVALID_TYPE | Wrong data type | Provide correct type |
UNKNOWN_FIELD | Unknown field without x- prefix | Remove or prefix with x- |
INVALID_FORMAT | Pattern mismatch | Follow required format |
VALUE_TOO_SHORT | Below min length | Provide longer value |
ARRAY_TOO_SHORT | Below min items | Add more items |
Conditional Rule Errors
| Code | Trigger | Fix |
|---|
MICROSERVICES_REQUIRES_SERVICES | Microservices without 2+ services | Add services or use modular-monolith |
OIDC_REQUIRES_PROVIDER | OIDC without provider | Add provider field |
PII_REQUIRES_ENCRYPTION | PII without encryption | Set encryptionAtRest: true |
INCOMPATIBLE_CLOUD_IAC | CloudFormation on non-AWS | Use terraform or change to AWS |
INCOMPATIBLE_DATABASE_ORM | MongoDB with EF Core | Use mongoose or change database |
Manifest-to-SDL Mapping
When converting a system manifest to SDL:
| Manifest Field | SDL Field |
|---|
project.name | solution.name |
project.description | solution.description |
project.type (app/agent/hybrid) | solution.stage — infer: new idea → MVP, scaling → Growth |
users[].role | product.personas[].name |
users[].description | product.personas[].goals (split into goal statements) |
users[].count (sum) | nonFunctional.scaling.expectedUsersYear1 |
frontends[] | architecture.projects.frontend[] |
services[] | architecture.projects.backend[] |
databases[0] | data.primaryDatabase |
databases[1+] | data.secondaryDatabases[] |
integrations[category=payments] | integrations.payments |
integrations[category=email] | integrations.email |
integrations[category=auth] | auth section |
integrations[category=storage] | data.storage |
integrations[category=cache] | data.cache |
application_patterns.style | architecture.style |
security.auth | auth section |
security.api_security | nonFunctional.security |
devops.ci_cd.provider | deployment.ciCd.provider |
deployment.targets[0] | deployment.cloud |
communication_patterns[] | interServiceCommunication[] |
application_patterns.error_handling | errorHandling |
devops.config_management | configuration |
services[].name + frontends[].name (cross-referenced with communication patterns) | architecture.projects.*[].dependsOn[] — required on every component. Array of names of other components and external providers this component calls. Rules: frontend lists every backend it calls; backend lists downstream services + external integrations (e.g. ["stripe", "sendgrid"]); lambda/worker lists its trigger source + any downstream service; shared lib gets []. Always emit the field even when empty. Use the component's SDL name as identifier. External providers in lowercase (e.g. "razorpay", "anthropic"). |
| Detected domain objects (entity names from models/schemas) | domain.entities[] — list of core domain object names |
| Identity provider (Cognito, Auth0, etc.) | auth.identityProvider |
| Service-level token validation mechanism (JWT, session) | auth.serviceTokenModel: jwt | session | api-key |
Auth note: Use auth.identityProvider for the external IdP (cognito, auth0, clerk) and auth.serviceTokenModel for how services validate tokens (jwt, session, api-key). These are often different — e.g. Cognito issues tokens, services validate them as JWT.
Integration Provider Mapping
| Manifest Service | SDL Path |
|---|
| Stripe | integrations.payments.provider: stripe |
| SendGrid | integrations.email.provider: sendgrid |
| Resend | integrations.email.provider: resend |
| Twilio | integrations.sms.provider: twilio |
| PostHog | integrations.analytics.provider: posthog |
| Datadog | integrations.monitoring.provider: datadog |
| Sentry | integrations.monitoring.provider: sentry |
| Cloudflare | integrations.cdn.provider: cloudflare |
| Auth0 | auth.identityProvider: auth0 |
| Firebase Auth | auth.identityProvider: firebase |
| Clerk | auth.identityProvider: clerk |
| Cognito | auth.identityProvider: cognito |
| S3 | data.storage.blobs.provider: s3 |
| GCS | data.storage.blobs.provider: gcs |
| Azure Blob | data.storage.blobs.provider: azure-blob |
| Cloudflare R2 | data.storage.blobs.provider: cloudflare-r2 |
| Redis | data.cache.type: redis |
| RabbitMQ | data.queues.provider: rabbitmq |
| SQS | data.queues.provider: sqs |
| Kafka | data.queues.provider: kafka |
| Azure Service Bus | data.queues.provider: azure-service-bus |
| Elasticsearch | data.search.provider: elasticsearch |
| Algolia | data.search.provider: algolia |
| Typesense | data.search.provider: typesense |
| Meilisearch | data.search.provider: meilisearch |
| Azure Search | data.search.provider: azure-search |
| Pinecone | data.search.provider: pinecone |
| Qdrant | data.search.provider: qdrant |
| Weaviate | data.search.provider: weaviate |
Domain Entities
The domain section captures the core business objects of the system. It is optional but strongly recommended for any system with 3+ services or a complex data model.
domain:
entities:
- Expert
- Client
- Appointment
- Payment
- Notification
Domain entities are used by:
generate-data-model — to enumerate all entities that need ORM schemas
blueprint — to drive the data model section and ERD generation
prototype — to generate typed mock data and CRUD pages
Rules:
- List entity names only (PascalCase) — no fields, no relationships here. Those belong in the data model deliverable.
- Include any object that has its own lifecycle, identity, and persistence
- Do NOT include value objects (Money, Address) or enums
SDL Generation Rules
When generating SDL from a conversation or manifest:
-
Save to project root — always write the SDL file as solution.sdl.yaml in the project root directory (current working directory). Never place it inside architecture/, artifacts/, output/, or any other subfolder.
-
Always set sdlVersion: "1.1"
-
Infer architecture style:
- Single backend →
modular-monolith
- 2+ backends with separate concerns →
microservices
- All functions/lambdas →
serverless
-
Include only sections with data — omit empty optional sections
-
Let normalizer handle defaults — do not manually set fields covered by the 15 normalization rules
-
Check the applicable v1.1 conditional rules mentally before outputting:
- Cross-reference the rules from
spec/SDL-v1.1.md when using v1.1 sections
- At minimum, check service references, feature dependencies, component references, and compatibility constraints
-
If plugin workflows need explicit generation metadata, set artifacts.generate based on what the user needs. This is plugin metadata, not a universally required upstream v1.1 root section. For a full blueprint:
artifacts:
generate:
- "architecture-diagram"
- "sequence-diagrams"
- "openapi"
- "data-model"
- "repo-scaffold"
- "adr"
- "backlog"
- "deployment-guide"
- "cost-estimate"
-
Use comments sparingly — only for non-obvious choices
-
Validate the output — ensure all required fields are present and enums are valid
-
Quote YAML-unsafe string values — any scalar value that starts with or contains a YAML special character MUST be wrapped in double quotes. Failure to quote these causes parse errors. Apply this rule to every string value you write:
| Character / pattern | Why it breaks YAML | Example fix |
|---|
Value starts with > | Interpreted as block scalar folding indicator | condition: ">5 failures in 5 min" |
Value starts with | | Interpreted as block scalar literal indicator | format: "| pipe-delimited" |
Value starts with { or [ | Interpreted as inline mapping/sequence | config: "{key: val}" |
Value starts with * or & | Interpreted as alias/anchor | ref: "*base" |
Value starts with ! | Interpreted as tag | type: "!important" |
Value contains : (colon-space) anywhere | Parsed as a nested mapping key | trigger: "EventBridge Schedule (rate: 1 day)" |
Value contains # (space-hash) | Everything after is treated as a comment | desc: "retry # times" |
Value contains ' or " | May terminate the string early | Use double quotes and escape inner doubles as \" |
Value is a bare true, false, yes, no, on, off, null | Coerced to boolean/null | flag: "true" |
| Value is a bare number that should be a string | Coerced to number | version: "1.0" |
Practical checklist — before writing any string value, ask:
- Does it start with
>, |, {, [, *, &, !, -, ?, :, @, `? → quote it.
- Does it contain
: anywhere (including inside parentheses)? → quote it.
- Does it contain
# anywhere? → quote it.
- Is it a comparison expression like
>5, >=10, <100ms? → quote it.
- Is it
true, false, yes, no, null, or a plain number that must stay a string? → quote it.
SDL Output Format
Output SDL as a YAML code block with triple-backtick yaml fencing. After the SDL, report the validation summary:
**Validation Summary**
| Field | Value |
|-------|-------|
| Architecture | {style} |
| Projects | {frontend + backend + mobile count} |
| Estimated Cost | {range} |
| Artifacts | {count} |
| Warnings | {count} |
If warnings exist, list each with code, message, and recommendation.
SDL Diffing
SDL documents can be compared structurally. The diff engine:
- Recursively compares both document trees
- Uses named array matching — arrays of objects with
name field are matched by name, not index
- Reports changes as
added, removed, or changed
- Groups summary by top-level section
Diff entry format: {path, type, oldValue?, newValue?}
Example paths:
architecture.style → scalar change
product.personas[name=Admin] → named array item
data.cache → section added/removed
Templates
10 starter templates are available at references/sdl-templates.md:
| ID | Name | Stage | Key Stack |
|---|
saas-starter | SaaS Starter | MVP | Next.js, Node.js, Postgres, Auth0, Vercel |
ecommerce | E-Commerce Platform | Growth | Microservices, Postgres, AWS, Cognito |
mobile-backend | Mobile App Backend | MVP | React Native, Node.js, Firebase, Railway |
internal-tool | Internal Tool | MVP | Vue, Python FastAPI, Entra ID, Azure |
api-first | API-First Platform | Growth | Go, DynamoDB, AWS, API key auth |
ai-product | AI Product / RAG API | MVP | Python FastAPI, Postgres, Auth0, AWS |
marketplace | Two-Sided Marketplace | MVP | .NET 8, Stripe Connect, AWS |
admin-dashboard | Admin Dashboard | MVP | React, Node.js, Railway |
saas-subscription | SaaS with Stripe Billing | MVP | Next.js, Vercel, Stripe |
realtime-collab | Real-Time Collaboration | MVP | React, Node.js, Redis, Clerk, Fly.io |
Artifact Generators
Each generator takes a compiled SDL document and produces deterministic output — same input always produces identical artifacts.
| Generator | Output | SDL Sections Used |
|---|
| Architecture Diagram | Mermaid C4 container diagram | architecture, data, auth, integrations |
| Repo Scaffold | Per-project package.json, configs, starter code | architecture.projects, data, auth |
| CI/CD Pipeline | GitHub Actions / GitLab CI / Azure DevOps YAML | deployment.ciCd, deployment.cloud, architecture.projects |
| ADRs | MADR-format decision records | All major sections |
| OpenAPI Spec | OpenAPI 3.1 YAML | architecture.projects.backend, auth, product.personas |
| Data Model | Mermaid ERD + ORM schema | data.primaryDatabase, backend ORM, product.personas |
| Sequence Diagrams | Mermaid sequence diagrams | auth, product.coreFlows, product.personas |
| Backlog | User stories grouped by epic | product.personas, product.coreFlows, architecture |
| Deployment Guide | Step-by-step runbook | deployment, data, auth, integrations |
| Cost Estimate | Monthly cost breakdown | deployment.cloud, data, integrations, nonFunctional.scaling |
| Docker Compose | docker-compose.yml for local dev | architecture.projects, data, integrations |
| Kubernetes | K8s manifests (Deployment, Service, HPA, Ingress) | architecture.projects, deployment, data |
| Monitoring | Prometheus config, alert rules, Grafana dashboard | architecture.projects, nonFunctional, data |
| Nginx | Reverse proxy config with SSL, gzip, rate limiting | architecture.projects, deployment |
| Coding Rules | CLAUDE.md, .cursorrules, copilot-instructions.md | architecture, data, auth, testing, observability, all projects |
| Coding Rules Enforcement | ESLint, dependency-cruiser, pre-commit, arch tests | architecture, all projects |
How SDL drives blueprint deliverables
Deterministic (SDL → artifact directly):
- 4b: Architecture Diagram
- 4e: API Artifacts (OpenAPI, Postman, AsyncAPI)
- 4i: Cost Estimate
- 4o: Sprint Backlog
Structured input (SDL provides context for LLM-enhanced output):
- 4a: Executive Summary
- 4c: Application Architecture & Patterns
- 4d: Shared Types & Contracts
- 4f: Security Architecture
- 4g: Observability & Monitoring
- 4h: DevOps Blueprint
- 4j: Complexity Assessment
- 4k: Well-Architected Review
- 4l: Plain English Specs
- 4m: Required Accounts
- 4n: Next Steps Guide
SDL API Routes
All SDL operations are exposed via REST endpoints at /api/sdl/*. All routes require authentication.
| Method | Path | Input | Description |
|---|
| POST | /api/sdl/validate | { yaml, modules? } | Validate SDL YAML (supports multi-module with imports) |
| POST | /api/sdl/generate | { yaml, artifactType? } | Generate all artifacts or a single type |
| POST | /api/sdl/docker-compose | { yaml } | Generate Docker Compose for local dev |
| POST | /api/sdl/kubernetes | { yaml } | Generate Kubernetes manifests |
| POST | /api/sdl/monitoring | { yaml } | Generate Prometheus + Grafana configs |
| POST | /api/sdl/nginx | { yaml } | Generate Nginx reverse proxy config |
| POST | /api/sdl/coding-rules | { yaml } | Generate AI coding rules (CLAUDE.md, .cursorrules) |
| POST | /api/sdl/diff | { yamlA, yamlB } | Diff two SDL documents |
| GET | /api/sdl/templates | — | List available SDL templates |
| GET | /api/sdl/templates/:id | — | Get specific template with YAML |
Notes:
coding-rules-enforcement has no dedicated route — use /api/sdl/generate with artifactType: "coding-rules-enforcement"
deploy-diagram is not exposed via API — used programmatically by the deploy planner module
- Routes with
sdlGate middleware also check billing capabilities (sdlEdit capability required)
Constants
Budget Monthly Ceilings
| Budget Tier | Monthly Ceiling |
|---|
startup | $500 |
scaleup | $2,000 |
enterprise | $10,000 |
Availability by Stage
| Stage | Default Availability Target |
|---|
concept | 99% |
mvp | 99% |
growth | 99.9% |
enterprise | 99.99% |