### SODL Complete Module Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

A comprehensive example of a SODL module, demonstrating the integration of various sections like implements, exports, configuration, invariants, acceptance tests, artifacts, and design patterns.

```sodl
module InMemoryTodoStore:
    implements = [TodoStore]
    exports = [TodoStore]
    config:
        persistence = "in-memory (ephemeral)"
        max_items = 1000
        thread_safe = true
    invariants:
        invariant = "Thread-safe access to todo list"
        invariant = "All operations maintain data consistency"
        invariant = "UUIDs are unique across all todos"
        invariant = "Max items limit is enforced"
    acceptance:
        test = "persists todo across GET calls within same runtime"
        test = "correctly creates new todos with unique IDs"
        test = "properly updates existing todos"
        test = "successfully deletes todos"
        test = "handles concurrent access safely"
        test = "returns 404 for non-existent todo ID"
        test = "enforces max items limit"
    artifacts = ["app/storage.py"]
    design_patterns:
        - name = "Repository"
          purpose = "Abstract data access"
```

--------------------------------

### Complete Pipeline Example with Dependencies (SODL)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Demonstrates a comprehensive pipeline definition named 'Cursor', showcasing multiple steps with dependencies, specific outputs, requirements, and gates. This example illustrates a complex generation flow from design to final review.

```sodl
pipeline "Cursor":
    step Design:
        output = design
        require = "Create data model and API specification"
        gate = "Architecture approved"
    
    step ImplementModels:
        modules = ["StorageModels", "APISchemas"]
        output = code
        require = "Use Pydantic for validation"
        gate = "Models compile without errors"
        depends_on = ["Design"]
    
    step ImplementStorage:
        modules = ["InMemoryTodoStore"]
        output = code
        require = "Thread-safe implementation"
        gate = "Storage tests pass"
        depends_on = ["ImplementModels"]
    
    step ImplementAPI:
        modules = ["TodoAPI"]
        output = code
        require = "RESTful conventions"
        gate = "API tests pass"
        depends_on = ["ImplementStorage"]
    
    step ImplementUI:
        modules = ["WebUI"]
        output = ui
        require = "Material Design components"
        gate = "UI tests pass"
        depends_on = ["ImplementAPI"]
    
    step ValidateArchitecture:
        output = architecture
        require = "Verify Clean Architecture patterns"
        gate = "Architecture validation passed"
        depends_on = ["ImplementAPI"]
    
    step GenerateTests:
        output = tests
        require = "Generate tests per testing_strategy"
        gate = "Test scaffolding complete"
        depends_on = ["ImplementAPI"]
    
    step FinalReview:
        output = diff
        require = "All acceptance criteria met"
        gate = "Full integration test suite passes"
        depends_on = ["ImplementUI", "ValidateArchitecture", "GenerateTests"]
```

--------------------------------

### SODL Pipeline Definition Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This example illustrates the definition of a pipeline in SODL, outlining the steps, their outputs, and the gates that must be passed for progression.

```sodl
# Pipeline
pipeline "Dev":
    step Implement:
        output = code
        gate = "Tests pass"
    step ValidateArchitecture:
        output = architecture
        gate = "Patterns verified"
    step GenerateTests:
        output = tests
        gate = "Tests generated"
```

--------------------------------

### SODL Template Inheritance Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This example shows how to define a base template in SODL and then extend it in a system definition, allowing for code reuse and overriding specific properties.

```sodl
# Template with Inheritance
template "Base":
    stack:
        language = "Python 3.12"
    architecture:
        style = "Clean Architecture"

system "App" extends "Base":
    override stack.language = "Python 3.13"
```

--------------------------------

### Generate SODL Specification with AI Agent

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/README.md

These are example prompts to be used with an AI agent that has the SODL specification generator skill installed. They demonstrate how to request SODL specifications for different types of applications.

```plaintext
Create a SODL specification for a task management API with JWT authentication
```

```plaintext
Generate a production-ready SODL file for an e-commerce microservice with CQRS
```

--------------------------------

### SODL Module Definition Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This example demonstrates the definition of a module in SODL, specifying its requirements, API endpoints, acceptance criteria, and associated design patterns.

```sodl
# Module
module API:
    requires = [Store]
    api:
        endpoint "GET/api/items" -> List[Item]
    acceptance:
        test = "works correctly"
    design_patterns:
        - name = "Repository"
          purpose = "Abstract data access"
```

--------------------------------

### Install and Validate SODL Specifications

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/README.md

Commands for installing the SODL generator skill and using the validator script to generate templates or verify existing specifications.

```bash
# Copy to AI agent skills directory
cp -r sodl-spec-generator-skill ~/.qwen/skills/sodl-spec-generator

# Generate templates
python scripts/sodl_validator.py generate crud output.sodl
python scripts/sodl_validator.py generate microservice output.sodl
python scripts/sodl_validator.py generate rest-api output.sodl
python scripts/sodl_validator.py generate fullstack output.sodl

# Validate specifications
python scripts/sodl_validator.py validate spec.sodl
python scripts/sodl_validator.py check-production spec.sodl
```

--------------------------------

