c4-annotations-schema.yaml

# =============================================================================
# C4 Literate Python Annotation Schema
# =============================================================================
# 
# This schema defines the C4 model annotations that can be embedded in
# Python docstrings and comments. The tangler extracts these annotations
# and generates Structurizr DSL for creating architecture diagrams.
#
# Version: 0.9.0
# Date: 2025-01-21
# =============================================================================

schema_version: "0.9.0"
schema_type: "c4-literate-annotations"

# -----------------------------------------------------------------------------
# Annotation Definitions
# -----------------------------------------------------------------------------

annotations:

  # ===========================================================================
  # STRUCTURE ANNOTATIONS (What elements exist)
  # ===========================================================================

  "@c4-container":
    name: "@c4-container"
    placement: [module]
    required_attributes:
      - "@c4-technology"
      - "@c4-description"
    optional_attributes:
      - "@c4-responsibilities"
    format: "Name of the container"
    description: >
      Declares that this module represents a C4 container (deployable
      unit like a web application, database, mobile app, etc.)
    examples:
      - "@c4-container: API Application"
      - "@c4-container: Database Layer"
      - "@c4-container: Message Queue"
    notes: >
      Containers are the high-level building blocks of your system.
      Each container is separately deployable and typically runs in
      its own process space.

  "@c4-component":
    name: "@c4-component"
    placement: [module, class]
    required_attributes:
      - "@c4-technology"
    optional_attributes:
      - "@c4-description"
    format: "Name of the component"
    description: >
      Declares that this module or class represents a C4 component
      (a grouping of related functionality within a container)
    examples:
      - "@c4-component: Data Validation Layer"
      - "@c4-component: API Request Handler"
      - "@c4-component: Authentication Service"
    notes: >
      Components are the major structural elements within a container.
      They represent groupings of related functionality.
    parent_container_assignment: >
      Components are automatically assigned to containers based on
      filepath. If a component and container are in the same file,
      the component is nested inside that container. Otherwise, the
      component is assigned to the first available container.
      See docs/ADR-001-component-assignment.md for details.

  # ===========================================================================
  # ATTRIBUTE ANNOTATIONS (Properties of elements)
  # ===========================================================================

  "@c4-technology":
    name: "@c4-technology"
    placement: [module, class, function]
    format: "Technology stack description"
    description: >
      Describes the technology or tech stack used to implement this
      element
    examples:
      - "@c4-technology: Python 3.12, FastAPI 0.104"
      - "@c4-technology: SQLAlchemy 2.0, SQLite 3"
      - "@c4-technology: Pydantic 2.0"
    notes: >
      Be specific about versions when relevant for documentation
      purposes.

  "@c4-description":
    name: "@c4-description"
    placement: [module, class, function]
    format: "Brief description (1-2 sentences recommended)"
    description: >
      Provides a brief description of what this element does or
      represents
    examples:
      - "@c4-description: REST API providing CRUD operations for notes"
      - "@c4-description: Validates and serializes request/response data"
    notes: >
      Keep descriptions concise and focused on the primary
      responsibility. Detailed explanations belong in the surrounding
      prose documentation.

  "@c4-responsibilities":
    name: "@c4-responsibilities"
    placement: [module, class]
    format: "Bullet list of responsibilities (one per line, indented)"
    description: "Lists the key responsibilities of this element"
    examples:
      - |
        @c4-responsibilities:
            - Accept and validate HTTP requests
            - Route requests to handlers
            - Transform responses to JSON
    notes: >
      Each responsibility should be a brief action phrase. Typically
      3-7 items.

  # ===========================================================================
  # RELATIONSHIP ANNOTATIONS (How elements interact)
  # ===========================================================================

  "@c4-uses":
    name: "@c4-uses"
    placement: [module, class]
    format: 'Target - "Description" - "Technology"'
    description: >
      Declares that this element depends on or uses another container
      or component
    examples:
      - '@c4-uses: Database Layer (app.database) - "Manages note persistence" - "SQLAlchemy ORM"'
      - '@c4-uses: Data Models (app.models) - "Validates requests" - "Pydantic"'
    notes: >
      The three parts are: (1) Target name with optional module path
      in parens, (2) Action description in quotes, (3) Technology/
      protocol in quotes.

  "@c4-used-by":
    name: "@c4-used-by"
    placement: [module, class]
    format: 'Source - "Description" - "Technology"'
    description: >
      Declares that this element is used by another container or
      component (inverse of @c4-uses)
    examples:
      - '@c4-used-by: API Application (app.main) - "Requests database sessions" - "SQLAlchemy ORM"'
    notes: >
      Use this for documenting reverse dependencies when the
      relationship is important to understand from this element's
      perspective.

  "@c4-used-by-person":
    name: "@c4-used-by-person"
    placement: [module, class]
    format: 'Person name - "Description" - "Technology/Protocol"'
    description: >
      Declares that this element is used by an external actor (person
      or external system acting as a user)
    examples:
      - '@c4-used-by-person: API Consumer - "Creates and manages notes" - "HTTPS/JSON"'
      - '@c4-used-by-person: System Administrator - "Monitors health" - "HTTPS"'
    notes: >
      Persons represent human actors or external systems that interact
      with your system from the outside.

  "@c4-operation":
    name: "@c4-operation"
    placement: [function]
    format: "Operation name (typically function name)"
    description: >
      Declares that this function represents a significant operation
      within a component
    examples:
      - "@c4-operation: create_note"
      - "@c4-operation: authenticate_user"
    notes: >
      Operations are the finest level of detail, showing key functions
      within components. Only annotate significant operations, not
      every function.

  "@c4-calls":
    name: "@c4-calls"
    placement: [function]
    format: 'Target - "Description"'
    description: >
      Declares that this operation calls another component or container
    examples:
      - '@c4-calls: Database Layer - "Persists new note"'
      - '@c4-calls: Authentication Service - "Validates token"'
    notes: >
      Use this to show data flow and interactions at the operation
      level. Two-part format: Target and action description.

  "@c4-relationship":
    name: "@c4-relationship"
    placement: [module, class, function]
    format: "Generic relationship declaration"
    description: >
      Generic relationship annotation for advanced use cases not
      covered by @c4-uses/@c4-calls
    examples:
      - "@c4-relationship: Initializes Database Container on startup"
    notes: >
      Use specific annotations (@c4-uses, @c4-calls) when possible.
      This is for special cases.

