Skip to content

Architecture Section Reorganization Summary

This document summarizes the architecture section reorganization that was completed to improve documentation structure and maintainability.

Reorganization Overview

The architecture section was reorganized following the established pattern of breaking down large monolithic documents into smaller, focused topics organized in logical subdirectories. This transformation significantly improves documentation usability, maintainability, and extensibility.

Key Changes

  1. Created Comprehensive Subdirectory Structure:
  2. /components/ - Core architectural components
  3. /workflows/ - End-to-end workflow processes
  4. /diagrams/ - WCAG-compliant Mermaid diagrams
  5. /deployment/ - Deployment architectures

  6. /integrations/ - CI/CD integration architectures

  7. Created 25 New Markdown Files:

  8. Created standardized index.md and inventory.md files for each subdirectory
  9. Created focused content files in each subdirectory

  10. Each file focuses on a specific aspect of the architecture

  11. Enhanced Documentation Quality:

  12. Added WCAG-compliant Mermaid diagrams throughout
  13. Ensured consistent styling and formatting
  14. Implemented comprehensive cross-references between related topics

  15. Used standardized terminology throughout

  16. Updated Navigation:

  17. Updated mkdocs.yml to reflect the new structure
  18. Created logical grouping in the navigation menu
  19. Ensured proper hierarchy and relationships

New Directory Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
docs/architecture/
├── index.md                  # Main entry point with overview and navigation
├── inventory.md              # Complete listing of all architecture documentation
├── components/               # Core component documentation
│   ├── index.md              # Components overview
│   ├── inventory.md          # Components documentation inventory
│   ├── core-components.md    # Details of main system components
│   ├── security-components.md # Security-focused components
│   └── communication.md      # Component communication patterns
├── workflows/                # Workflow process documentation
│   ├── index.md              # Workflows overview
│   ├── inventory.md          # Workflows documentation inventory
│   ├── standard-container.md # Standard container workflow
│   ├── distroless-container.md # Distroless container workflow
│   ├── sidecar-container.md  # Sidecar container workflow
│   └── security-workflows.md # Security-focused workflows
├── diagrams/                 # Architecture diagrams
│   ├── index.md              # Diagrams overview
│   ├── inventory.md          # Diagrams documentation inventory
│   ├── component-diagrams.md # Component visualization diagrams
│   ├── workflow-diagrams.md  # Workflow visualization diagrams
│   └── deployment-diagrams.md # Deployment visualization diagrams
├── deployment/               # Deployment architectures
│   ├── index.md              # Deployment overview
│   ├── inventory.md          # Deployment documentation inventory
│   ├── script-deployment.md  # Script-based deployment architecture
│   ├── helm-deployment.md    # Helm chart deployment architecture
│   └── ci-cd-deployment.md   # CI/CD integration deployment architecture
└── integrations/             # CI/CD integration architectures
    ├── index.md              # Integrations overview
    ├── inventory.md          # Integrations documentation inventory
    ├── github-actions.md     # GitHub Actions integration architecture
    ├── gitlab-ci.md          # GitLab CI integration architecture
    ├── gitlab-services.md    # GitLab Services integration architecture
    └── custom-integrations.md # Custom integration architecture

Content Creation Details

Components Documentation

The components directory contains documentation about the core architectural components of the scanning system:

  • core-components.md: Detailed information about the main system components
  • security-components.md: Security-focused components and their roles
  • communication.md: Component communication patterns

Workflows Documentation

The workflows directory contains documentation about the end-to-end workflow processes:

  • standard-container.md: Workflow for standard containers
  • distroless-container.md: Workflow for distroless containers
  • sidecar-container.md: Workflow using the sidecar approach
  • security-workflows.md: Security-focused workflows

Diagrams Documentation

The diagrams directory contains WCAG-compliant Mermaid diagrams visualizing the architecture:

  • component-diagrams.md: Visualization of system components
  • workflow-diagrams.md: Visualization of workflow processes
  • deployment-diagrams.md: Visualization of deployment architectures

Deployment Documentation

The deployment directory contains documentation about different deployment architectures:

  • script-deployment.md: Script-based deployment architecture
  • helm-deployment.md: Helm chart deployment architecture
  • ci-cd-deployment.md: CI/CD integration deployment architecture

Integrations Documentation

The integrations directory contains documentation about CI/CD integration architectures:

  • github-actions.md: GitHub Actions integration architecture
  • gitlab-ci.md: GitLab CI integration architecture
  • gitlab-services.md: GitLab Services integration architecture
  • custom-integrations.md: Custom integration architecture

Benefits of Reorganization

The architecture section reorganization provides several key benefits:

  1. Improved Readability: Smaller, focused documents are easier to read and understand
  2. Enhanced Maintainability: Focused files are easier to update and maintain
  3. Better Navigation: Logical subdirectory structure makes information easier to find
  4. Consistent Structure: Follows the established pattern from other sections
  5. Comprehensive Coverage: Ensures all aspects of the architecture are documented
  6. Improved Visualization: WCAG-compliant diagrams throughout improve understanding
  7. Clear Relationships: Cross-references show relationships between components

Next Steps

After completing the architecture section reorganization, the next steps in the documentation refactoring process are:

  1. Proceed with Integration section reorganization
  2. Continue Phase 4 (review and refinement) of documentation refactoring
  3. Address remaining documentation gaps
  4. Implement documentation validation tools