### Step Definition with Constraints (SODL)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Provides an example of a step definition that includes specific modules, output type, and detailed requirements and gates. This highlights how to enforce quality and specific generation criteria for a step.

```sodl
step Implement "Backend":
    modules = ["ImageAPI", "StorageLocal"]
    output = code
    require = "Generate code incrementally"
    gate = "pytest passes with 80% coverage"
```

--------------------------------

### SODL System Definition Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This snippet demonstrates the basic structure for defining a system in SODL, including version, stack, intent, architecture, design patterns, dependency injection, error handling, observability, and testing strategy.

```sodl
# System Definition
system "Name":
    version = "1.0.0"
    stack:
        language = "Python 3.12"
    intent:
        primary = "Goal"
    architecture:
        style = "Clean Architecture"
        layers = ["Domain", "Application", "Infrastructure"]
    design_patterns:
        - name = "Repository"
          scope = "global"
    dependency_injection:
        container = "AutoWire"
        injection_style = "Constructor Injection"
    error_handling:
        strategy = "Result Pattern"
    observability:
        logging:
            format = "JSON"
            level = "INFO"
    testing_strategy:
        unit_tests:
            framework = "pytest"
            coverage_target = 80%
```

--------------------------------

### SODL UI Section Definition Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This snippet shows how to define the UI configuration in SODL, including theme, rules, components, bindings, and page layouts.

```sodl
# UI Section
ui:
    theme = "MaterialWeb"
    rules:
        - name: "ValidateOnBlur"
          actions: ["validate()"]
    components:
        - name: "StandardForm"
          template:
              component: "form"
    bindings:
        - endpoint_method: "GET"
          control_type: "DataTable"
    pages:
        - name: "HomePage"
          components:
              - type: "DataTable"
```

--------------------------------

### SODL Interface Definition Example

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This snippet illustrates how to define an interface in SODL, including its methods, input/output types, and invariants (constraints).

```sodl
# Interface
interface Store:
    method create(Input) -> Output
    invariants:
        invariant = "Constraint"
```

--------------------------------

### Install SODL Specification Generator Skill (Bash)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/README.md

This command copies the SODL specification generator skill to the AI agent's skills directory for use with Qwen. Ensure the target directory exists.

```bash
# Copy skill to your AI agent's skills directory
cp -r sodl-spec-generator-skill ~/.qwen/skills/sodl-spec-generator
```

--------------------------------

### Install SODL Specification Generator Skill (Windows Batch)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/README.md

This command copies the SODL specification generator skill to the AI agent's skills directory for use with Qwen on Windows. Ensure the target directory exists.

```batch
# Or on Windows
xcopy /E /I sodl-spec-generator-skill %USERPROFILE%\.qwen\skills\sodl-spec-generator
```

--------------------------------

### GET /api/todos

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Retrieves a list of all todo items.

```APIDOC
## GET /api/todos

### Description
Retrieves a list of all existing todo items.

### Method
GET

### Endpoint
/api/todos

### Response
#### Success Response (200)
- **todos** (List[TodoResponse]) - A list of todo items.

#### Response Example
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Example Todo",
    "completed": false
  }
]
```

--------------------------------

### Define System Architecture with SODL

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/README.md

A comprehensive example of a SODL specification defining a Todo application, including stack, architecture, dependency injection, and pipeline steps.

```sodl
system "TodoApp":
  version = "1.0.0"
  stack:
    language = "Python 3.12"
    web = "FastAPI"

  intent:
    primary = "Task management application"
    outcomes = ["Create and manage todos", "RESTful API"]

  architecture:
    style = "Clean Architecture"
    layers = ["Domain", "Application", "Infrastructure", "Interface"]

  design_patterns:
    - name = "Repository"
      scope = "global"
    - name = "Factory"
      scope = "modules: [Notification]"

  dependency_injection:
    container = "AutoWire"
    injection_style = "Constructor Injection"
    lifetime_rules:
      - service = "DatabaseConnection"
        scope = "Singleton"
      - service = "TodoService"
        scope = "Transient"

  error_handling:
    strategy = "Result Pattern"
    error_codes:
      - code = "TODO_NOT_FOUND"
        http_status = 404
        user_message = "Todo not found"
    retry_policy:
      max_attempts = 3
      backoff = "exponential"

  observability:
    logging:
      format = "JSON"
      level = "INFO"
    tracing:
      enabled = true
      provider = "OpenTelemetry"

  testing_strategy:
    unit_tests:
      framework = "pytest"
      coverage_target = 80%
    integration_tests:
      framework = "pytest-bdd"

  interface TodoStore:
    method create(todo: TodoInput) -> Todo
    method get_all() -> List[Todo]

  module TodoAPI:
    requires = [TodoStore]
    api:
      endpoint "GET /api/todos" -> List[TodoResponse]
      endpoint "POST /api/todos" -> TodoResponse

  pipeline "Build":
    step Implement:
      modules = ["TodoAPI"]
      output = code
      gate = "Tests pass"
    step ValidateArchitecture:
      output = architecture
      gate = "No dependency violations"
    step GenerateTests:
      output = tests
      gate = "Test scaffolding complete"
```

--------------------------------

