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
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:

0. 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.

1. Always set sdlVersion: "1.1"

2. Infer architecture style:

   • Single backend → modular-monolith
   • 2+ backends with separate concerns → microservices
   • All functions/lambdas → serverless

3. Include only sections with data — omit empty optional sections

4. Let normalizer handle defaults — do not manually set fields covered by the 15 normalization rules

5. 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

6. 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"
   

7. Use comments sparingly — only for non-obvious choices

8. Validate the output — ensure all required fields are present and enums are valid

9. 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:

1. Recursively compares both document trees
2. Uses named array matching — arrays of objects with name field are matched by name, not index
3. Reports changes as added, removed, or changed
4. 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%