@bluefly/openstandardagents 0.1.9

package/public/src/api/clean-architecture.openapi.yml

@@ -0,0 +1,1435 @@
+openapi: 3.1.0
+info:
+  title: Clean Architecture Guidelines API
+  description: |
+    Clean Architecture Guidelines and Enforcement System for OSSA v0.1.9.
+    Comprehensive framework for Clean Architecture validation, compliance checking,
+    migration planning, and automated enforcement with CI/CD integration.
+  version: "@bluefly/ossa/v0.1.9"
+  contact:
+    name: OSSA Framework
+    url: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard
+  license:
+    name: MIT
+    url: https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/blob/main/LICENSE
+
+servers:
+  - url: https://api.ossa.bluefly.io/clean-arch
+    description: Clean Architecture API Server
+
+paths:
+  /validate/architecture:
+    post:
+      summary: Validate architecture compliance
+      description: Comprehensive validation of Clean Architecture principles and patterns
+      operationId: validateArchitecture
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ArchitectureValidationRequest'
+      responses:
+        '200':
+          description: Architecture validation results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ArchitectureValidationResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+
+  /compliance/check:
+    post:
+      summary: Check compliance with Clean Architecture
+      description: Automated compliance checking against Clean Architecture standards
+      operationId: checkCompliance
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ComplianceCheckRequest'
+      responses:
+        '200':
+          description: Compliance check results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ComplianceCheckResponse'
+
+  /migration/plan:
+    post:
+      summary: Generate migration plan
+      description: Create detailed migration plan to Clean Architecture
+      operationId: generateMigrationPlan
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MigrationPlanRequest'
+      responses:
+        '200':
+          description: Migration plan generated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MigrationPlanResponse'
+
+  /quality/gates:
+    get:
+      summary: Get quality gates configuration
+      description: Retrieve current quality gates and thresholds
+      operationId: getQualityGates
+      parameters:
+        - name: projectType
+          in: query
+          schema:
+            type: string
+            enum: [web, api, library, microservice, monolith]
+      responses:
+        '200':
+          description: Quality gates configuration
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/QualityGatesConfig'
+
+    post:
+      summary: Configure quality gates
+      description: Set up automated quality gates for CI/CD enforcement
+      operationId: configureQualityGates
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/QualityGatesRequest'
+      responses:
+        '200':
+          description: Quality gates configured
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/QualityGatesConfig'
+
+  /refactor/suggestions:
+    post:
+      summary: Generate refactoring suggestions
+      description: AI-powered suggestions for Clean Architecture refactoring
+      operationId: generateRefactoringSuggestions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RefactoringSuggestionsRequest'
+      responses:
+        '200':
+          description: Refactoring suggestions generated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RefactoringSuggestionsResponse'
+
+  /patterns/library:
+    get:
+      summary: Get architecture patterns library
+      description: Retrieve library of Clean Architecture patterns and templates
+      operationId: getPatternLibrary
+      parameters:
+        - name: category
+          in: query
+          schema:
+            type: string
+            enum: [entities, use-cases, interfaces, frameworks, infrastructure]
+        - name: language
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Architecture patterns library
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PatternLibrary'
+
+  /patterns/{patternId}:
+    get:
+      summary: Get specific pattern details
+      operationId: getPattern
+      parameters:
+        - name: patternId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Pattern details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ArchitecturePattern'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /documentation/generate:
+    post:
+      summary: Generate architecture documentation
+      description: Automated generation of Clean Architecture documentation
+      operationId: generateDocumentation
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DocumentationRequest'
+      responses:
+        '200':
+          description: Documentation generated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DocumentationResponse'
+            text/markdown:
+              schema:
+                type: string
+            text/html:
+              schema:
+                type: string
+
+  /enforcement/rules:
+    get:
+      summary: Get enforcement rules
+      description: Retrieve current architecture enforcement rules
+      operationId: getEnforcementRules
+      responses:
+        '200':
+          description: Enforcement rules
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EnforcementRules'
+
+    post:
+      summary: Configure enforcement rules
+      description: Set up automated enforcement rules for CI/CD integration
+      operationId: configureEnforcementRules
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EnforcementRulesRequest'
+      responses:
+        '200':
+          description: Enforcement rules configured
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EnforcementRules'
+
+  /metrics/architecture:
+    get:
+      summary: Get architecture metrics
+      description: Comprehensive metrics for architecture quality and compliance
+      operationId: getArchitectureMetrics
+      parameters:
+        - name: projectId
+          in: query
+          schema:
+            type: string
+        - name: timeRange
+          in: query
+          schema:
+            type: string
+            enum: [7d, 30d, 90d, 1y]
+            default: 30d
+      responses:
+        '200':
+          description: Architecture metrics
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ArchitectureMetrics'
+
+  /training/materials:
+    get:
+      summary: Get training materials
+      description: Educational materials and best practices for Clean Architecture
+      operationId: getTrainingMaterials
+      parameters:
+        - name: level
+          in: query
+          schema:
+            type: string
+            enum: [beginner, intermediate, advanced]
+        - name: format
+          in: query
+          schema:
+            type: string
+            enum: [text, video, interactive, workshop]
+      responses:
+        '200':
+          description: Training materials
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TrainingMaterials'
+
+components:
+  schemas:
+    ArchitectureValidationRequest:
+      type: object
+      required:
+        - projectId
+      properties:
+        projectId:
+          type: string
+        validationRules:
+          type: array
+          items:
+            $ref: '#/components/schemas/ValidationRule'
+        scope:
+          type: string
+          enum: [full, incremental, specific-files]
+          default: full
+        files:
+          type: array
+          items:
+            type: string
+          description: Specific files to validate (when scope is specific-files)
+
+    ArchitectureValidationResponse:
+      type: object
+      properties:
+        validationId:
+          type: string
+        projectId:
+          type: string
+        overallScore:
+          type: number
+          minimum: 0
+          maximum: 100
+        compliance:
+          type: string
+          enum: [compliant, partially-compliant, non-compliant]
+        violations:
+          type: array
+          items:
+            $ref: '#/components/schemas/ArchitectureViolation'
+        recommendations:
+          type: array
+          items:
+            $ref: '#/components/schemas/ArchitectureRecommendation'
+        layerAnalysis:
+          $ref: '#/components/schemas/LayerAnalysis'
+        dependencyAnalysis:
+          $ref: '#/components/schemas/DependencyAnalysis'
+
+    ComplianceCheckRequest:
+      type: object
+      required:
+        - projectId
+      properties:
+        projectId:
+          type: string
+        standards:
+          type: array
+          items:
+            type: string
+            enum: [clean-architecture, solid, ddd, hexagonal, onion]
+        severity:
+          type: string
+          enum: [error, warning, info]
+          default: warning
+        autoFix:
+          type: boolean
+          default: false
+
+    ComplianceCheckResponse:
+      type: object
+      properties:
+        checkId:
+          type: string
+        projectId:
+          type: string
+        complianceScore:
+          type: number
+          minimum: 0
+          maximum: 100
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/ComplianceResult'
+        summary:
+          $ref: '#/components/schemas/ComplianceSummary'
+        autoFixApplied:
+          type: boolean
+        fixesSuggested:
+          type: array
+          items:
+            $ref: '#/components/schemas/AutoFix'
+
+    MigrationPlanRequest:
+      type: object
+      required:
+        - projectId
+        - targetArchitecture
+      properties:
+        projectId:
+          type: string
+        currentArchitecture:
+          type: string
+        targetArchitecture:
+          type: string
+          enum: [clean-architecture, hexagonal, onion, layered-architecture]
+        migrationStrategy:
+          type: string
+          enum: [big-bang, strangler-fig, branch-by-abstraction, parallel-run]
+        constraints:
+          $ref: '#/components/schemas/MigrationConstraints'
+        preferences:
+          $ref: '#/components/schemas/MigrationPreferences'
+
+    MigrationPlanResponse:
+      type: object
+      properties:
+        planId:
+          type: string
+        projectId:
+          type: string
+        strategy:
+          type: string
+        phases:
+          type: array
+          items:
+            $ref: '#/components/schemas/MigrationPhase'
+        timeline:
+          $ref: '#/components/schemas/MigrationTimeline'
+        riskAssessment:
+          $ref: '#/components/schemas/MigrationRiskAssessment'
+        resources:
+          $ref: '#/components/schemas/ResourceRequirements'
+        successCriteria:
+          type: array
+          items:
+            $ref: '#/components/schemas/SuccessCriterion'
+
+    QualityGatesRequest:
+      type: object
+      required:
+        - projectId
+        - gates
+      properties:
+        projectId:
+          type: string
+        gates:
+          type: array
+          items:
+            $ref: '#/components/schemas/QualityGate'
+        enforcement:
+          type: string
+          enum: [blocking, warning, advisory]
+          default: warning
+        integration:
+          $ref: '#/components/schemas/CiCdIntegration'
+
+    QualityGatesConfig:
+      type: object
+      properties:
+        projectId:
+          type: string
+        gates:
+          type: array
+          items:
+            $ref: '#/components/schemas/QualityGate'
+        enforcement:
+          type: string
+        lastUpdated:
+          type: string
+          format: date-time
+        status:
+          type: string
+          enum: [active, inactive, pending]
+
+    RefactoringSuggestionsRequest:
+      type: object
+      required:
+        - projectId
+      properties:
+        projectId:
+          type: string
+        targetPatterns:
+          type: array
+          items:
+            type: string
+        priority:
+          type: string
+          enum: [high-impact, low-effort, quick-wins, all]
+          default: all
+        includeCodeExamples:
+          type: boolean
+          default: true
+
+    RefactoringSuggestionsResponse:
+      type: object
+      properties:
+        projectId:
+          type: string
+        suggestions:
+          type: array
+          items:
+            $ref: '#/components/schemas/RefactoringSuggestion'
+        prioritizedActions:
+          type: array
+          items:
+            $ref: '#/components/schemas/PrioritizedRefactoring'
+        estimatedImpact:
+          $ref: '#/components/schemas/RefactoringImpact'
+
+    PatternLibrary:
+      type: object
+      properties:
+        categories:
+          type: array
+          items:
+            $ref: '#/components/schemas/PatternCategory'
+        patterns:
+          type: array
+          items:
+            $ref: '#/components/schemas/PatternSummary'
+        total:
+          type: integer
+
+    ArchitecturePattern:
+      type: object
+      properties:
+        patternId:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        description:
+          type: string
+        intent:
+          type: string
+        structure:
+          $ref: '#/components/schemas/PatternStructure'
+        participants:
+          type: array
+          items:
+            $ref: '#/components/schemas/PatternParticipant'
+        collaborations:
+          type: array
+          items:
+            $ref: '#/components/schemas/PatternCollaboration'
+        consequences:
+          $ref: '#/components/schemas/PatternConsequences'
+        implementation:
+          $ref: '#/components/schemas/PatternImplementation'
+        examples:
+          type: array
+          items:
+            $ref: '#/components/schemas/PatternExample'
+
+    DocumentationRequest:
+      type: object
+      required:
+        - projectId
+      properties:
+        projectId:
+          type: string
+        sections:
+          type: array
+          items:
+            type: string
+            enum: [overview, architecture, layers, dependencies, patterns, guidelines]
+        format:
+          type: string
+          enum: [markdown, html, pdf, confluence]
+          default: markdown
+        includeCodeExamples:
+          type: boolean
+          default: true
+        includeDiagrams:
+          type: boolean
+          default: true
+
+    DocumentationResponse:
+      type: object
+      properties:
+        documentationId:
+          type: string
+        projectId:
+          type: string
+        format:
+          type: string
+        sections:
+          type: array
+          items:
+            $ref: '#/components/schemas/DocumentationSection'
+        downloadUrl:
+          type: string
+        generatedAt:
+          type: string
+          format: date-time
+
+    EnforcementRulesRequest:
+      type: object
+      required:
+        - projectId
+        - rules
+      properties:
+        projectId:
+          type: string
+        rules:
+          type: array
+          items:
+            $ref: '#/components/schemas/EnforcementRule'
+        severity:
+          type: string
+          enum: [error, warning, info]
+        cicdIntegration:
+          $ref: '#/components/schemas/CiCdIntegration'
+
+    EnforcementRules:
+      type: object
+      properties:
+        projectId:
+          type: string
+        rules:
+          type: array
+          items:
+            $ref: '#/components/schemas/EnforcementRule'
+        lastUpdated:
+          type: string
+          format: date-time
+        activeRules:
+          type: integer
+        violationsBlocked:
+          type: integer
+
+    ArchitectureMetrics:
+      type: object
+      properties:
+        projectId:
+          type: string
+        timeRange:
+          type: string
+        compliance:
+          $ref: '#/components/schemas/ComplianceMetrics'
+        quality:
+          $ref: '#/components/schemas/QualityMetrics'
+        complexity:
+          $ref: '#/components/schemas/ComplexityMetrics'
+        maintainability:
+          $ref: '#/components/schemas/MaintainabilityMetrics'
+        trends:
+          type: array
+          items:
+            $ref: '#/components/schemas/MetricTrend'
+
+    TrainingMaterials:
+      type: object
+      properties:
+        materials:
+          type: array
+          items:
+            $ref: '#/components/schemas/TrainingMaterial'
+        courses:
+          type: array
+          items:
+            $ref: '#/components/schemas/TrainingCourse'
+        workshops:
+          type: array
+          items:
+            $ref: '#/components/schemas/Workshop'
+
+    # Supporting schemas
+    ValidationRule:
+      type: object
+      properties:
+        ruleId:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        severity:
+          type: string
+          enum: [error, warning, info]
+        enabled:
+          type: boolean
+
+    ArchitectureViolation:
+      type: object
+      properties:
+        ruleId:
+          type: string
+        severity:
+          type: string
+        message:
+          type: string
+        location:
+          $ref: '#/components/schemas/CodeLocation'
+        suggestion:
+          type: string
+        autoFixable:
+          type: boolean
+
+    ArchitectureRecommendation:
+      type: object
+      properties:
+        category:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        priority:
+          type: string
+          enum: [low, medium, high, critical]
+        effort:
+          type: string
+          enum: [low, medium, high]
+        impact:
+          type: string
+          enum: [low, medium, high]
+        steps:
+          type: array
+          items:
+            type: string
+
+    LayerAnalysis:
+      type: object
+      properties:
+        layers:
+          type: array
+          items:
+            $ref: '#/components/schemas/ArchitectureLayer'
+        violations:
+          type: array
+          items:
+            $ref: '#/components/schemas/LayerViolation'
+        separation:
+          type: number
+          minimum: 0
+          maximum: 100
+
+    DependencyAnalysis:
+      type: object
+      properties:
+        allowedDependencies:
+          type: array
+          items:
+            $ref: '#/components/schemas/DependencyRule'
+        violations:
+          type: array
+          items:
+            $ref: '#/components/schemas/DependencyViolation'
+        circularDependencies:
+          type: array
+          items:
+            $ref: '#/components/schemas/CircularDependency'
+
+    ComplianceResult:
+      type: object
+      properties:
+        standard:
+          type: string
+        score:
+          type: number
+        violations:
+          type: array
+          items:
+            $ref: '#/components/schemas/ArchitectureViolation'
+        recommendations:
+          type: array
+          items:
+            type: string
+
+    ComplianceSummary:
+      type: object
+      properties:
+        totalChecks:
+          type: integer
+        passed:
+          type: integer
+        failed:
+          type: integer
+        warnings:
+          type: integer
+
+    AutoFix:
+      type: object
+      properties:
+        type:
+          type: string
+        description:
+          type: string
+        location:
+          $ref: '#/components/schemas/CodeLocation'
+        changes:
+          type: array
+          items:
+            type: string
+
+    MigrationConstraints:
+      type: object
+      properties:
+        timeline:
+          type: string
+        budget:
+          type: string
+        resources:
+          type: integer
+        downtimeLimit:
+          type: string
+        riskTolerance:
+          type: string
+          enum: [low, medium, high]
+
+    MigrationPreferences:
+      type: object
+      properties:
+        preserveExistingTests:
+          type: boolean
+        minimizeCodeChanges:
+          type: boolean
+        prioritizePerformance:
+          type: boolean
+        incrementalDeployment:
+          type: boolean
+
+    MigrationPhase:
+      type: object
+      properties:
+        phaseId:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        order:
+          type: integer
+        tasks:
+          type: array
+          items:
+            $ref: '#/components/schemas/MigrationTask'
+        prerequisites:
+          type: array
+          items:
+            type: string
+        deliverables:
+          type: array
+          items:
+            type: string
+        estimatedDuration:
+          type: string
+
+    MigrationTask:
+      type: object
+      properties:
+        taskId:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        type:
+          type: string
+          enum: [refactor, create, move, delete, test, document]
+        estimatedHours:
+          type: number
+        skills:
+          type: array
+          items:
+            type: string
+        dependencies:
+          type: array
+          items:
+            type: string
+
+    MigrationTimeline:
+      type: object
+      properties:
+        totalDuration:
+          type: string
+        phases:
+          type: array
+          items:
+            type: object
+            properties:
+              phase:
+                type: string
+              startDate:
+                type: string
+                format: date
+              endDate:
+                type: string
+                format: date
+              duration:
+                type: string
+
+    MigrationRiskAssessment:
+      type: object
+      properties:
+        overallRisk:
+          type: string
+          enum: [low, medium, high, very-high]
+        risks:
+          type: array
+          items:
+            $ref: '#/components/schemas/MigrationRisk'
+        mitigation:
+          type: array
+          items:
+            $ref: '#/components/schemas/RiskMitigation'
+
+    MigrationRisk:
+      type: object
+      properties:
+        category:
+          type: string
+        description:
+          type: string
+        probability:
+          type: string
+          enum: [low, medium, high]
+        impact:
+          type: string
+          enum: [low, medium, high]
+        mitigation:
+          type: string
+
+    RiskMitigation:
+      type: object
+      properties:
+        risk:
+          type: string
+        strategy:
+          type: string
+        actions:
+          type: array
+          items:
+            type: string
+
+    ResourceRequirements:
+      type: object
+      properties:
+        roles:
+          type: array
+          items:
+            $ref: '#/components/schemas/RoleRequirement'
+        skills:
+          type: array
+          items:
+            type: string
+        tools:
+          type: array
+          items:
+            type: string
+
+    RoleRequirement:
+      type: object
+      properties:
+        role:
+          type: string
+        level:
+          type: string
+          enum: [junior, mid, senior, lead, architect]
+        estimatedHours:
+          type: number
+        responsibilities:
+          type: array
+          items:
+            type: string
+
+    SuccessCriterion:
+      type: object
+      properties:
+        criterion:
+          type: string
+        metric:
+          type: string
+        target:
+          type: string
+        measurement:
+          type: string
+
+    QualityGate:
+      type: object
+      properties:
+        gateId:
+          type: string
+        name:
+          type: string
+        conditions:
+          type: array
+          items:
+            $ref: '#/components/schemas/QualityCondition'
+        threshold:
+          type: number
+        blocking:
+          type: boolean
+
+    QualityCondition:
+      type: object
+      properties:
+        metric:
+          type: string
+        operator:
+          type: string
+          enum: [gt, gte, lt, lte, eq, neq]
+        value:
+          type: number
+        description:
+          type: string
+
+    CiCdIntegration:
+      type: object
+      properties:
+        platform:
+          type: string
+          enum: [gitlab-ci, github-actions, jenkins, azure-devops]
+        webhooks:
+          type: array
+          items:
+            type: string
+        notifications:
+          $ref: '#/components/schemas/NotificationConfig'
+
+    NotificationConfig:
+      type: object
+      properties:
+        channels:
+          type: array
+          items:
+            type: string
+            enum: [email, slack, teams, webhook]
+        onViolation:
+          type: boolean
+        onSuccess:
+          type: boolean
+
+    RefactoringSuggestion:
+      type: object
+      properties:
+        suggestionId:
+          type: string
+        type:
+          type: string
+          enum: [extract-layer, separate-concerns, dependency-inversion, interface-segregation]
+        title:
+          type: string
+        description:
+          type: string
+        location:
+          $ref: '#/components/schemas/CodeLocation'
+        before:
+          type: string
+        after:
+          type: string
+        effort:
+          type: string
+        impact:
+          type: string
+        confidence:
+          type: number
+
+    PrioritizedRefactoring:
+      type: object
+      properties:
+        refactoring:
+          $ref: '#/components/schemas/RefactoringSuggestion'
+        priority:
+          type: integer
+        reasoning:
+          type: string
+
+    RefactoringImpact:
+      type: object
+      properties:
+        qualityImprovement:
+          type: number
+        maintainabilityGain:
+          type: number
+        complexityReduction:
+          type: number
+        estimatedEffort:
+          type: string
+
+    PatternCategory:
+      type: object
+      properties:
+        categoryId:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        patternCount:
+          type: integer
+
+    PatternSummary:
+      type: object
+      properties:
+        patternId:
+          type: string
+        name:
+          type: string
+        category:
+          type: string
+        description:
+          type: string
+        complexity:
+          type: string
+          enum: [simple, moderate, complex]
+
+    PatternStructure:
+      type: object
+      properties:
+        diagram:
+          type: string
+          description: Base64 encoded diagram or URL
+        components:
+          type: array
+          items:
+            type: string
+        relationships:
+          type: array
+          items:
+            type: string
+
+    PatternParticipant:
+      type: object
+      properties:
+        name:
+          type: string
+        role:
+          type: string
+        responsibilities:
+          type: array
+          items:
+            type: string
+
+    PatternCollaboration:
+      type: object
+      properties:
+        participants:
+          type: array
+          items:
+            type: string
+        interaction:
+          type: string
+
+    PatternConsequences:
+      type: object
+      properties:
+        benefits:
+          type: array
+          items:
+            type: string
+        liabilities:
+          type: array
+          items:
+            type: string
+        tradeoffs:
+          type: array
+          items:
+            type: string
+
+    PatternImplementation:
+      type: object
+      properties:
+        languages:
+          type: array
+          items:
+            type: string
+        codeExamples:
+          type: array
+          items:
+            $ref: '#/components/schemas/CodeExample'
+        considerations:
+          type: array
+          items:
+            type: string
+
+    PatternExample:
+      type: object
+      properties:
+        language:
+          type: string
+        code:
+          type: string
+        explanation:
+          type: string
+
+    CodeExample:
+      type: object
+      properties:
+        language:
+          type: string
+        title:
+          type: string
+        code:
+          type: string
+        explanation:
+          type: string
+
+    DocumentationSection:
+      type: object
+      properties:
+        sectionId:
+          type: string
+        title:
+          type: string
+        content:
+          type: string
+        subsections:
+          type: array
+          items:
+            $ref: '#/components/schemas/DocumentationSection'
+
+    EnforcementRule:
+      type: object
+      properties:
+        ruleId:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        category:
+          type: string
+        severity:
+          type: string
+        pattern:
+          type: string
+        enabled:
+          type: boolean
+
+    ComplianceMetrics:
+      type: object
+      properties:
+        score:
+          type: number
+        violations:
+          type: integer
+        trends:
+          type: array
+          items:
+            $ref: '#/components/schemas/ComplianceTrend'
+
+    QualityMetrics:
+      type: object
+      properties:
+        maintainabilityIndex:
+          type: number
+        technicalDebt:
+          type: number
+        codeSmells:
+          type: integer
+        testCoverage:
+          type: number
+
+    ComplexityMetrics:
+      type: object
+      properties:
+        cyclomaticComplexity:
+          type: number
+        cognitiveComplexity:
+          type: number
+        nestingDepth:
+          type: number
+
+    MaintainabilityMetrics:
+      type: object
+      properties:
+        changeability:
+          type: number
+        analyzability:
+          type: number
+        stability:
+          type: number
+        testability:
+          type: number
+
+    MetricTrend:
+      type: object
+      properties:
+        metric:
+          type: string
+        date:
+          type: string
+          format: date
+        value:
+          type: number
+
+    ComplianceTrend:
+      type: object
+      properties:
+        date:
+          type: string
+          format: date
+        score:
+          type: number
+        violations:
+          type: integer
+
+    TrainingMaterial:
+      type: object
+      properties:
+        materialId:
+          type: string
+        title:
+          type: string
+        type:
+          type: string
+          enum: [article, tutorial, guide, reference]
+        level:
+          type: string
+        duration:
+          type: string
+        url:
+          type: string
+
+    TrainingCourse:
+      type: object
+      properties:
+        courseId:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        level:
+          type: string
+        duration:
+          type: string
+        modules:
+          type: array
+          items:
+            type: string
+
+    Workshop:
+      type: object
+      properties:
+        workshopId:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        duration:
+          type: string
+        format:
+          type: string
+          enum: [hands-on, presentation, interactive]
+
+    CodeLocation:
+      type: object
+      properties:
+        file:
+          type: string
+        line:
+          type: integer
+        column:
+          type: integer
+        method:
+          type: string
+        class:
+          type: string
+
+    ArchitectureLayer:
+      type: object
+      properties:
+        name:
+          type: string
+        type:
+          type: string
+          enum: [entities, use-cases, interface-adapters, frameworks-drivers]
+        files:
+          type: array
+          items:
+            type: string
+        dependencies:
+          type: array
+          items:
+            type: string
+
+    LayerViolation:
+      type: object
+      properties:
+        fromLayer:
+          type: string
+        toLayer:
+          type: string
+        violationType:
+          type: string
+        location:
+          $ref: '#/components/schemas/CodeLocation'
+
+    DependencyRule:
+      type: object
+      properties:
+        from:
+          type: string
+        to:
+          type: string
+        allowed:
+          type: boolean
+        reason:
+          type: string
+
+    DependencyViolation:
+      type: object
+      properties:
+        from:
+          type: string
+        to:
+          type: string
+        violationType:
+          type: string
+        location:
+          $ref: '#/components/schemas/CodeLocation'
+
+    CircularDependency:
+      type: object
+      properties:
+        cycle:
+          type: array
+          items:
+            type: string
+        severity:
+          type: string
+
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              message:
+                type: string
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+              message:
+                type: string