### GET /api/entities

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Retrieves a list of all entities available in the system.

```APIDOC
## GET /api/entities

### Description
Retrieves a list of all entities.

### Method
GET

### Endpoint
/api/entities

### Response
#### Success Response (200)
- **entities** (List[Entity]) - A list of entity objects.

#### Response Example
{
  "entities": []
}
```

--------------------------------

### SODL Indentation for Block Structure

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

SODL uses indentation with 2 or 4 spaces to define block structure, similar to Python. This example shows how to define a system with version and stack information.

```sodl
system "MySystem":
    version = "1.0.0"
    stack:
        language = "Python 3.12"
        web = "Flask"
```

--------------------------------

### SODL List Definition

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Lists in SODL are defined using square brackets with comma-separated values. This example shows a list of user actions for a todo list application.

```sodl
outcomes = [
    "Users can create todos",
    "Users can delete todos"
]
```

--------------------------------

### Pipeline and Step Definition Syntax (SODL)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Illustrates the syntax for defining pipelines and individual steps within a pipeline. It shows how to specify step names, outputs, required conditions, and module inclusions for different generation phases.

```sodl
pipeline "Development":
    step Design:
        output = design
        require = "Produce architecture diagram and data model"
    step Implement:
        modules = ["StorageModels", "TodoStore", "TodoAPI"]
        output = code
        gate = "All acceptance tests pass"
    step GenerateUI:
        modules = ["UserUI"]
        output = ui
        gate = "UI components render correctly"
    step Review:
        output = diff
        require = "Code review checklist completed"
```

--------------------------------

### Implement Policy Inheritance

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Demonstrates how systems can extend base templates to inherit and override existing policy definitions.

```sodl
template "BaseWebApp":
    policy Security:
        rule = "Validate all inputs"
        severity = "high"

system "MyApp" extends "BaseWebApp":
    policy Security:
        rule = "Encrypt sensitive data"
        severity = "critical"
```

--------------------------------

### API-UI Binding: GET to DataTable

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This binding configures a DataTable component to display a list of items fetched from a GET API endpoint. It supports features like pagination, sorting, and actions for editing or deleting items.

```yaml
endpoint_method: "GET"
control_type: "DataTable"
default_params:
    columns: ["id", "name", "email", "created_at"]
    pagination:
        enabled: true
        page_size: 25
    sorting:
        enabled: true
    filtering:
        enabled: true
```

--------------------------------

### Define SODL System and Components

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Demonstrates the basic syntax for defining a system in SODL, including versioning, stack configuration, UI bindings, and architectural style. This serves as the root executable specification for an application.

```sodl
system "MySystem":
    version = "1.0.0"
    stack:
        language = "Python 3.12"
        web = "Flask"
    intent:
        primary = "Main application goal"
    ui:
        theme = "Material"
        bindings:
            - method: "GET"
              control: "DataTable"
    architecture:
        style = "Clean Architecture"
        layers = ["Domain", "Application", "Infrastructure", "Interface"]
```

```sodl
system "MyApp":
    version = "1.0.0"
```

--------------------------------

### System Inheritance

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Demonstrates how a system can extend a template to inherit and override configurations, enabling code reuse and modularity.

```APIDOC
## System Definition with Inheritance

### Description
Defines a system that extends a template, inheriting its properties and allowing for specific overrides or additions.

### Method
N/A (Declarative definition)

### Endpoint
N/A

### Parameters
- **system** (string) - Required - The name of the system being defined.
- **extends** (string) - Required - The name of the template being extended.

### Request Body (Conceptual)
Properties defined within the system block will be merged with the parent template's properties according to the inheritance rules.

### Inheritance Rules Summary:
- **Merge Order**: Parent properties are applied first, then child properties.
- **Overrides**: Child values take precedence over parent values for the same properties.
- **Lists**: Elements from child lists are appended to or removed from parent lists based on operations.
- **Blocks**: Child blocks can add to or override parent blocks.

### Example
```sodl
system "MyApp" extends "BasePythonWebApp":
    intent:
        primary = "My specific application"
    stack:
        web = "Flask"
    ui:
        # Inherits rules from BasePythonWebApp
        bindings:
            - endpoint_method: "GET"
              control_type: "DataTable"
    architecture:
        # Inherits style from template
        layers += "Presentation"  # Append additional layer
```

### Override Operations:
- **Replace**: `override path = value` (e.g., `override stack.language = "Python 3.13"`)
- **Append**: `append path += value` (e.g., `append stack.testing += "pytest-asyncio"`)
- **Remove**: `remove path -= value` (e.g., `remove stack.testing -= "pytest-cov"`)
- **Replace block**: `replace block Name:` (e.g., `replace block ui:`) 
```

--------------------------------

### GET /api/users

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Retrieves a paginated list of users.

```APIDOC
## GET /api/users

### Description
Fetches a list of users with support for pagination, sorting, and filtering.

### Method
GET

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Current page number
- **page_size** (integer) - Optional - Number of items per page (default 25)

### Response
#### Success Response (200)
- **data** (array) - List of user objects
- **total** (integer) - Total count of users
```

--------------------------------

