sdl-knowledge

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

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

---

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"
   

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,

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%