# -----------------------------------------------------------------------------
# Validation Rules
# -----------------------------------------------------------------------------

validation_rules:
  
  container_requirements:
    description: >
      A module with @c4-container must have @c4-technology and
      @c4-description
    required:
      - "@c4-technology"
      - "@c4-description"

  component_requirements:
    description: >
      A module or class with @c4-component must have @c4-technology
    required:
      - "@c4-technology"

  relationship_format:
    description: >
      Relationship annotations must follow the specified format with
      proper quoting
    pattern: '^.+ - ".+" - ".+"$'

# -----------------------------------------------------------------------------
# Best Practices
# -----------------------------------------------------------------------------

best_practices:
  placement: >
    Place container declarations at module level, component
    declarations at module or class level, operation declarations
    at function level
  
  naming: >
    Use clear, consistent names that match your architecture
    documentation
  
  descriptions: >
    Keep descriptions concise (1-2 sentences). Use surrounding prose
    for detailed explanations
  
  relationships: >
    Document relationships from the perspective of the element being
    annotated
  
  consistency: >
    Use consistent terminology across all annotations in your codebase

# -----------------------------------------------------------------------------
# Future Extensions (Planned)
# -----------------------------------------------------------------------------

future_extensions:
  planned:
    - "@c4-software-system: For declaring system context"
    - "@c4-person: For declaring external actors"
    - "@c4-database: For declaring data stores"
    - "@c4-external-system: For declaring external dependencies"
    - "@c4-deployment-node: For deployment context"
    - "@c4-security-zone: For security boundaries"
    - "@c4-parent-container: For explicit component-to-container assignment"

# -----------------------------------------------------------------------------
# References
# -----------------------------------------------------------------------------

references:
  c4_model: "https://c4model.com/"
  structurizr_dsl: "https://github.com/structurizr/dsl"
  repository: "https://github.com/yourusername/c4-literate-python"
  adr_component_assignment: "docs/ADR-001-component-assignment.md"