### GET /api/images/{id}

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Retrieves image metadata and access details by its unique identifier.

```APIDOC
## GET /api/images/{id}

### Description
Fetches the details of a specific image resource.

### Method
GET

### Endpoint
/api/images/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the image.

### Response
#### Success Response (200)
- **id** (string) - Image ID
- **format** (string) - Image format (PNG/JPEG)
- **size** (int) - File size in bytes

#### Response Example
{
  "id": "img-123",
  "format": "JPEG",
  "size": 512000
}
```

--------------------------------

### SODL Comments

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Comments in SODL start with the '#' symbol. This can be used for single-line or inline comments to explain code.

```sodl
# This is a comment
stack:
    language = "Python 3.12"  # Inline comment
```

--------------------------------

### SODL String Definition

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Strings in SODL can be defined using double quotes. This example demonstrates defining an intent for a todo list application.

```sodl
intent:
    primary = "Build a todo list application"
```

--------------------------------

### Data Migration and UI Configuration

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Information on data migration strategies and UI component configurations.

```APIDOC
## Data Migrations

### Description
Defines the strategy and tools used for data migrations.

### Method
N/A

### Endpoint
N/A

### Details
- **strategy**: "Code-based"
- **tool**: "Alembic"
- **rollback_supported**: true
- **zero_downtime**: true
```

```APIDOC
## UI Configuration

### Description
Details the UI theme, rules, components, and page structure.

### Method
N/A

### Endpoint
N/A

### Details
- **theme**: "MaterialWeb"

### UI Rules
- **AutoFillKnownFields**: Prefills fields like email and name from user profile.
- **ValidateOnBlur**: Validates fields when the user leaves them.
- **ShowLoadingOnAsync**: Displays a loading indicator during asynchronous actions.
- **AccessibilityCompliance**: Ensures accessibility standards are met for rendered components.

### UI Components
- **StandardForm**: A generic form component.
- **DataTable**: A component for displaying tabular data.
- **ConfirmationModal**: A modal for user confirmation.

### UI Bindings
- **GET** requests are bound to **DataTable** controls.
- **POST** and **PUT** requests are bound to **StandardForm** controls.
- **DELETE** requests are bound to **ConfirmationModal** controls.

### UI Pages
- **UsersPage**: Contains a DataTable and a StandardForm for user management.
```

--------------------------------

### Configuring System Overrides in SODL

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Demonstrates how to modify inherited system properties using override, append, remove, and replace operations. This allows fine-grained control over stack, UI, and architectural configurations.

```sodl
system "CustomApp" extends "BasePythonWebApp":
    override stack.language = "Python 3.13"
    append stack.testing += "pytest-asyncio"
    remove stack.testing -= "pytest-cov"
    override ui.theme = "DarkMode"
    append ui.rules += "CustomValidationRule"
    append architecture.layers += ["Presentation"]
    append design_patterns += 
        - name = "CQRS"
          scope = "modules: [Order, Inventory]"
    
    replace block ui:
        theme = "CustomTheme"
        rules:
            - name: "CustomRule"
              actions: ["customAction()"]
```

--------------------------------

### UI Binding Pattern in SODL

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Specifies UI control types (DataTable, StandardForm, ConfirmationModal) to be bound to different API endpoint methods (GET, POST, PUT, DELETE).

```sodl
ui:
    bindings:
        - endpoint_method: "GET"
          control_type: "DataTable"
        - endpoint_method: "POST"
          control_type: "StandardForm"
        - endpoint_method: "PUT"
          control_type: "StandardForm"
        - endpoint_method: "DELETE"
          control_type: "ConfirmationModal"
```

--------------------------------

### Configure Observability Settings

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines logging, tracing, metrics, health checks, and alerting configurations. Supports various output formats, levels, providers, and sensitive field redaction. Includes options for sampling rates, propagation, and custom metrics.

```sodl
observability:
    logging:
        format = "JSON"  # or "Text", "Structured"
        level = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
        correlation_id = "required"
        include_timestamp = true
        include_source = true
        output = ["console", "file", "elasticsearch"]
        retention_days = 30
        sensitive_fields = ["password", "token", "credit_card"]
    
    tracing:
        enabled = true
        provider = "OpenTelemetry"  # or "Jaeger", "Zipkin", "AWS X-Ray"
        sampling_rate = 0.1  # 10% of requests
        propagation = ["traceparent", "baggage"]
        export_to = ["jaeger", "prometheus"]
        include_db_queries = true
        include_http_requests = true
    
    metrics:
        enabled = true
        provider = "Prometheus"  # or "CloudWatch", "Datadog"
        default_buckets = [0.1, 0.5, 1.0, 5.0, 10.0]
        default_labels = ["service", "version", "environment"]
        custom_metrics:
            - name = "business_transactions_total"
              type = "counter"
              labels = ["transaction_type", "status"]
            - name = "request_duration_seconds"
              type = "histogram"
              labels = ["endpoint", "method", "status_code"]
    
    health_checks:
        enabled = true
        endpoint = "/health"
        checks = ["database", "cache", "external_apis"]
        interval = "30s"
    
    alerts:
        - name = "HighErrorRate"
          condition = "error_rate > 5%"
          window = "5m"
          severity = "critical"
          notify = ["slack", "pagerduty"]
        
        - name = "HighLatency"
          condition = "p99_latency > 2s"
          window = "10m"
          severity = "warning"
          notify = ["slack"]
```

