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

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

Type Compatibility

Deployment Integrity

Data Model Integrity

Configuration Completeness

Resilience & Performance

PII & Security

Normalization Rules

The normalizer applies 15 auto-inference defaults. Do not manually set these — let the normalizer handle them:

Cloud → Runtime Mapping

Framework → ORM Mapping

Framework → Test Framework Mapping

Framework → Logging Provider Mapping

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

Schema Errors

Conditional Rule Errors

Manifest-to-SDL Mapping

When converting a system manifest to SDL:

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

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:

Artifact Generators

Each generator takes a compiled SDL document and produces deterministic output — same input always produces identical artifacts.

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.

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

Availability by Stage