--------------------------------

### Implementing Template Chaining

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Shows how to create hierarchical templates where child templates extend parent templates. This pattern promotes code reuse and allows for incremental configuration of system architectures.

```sodl
template "BaseWebApp":
    stack:
        language = "Python 3.12"
    policy Security:
        rule = "Validate all inputs"
        severity = "high"
    architecture:
        style = "Layered Architecture"

template "CRUDWebApp" extends "BaseWebApp":
    ui:
        components:
            - name: "StandardForm"
            - name: "DataTable"
        bindings:
            - endpoint_method: "GET"
              control_type: "DataTable"
    design_patterns:
        - name = "Repository"
          scope = "global"
        - name = "Factory"
          scope = "modules: [Payment]"

system "ProductCatalog" extends "CRUDWebApp":
    intent:
        primary = "Product catalog system"
    stack:
        database = "PostgreSQL"
    architecture:
        style = "Clean Architecture"
```

--------------------------------

### CRUD Module Pattern in SODL

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines a module with API endpoints for CRUD operations (GET, POST, PUT, DELETE) on entities, along with associated UI pages and design patterns like Repository.

```sodl
module EntityAPI:
    api:
        endpoint "GET/api/entities" -> List[Entity]
        endpoint "POST/api/entities" -> Entity
        endpoint "PUT/api/entities/{id}" -> Entity
        endpoint "DELETE/api/entities/{id}" -> Empty
    ui:
        pages:
            - name: "EntitiesPage"
    design_patterns:
        - name = "Repository"
          purpose = "Abstract data access"
```

--------------------------------

### Define Global Policies in SODL

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Shows how to define security and operational policies with specific severity levels. These rules act as constraints during the system generation process.

```sodl
policy Security:
    rule = "No secrets in repository"
    severity = "critical"
    rule = "Validate all user input"
    severity = "high"
    rule = "Use HTTPS for external APIs"
    severity = "high"
    rule = "Log security events"
    severity = "medium"
```

--------------------------------

### Define Conditional API and UI Policies

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Illustrates advanced policy definitions using conditional logic to enforce security and accessibility requirements based on request parameters or component types.

```sodl
policy SecureAPIAccess:
    rule = "All API calls must be authenticated"
    severity = "critical"
    rules:
        - if: "api_call.method != 'GET'"
          then: "require_authentication"
        - if: "api_call.endpoint contains '/admin'"
          then: "require_admin_role"

policy InputValidation:
    rule = "All input data must be validated"
    severity = "high"
    rules:
        - if: "request.body != null"
          then: "validate_input(request.body)"
        - if: "request.params != null"
          then: "validate_params(request.params)"
        - if: "request.headers != null"
          then: "validate_headers(request.headers)"
```

--------------------------------

### Define Testing Strategy and Configuration

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Specifies the overall testing approach, including frameworks, patterns, coverage targets, and directories for various test types like unit, integration, e2e, and API tests. Also configures load testing, mocking strategies, and CI/CD pipeline integration.

```sodl
testing_strategy:
    unit_tests:
        framework = "pytest"  # or "unittest", "Jest", "JUnit"
        pattern = "AAA"  # Arrange-Act-Assert
        coverage_target = 80%
        parallel = true
        timeout = "30s"
        directories = ["tests/unit"]
        naming_convention = "test_*.py"
    
    integration_tests:
        pattern = "Given-When-Then"  # BDD style
        framework = "pytest-bdd"
        database = "TestContainer"
        directories = ["tests/integration"]
        cleanup = "after_each"
        parallel = false
    
    e2e_tests:
        framework = "Playwright"  # or "Selenium", "Cypress"
        browsers = ["chromium", "firefox", "webkit"]
        headless = true
        screenshot_on_failure = true
        video_on_failure = true
        directories = ["tests/e2e"]
    
    api_tests:
        framework = "pytest"
        base_url = "http://localhost:8000"
        directories = ["tests/api"]
        validate_schemas = true
    
    load_tests:
        framework = "locust"
        scenarios:
            - name = "NormalLoad"
              users = 100
              spawn_rate = 10
              duration = "5m"
            - name = "StressTest"
              users = 1000
              spawn_rate = 50
              duration = "10m"
    
    mocking:
        strategy = "Interface-based"
        library = "unittest.mock"  # or "Mockito", "Moq"
        auto_mock = ["external_apis", "database", "cache"]
    
    test_factories:
        strategy = "Factories"
        library = "factory_boy"
        seed = 42
        cleanup = "transaction_rollback"
    
    ci_cd:
        run_on_commit = ["unit", "api"]
        run_on_merge = ["unit", "integration", "api", "e2e"]
        run_nightly = ["load", "security"]
        coverage_gate = 80%
        fail_on_flaky = true
```

--------------------------------

### Defining and Referencing UI Themes

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines a reusable ui_theme construct containing component libraries and global UX rules. It also demonstrates how a system references these themes to apply standardized UI behavior.

```sodl
ui_theme "MaterialWeb":
    components:
        - name: "StandardForm"
          description: "Standard form with auto-fill and validation"
        - name: "DataTable"
          description: "Table for displaying entity lists"
        - name: "ConfirmationModal"
          description: "Confirmation modal dialog"
        - name: "NavigationMenu"
          description: "Primary navigation component"
        - name: "SearchBar"
          description: "Search input with autocomplete"
    rules:
        - name: "UserFriendlyErrors"
          severity = "high"
          description: "Display errors in a user-friendly format"
        - name: "AutoFillKnownFields"
          severity = "medium"
          description: "Auto-fill fields if data is available"
        - name: "ValidateOnBlur"
          severity = "high"
          description: "Validate field on blur"
        - name: "ShowLoadingOnAsync"
          severity = "medium"
          description: "Show spinner during async operations"
    bindings:
        - endpoint_method: "GET"
          control_type: "DataTable"
        - endpoint_method: "POST"
          control_type: "StandardForm"
        - endpoint_method: "PUT"
          control_type: "StandardForm"
        - endpoint_method: "DELETE"
          control_type: "ConfirmationModal"

system "MyApp":
    ui:
        theme = "MaterialWeb"
```

--------------------------------

### Define Project Stack (SODL)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Specifies the technological context and dependencies for a project. This includes programming language, web framework, templating engine, UI framework, database, ORM, caching system, testing tools, and linting tools.

```sodl
stack:
    language = "Python 3.12"
    web = "FastAPI"
    templating = "Jinja2"
    ui_framework = "Material Components Web"
    database = "PostgreSQL"
    orm = "SQLAlchemy"
    cache = "Redis"
    testing = ["pytest", "pytest-cov"]
    linting = ["flake8", "black"]
```

--------------------------------

### SODL Compiler Workflow and Output Structure

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

The SODL compiler processes the specification through multiple stages, generating structured prompt chunks and organizing them into an output directory. New stages include architecture validation, test generation, dependency injection, error handling, and observability.

```text
┌─────────────────────────────────────────────────────────────────┐
│                        SODL Compiler                            │
├─────────────────────────────────────────────────────────────────┤
│  1. Parse SODL specification                                    │
│  2. Validate syntax and semantics                               │
│  3. Resolve templates and inheritance                           │
│  4. Generate module-specific instructions                       │
│  5. Generate UI binding instructions                            │
│  6. Generate architecture pattern instructions                  │
│  7. Generate dependency injection configuration                 │
│  8. Generate error handling scaffolding                         │
│  9. Generate observability configuration                        │
│  10. Generate test scaffolding per strategy                     │
│  11. Output structured prompt chunks                            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     .sodl/ Output Directory                     │
├─────────────────────────────────────────────────────────────────┤
│  global.md          # System-level context                      │
│  ui/                # UI-specific instructions                  │
│  modules/           # Module-specific instructions              │
│  steps/             # Step-by-step generation instructions      │
│  architecture/      # Architecture pattern instructions         │
│  testing/           # Test generation instructions              │
│  manifest.json      # Metadata and structure                    │
└─────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Configure UI Bindings for CRUD Operations

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Maps HTTP methods to specific UI controls and default parameters. This enables automatic generation of forms, tables, and confirmation dialogs based on endpoint interactions.

```sodl
ui:
    bindings:
        - endpoint_method: "GET"
          control_type: "DataTable"
          default_params:
              columns: ["id", "name", "email", "created_at"]
              actions:
                  - name: "edit"
                    endpoint: "{{endpoint}}/{id}"
                  - name: "delete"
                    endpoint: "{{endpoint}}/{id}"
        
        - endpoint_method: "POST"
          control_type: "StandardForm"
          default_params:
              fields:
                  - name: "name"
                    type: "text"
                    validation: "required"
                  - name: "email"
                    type: "email"
                    validation: "email"
              submitLabel: "Create"
        
        - endpoint_method: "PUT"
          control_type: "StandardForm"
          default_params:
              fields:
                  - name: "name"
                    type: "text"
                    validation: "required"
                  - name: "email"
                    type: "email"
                    validation: "email"
              submitLabel: "Save"
              loadExistingData: true
        
        - endpoint_method: "DELETE"
          control_type: "ConfirmationModal"
          default_params:
              title: "Confirm Deletion"
              content: "Are you sure?"
```

--------------------------------

### Define and Reference Pattern Libraries

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Creates reusable pattern definitions in a library that can be referenced by systems to maintain consistency across projects.

```sodl
pattern_library "StandardPatterns":
    pattern "CQRS":
        description = "Separate read and write models"
        when_to_use = "High read/write ratio, complex queries"
        template = "Commands go to WriteModel, Queries to ReadModel"
    
system "MyApp":
    design_patterns:
        - ref = "StandardPatterns.CQRS"
          scope = "modules: [Order, Inventory]"
```

--------------------------------

### POST /api/todos

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Creates a new todo item.

```APIDOC
## POST /api/todos

### Description
Creates a new todo item in the system.

### Method
POST

### Endpoint
/api/todos

### Request Body
- **title** (str) - Required - The title of the todo.
- **description** (str) - Optional - Detailed description.
- **priority** (int) - Optional - Priority level (1-3).

### Response
#### Success Response (201)
- **todo** (TodoResponse) - The created todo item.

#### Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "New Todo",
  "completed": false
}
```

--------------------------------

### Repository Pattern Interface and Implementation in SODL

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines an interface for a repository pattern with methods for data access (find, create, update, delete) and provides a concrete implementation for PostgreSQL, exporting the interface.

```sodl
interface EntityRepository:
    method find_all() -> List[Entity]
    method find_by_id(id: UUID) -> Optional[Entity]
    method create(entity: EntityInput) -> Entity
    method update(id: UUID, updates: EntityUpdate) -> Entity
    method delete(id: UUID) -> bool

module PostgresEntityRepository:
    implements = [EntityRepository]
    exports = [EntityRepository]
    design_patterns:
        - name = "Repository"
          purpose = "Abstract data access"
```

--------------------------------

### Define Modular System Structure

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines a module with ownership, API endpoints, UI components, invariants, and acceptance tests, representing a complete functional unit.

```sodl
module ImageAPI:
    owns = ["Image upload endpoint", "Image retrieval logic"]
    requires = [ImageStore]
    api:
        endpoint "POST/api/images" -> JsonSavedImage
        endpoint "GET/api/images/{id}" -> JsonImage
    ui:
        pages:
            - name: "UploadPage"
              components:
                  - type: "StandardForm"
                    params:
                        endpoint: "/api/images"
    invariants:
        invariant = "Accept only PNG and JPEG formats"
        invariant = "Validate file size < 10MB"
    acceptance:
        test = "valid image uploads successfully"
        test = "oversized image returns 413"
        test = "invalid format returns 400"
    artifacts = ["app/api.py", "app/routes/images.py"]
    design_patterns:
        - name = "Factory"
          purpose = "Create different image processors"
```

--------------------------------

### API-UI Binding: POST to StandardForm

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

This binding sets up a StandardForm for creating new entries via a POST API request. It includes field definitions with validation rules and customizable labels for submission and cancellation.

```yaml
endpoint_method: "POST"
control_type: "StandardForm"
default_params:
    fields:
        - name: "name"
          type: "text"
          validation: "required"
          label: "Name"
        - name: "email"
          type: "email"
          validation: "email"
          label: "Email"
    submitLabel: "Create"
    cancelEnabled: true
```

--------------------------------

### Microservices Application Configuration (SODL)

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines the overall structure and configuration of a microservices application using SODL. It specifies the system version, technology stack, architectural style, communication patterns, design patterns, dependency injection, error handling, observability, testing strategies, security patterns, and individual module definitions.

```sodl
system "MicroservicesApp":
    version = "1.0.0"
    
    stack:
        language = "Python 3.12"
        web = "FastAPI"
        database = "PostgreSQL"
        message_broker = "RabbitMQ"
        cache = "Redis"
    
    architecture:
        style = "Microservices"
        communication = "Event-Driven"
        services = ["UserService", "OrderService", "PaymentService", "NotificationService"]
        service_discovery = "Consul"
        api_gateway = "Kong"
    
    design_patterns:
        - name = "Saga"
          purpose = "Distributed transaction management"
          scope = "global"
        - name = "Event Sourcing"
          purpose = "Event-based state management"
          scope = "modules: [Order, Payment]"
        - name = "CQRS"
          purpose = "Separate read and write models"
          scope = "modules: [Order, Inventory]"
        - name = "Circuit Breaker"
          purpose = "Fault tolerance"
          scope = "global"
    
    dependency_injection:
        container = "AutoWire"
        injection_style = "Constructor Injection"
        lifetime_rules:
            - service = "MessageBus"
              scope = "Singleton"
            - service = "DatabaseConnection"
              scope = "Singleton"
    
    error_handling:
        strategy = "Result Pattern"
        retry_policy:
            max_attempts = 3
            backoff = "exponential"
        circuit_breaker:
            enabled = true
            failure_threshold = 5
            recovery_timeout = "30s"
    
    observability:
        logging:
            format = "JSON"
            correlation_id = "required"
        tracing:
            enabled = true
            provider = "OpenTelemetry"
            sampling_rate = 0.1
        metrics:
            enabled = true
            provider = "Prometheus"
    
    testing_strategy:
        unit_tests:
            framework = "pytest"
            coverage_target = 85%
        integration_tests:
            pattern = "Given-When-Then"
            database = "TestContainer"
        contract_tests:
            framework = "Pact"
            enabled = true
        ci_cd:
            run_on_commit = ["unit", "contract"]
            run_on_merge = ["unit", "integration", "contract", "e2e"]
    
    security_patterns:
        authentication:
            method = "JWT"
            token_expiry = "1h"
        authorization:
            model = "RBAC"
        data_protection:
            encryption_at_rest = "AES-256"
            encryption_in_transit = "TLS 1.3"
    
    module OrderService:
        owns = ["Order processing"]
        design_patterns:
            - name = "Saga"
              purpose = "Coordinate order fulfillment"
            - name = "Event Sourcing"
              purpose = "Track order state changes"
        api:
            endpoint "POST/api/orders" -> Order
            endpoint "GET/api/orders/{id}" -> Order
        invariants:
            invariant = "Orders are idempotent"
            invariant = "State changes are logged as events"
    
    module PaymentService:
        owns = ["Payment processing"]
        requires = ["OrderService"]
        design_patterns:
            - name = "Saga"
              purpose = "Coordinate with order service"
            - name = "Circuit Breaker"
              purpose = "Handle payment gateway failures"
        api:
            endpoint "POST/api/payments" -> Payment
            endpoint "GET/api/payments/{id}" -> Payment
        invariants:
            invariant = "Payments are idempotent"
            invariant = "Failed payments trigger compensation"
    
    pipeline "Microservices":
        step Design:
            output = design
            require = "Service boundaries and event contracts"
        
        step ImplementServices:
            modules = ["OrderService", "PaymentService"]
            output = code
            gate = "Service tests pass"
        
        step ImplementEvents:
            output = code
            require = "Event schemas and handlers"
            gate = "Event tests pass"
            depends_on = ["ImplementServices"]
        
        step ContractTests:
            output = tests
            require = "Pact contract tests"
            gate = "Contracts verified"
            depends_on = ["ImplementServices"]
        
        step Deploy:
            output = diff
            require = "All tests pass"
            depends_on = ["ImplementEvents", "ContractTests"]

```

--------------------------------

### Define System-Level Multi-Policy Configuration

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Groups multiple policy definitions under a system container to enforce comprehensive rules across security, performance, and code quality domains.

```sodl
system "SecureApp":
    policy Security:
        rule = "Encrypt sensitive data at rest"
        severity = "critical"
        rule = "Use parameterized queries"
        severity = "critical"
        rule = "Implement rate limiting"
        severity = "high"
    
    policy Performance:
        rule = "Cache frequently accessed data"
        severity = "medium"
        rule = "Use database indexes"
        severity = "high"
        rule = "Lazy load large resources"
        severity = "medium"
    
    policy CodeQuality:
        rule = "Test coverage above 80%"
        severity = "high"
        rule = "No code duplication"
        severity = "medium"
        rule = "Document public APIs"
        severity = "medium"
```

--------------------------------

### Dependency Injection Configuration

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Configures the dependency injection container, specifying injection styles and lifetime rules for services. It supports various DI containers and scanning conventions.

```sodl
dependency_injection:
    container = "AutoWire"  # or "Manual", "Unity", "Ninject", "Spring"
    injection_style = "Constructor Injection"  # or "Property Injection", "Method Injection"
    
    lifetime_rules:
        - service = "DatabaseConnection"
          scope = "Singleton"
          description = "Single connection pool for application lifetime"
        
        - service = "UserSession"
          scope = "Request"
          description = "New session per HTTP request"
        
        - service = "EmailService"
          scope = "Transient"
          description = "New instance per injection"
        
        - service = "CacheService"
          scope = "Singleton"
          description = "Shared cache across application"
        
        - service = "Logger"
          scope = "Singleton"
          description = "Centralized logging instance"
    
    registration_conventions:
        - pattern = "*Repository"
          scope = "Singleton"
        - pattern = "*Service"
          scope = "Transient"
        - pattern = "*Controller"
          scope = "Transient"
    
    modules_to_scan:
        - "app/services"
        - "app/repositories"
        - "app/controllers"
```

--------------------------------

### SODL Data Migrations Configuration

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Defines the database migration strategy, including the migration tool, rollback support, and zero-downtime considerations. It also specifies conventions for migration naming and directory structure, as well as deployment and data seeding configurations.

```sodl
data_migrations:
    strategy = "Code-based"  # or "SQL-based", "ORM-based"
    tool = "Alembic"  # or "Flyway", "Liquibase", "Django Migrations"
    rollback_supported = true
    zero_downtime = true
    
    conventions:
        naming = "YYYYMMDD_HHMMSS_description"
        directory = "migrations"
        auto_generate = true
        review_required = true
    
    deployment:
        run_on_deploy = true
        backup_before_migrate = true
        test_on_staging = true
        rollback_plan_required = true
    
    data_seeding:
        enabled = true
        environments = ["development", "staging"]
        seed_data_directory = "seeds"
```

--------------------------------

### Define System-Level Design Patterns

Source: https://github.com/sodlspace/sodl-impl-v1/blob/main/.sodl/SODL_spec_05.md

Configures design patterns to be applied globally or within specific modules. Each pattern includes a purpose, scope, and implementation template.

```sodl
design_patterns:
    - name = "Repository"
      purpose = "Abstract database access"
      scope = "global"
      when_to_use = "All data access operations"
      template = "Generic repository pattern with unit of work"
    
    - name = "CQRS"
      purpose = "Separate read and write models"
      scope = "modules: [Order, Inventory]"
      when_to_use = "High read/write ratio, complex queries"
      template = "Commands go to WriteModel, Queries to ReadModel"
```