Skip to content

Architecture.md

Latest commit

 

History

History
274 lines (224 loc) · 9.21 KB

Architecture.md

File metadata and controls

274 lines (224 loc) · 9.21 KB

Architecture

Physical Architecture

Physical Architecture Block

The Physical Architecture represents the concrete systems, services, and components that implement the functionality of Reqvire. It defines the deployment-level structure of the tool, detailing how various components interact and are organized in the actual system.

graph TD
    subgraph Reqvire["Reqvire System"]
        subgraph ReqvireTool["ReqvireTool Subsystem"]
            subgraph UserInterface["UserInterface"]
                CLI["CLI"]
                ChatOps["ChatOps"]
            end
            ModelManagement["ModelManagement"]
            ValidationAndReporting["ValidationAndReporting"]
            Storage["Storage"]
        end

        subgraph Integrations["Integrations Subsystem"]
            GitHubIntegration["GitHubIntegration"]
            subgraph CICDIntegration["CICDIntegration"]
                AIWorkflows["AIWorkflows"]
            end
        end
    end
Loading

Logical to Physical Architecture Mapping:

graph TD
    %% Root System
    Reqvire["Reqvire (system)"]

    %% Subsystems under Reqvire
    subgraph ReqvireTool["ReqvireTool (subsystem)"]
        UserInterface["UserInterface (component)"]
        ModelManagement["ModelManagement (component)"]
        ValidationAndReporting["ValidationAndReporting (component)"]
        Storage["Storage (component)"]
    end

    subgraph Integrations["Integrations (subsystem)"]
        GitHubIntegration["GitHubIntegration (component)"]
        CICDIntegration["CICDIntegration (component)"]
    end

    subgraph AIWorkflows["AIWorkflows (workflow)"]
        AIWorkflowsComponent["AIWorkflows (workflow)"]
    end

    %% AI component (added based on the logical architecture)
    AI["AI (component)"]

    %% Systems
    SystemOfInterest["SystemOfInterest (system)"]

    %% Hierarchical Structure
    Reqvire --> ReqvireTool
    Reqvire --> Integrations
    Reqvire --> AIWorkflows

    ReqvireTool --> UserInterface
    ReqvireTool --> ModelManagement
    ReqvireTool --> ValidationAndReporting
    ReqvireTool --> Storage

    UserInterface --> CLI["CLI (component)"]
    UserInterface --> ChatOps["ChatOps (component)"]

    Integrations --> GitHubIntegration
    Integrations --> CICDIntegration

    CICDIntegration --> AIWorkflowsComponent

    AIWorkflowsComponent --> AI

    SystemOfInterest --> Storage
Loading

Metadata

  • type: block

Relations

Logical Architecture

Logical Architecture Block

The Logical Architecture for Reqvire defines the high-level functional organization of the tool, focusing on the main components that deliver its core functionalities. This architecture serves as the foundation for further refinement into physical architecture and system requirements.

classDiagram
    class UserInteraction {
        +CLIInterface
        +ChatOpsInterface
    }
    class CLI {
        +InteractWithModelManagement()
    }
    class ModelManagement {
        +ManageModel()
        +GenerateDiagrams()
        +AnalyzeRelations()
        +ValidateStructure()
        +TraceChanges()
        +GenerateTraceabilityMatrix()
    }
    class AI {
        +ProvideAISuggestions()
        +DevelopSystemOfInterest()
        +ApplyAISuggestions()
        +CallModelManagementFunctions()
    }
    class AIWorkflow {
        +DriveAIAgentsDevelopment()
        +ProvidesCollaborationFeedback()
        +TrackSystemOfInterestProgress()
    }
    class ValidationAndReporting {
        +ValidateMarkdownStructure()
        +ValidateFilesystemStructure()
        +ValidateModelConsistency()
        +FixModelIssues()
        +GenerateReports()
    }
    class Storage {
        +GitRepository
        +ModelStorage
    }
    class Integrations {
        +CollaboratesWithGitHub()
        +CollaboratesWithCICD()
    }

    class GitHubIntegration {
    }

    class CICDIntegration {
        +TriggerBuilds()
        +RunTests()
        +RunActions()
        +TriggerValidations()
    }

    class SystemOfInterest {
        +MBSEModel
        +DevelopedSystem
    }

    %% Relationships
    UserInteraction --> CLI : "Interacts via CLI"
    UserInteraction --> AI : "Interacts via ChatOps"
    CLI --> ModelManagement
    AI --> ModelManagement : "Calls Functions for Model Management"
    CLI --> ValidationAndReporting : "Triggers validation/fixing/reporting"
    CLI --> Storage : "Reads/Writes Model Data"
    AI --> ValidationAndReporting : "Provides AI Validation Suggestions"
    AI --> Storage : "Saves Approved Changes"
    ValidationAndReporting --> Storage : "Accesses Model Data"
    Integrations --> ValidationAndReporting : "Triggers Validations"
    Integrations --> GitHubIntegration : "Manages GitHub-related tasks"
    Integrations --> CICDIntegration : "Manages CI/CD workflows"
    GitHubIntegration --> Storage : "Syncs changes with Git Repository"
    GitHubIntegration --> AIWorkflow : "Triggers AI-driven commits/changes"
    GitHubIntegration --> ModelManagement : "Facilitates version control of model"
    CICDIntegration --> GitHubIntegration : "Triggers actions based on PR/Merge status"
    CICDIntegration --> ValidationAndReporting : "Performs automated validations during builds"
    CICDIntegration --> AIWorkflow : "Enables AI-driven tests and deployment"

    Storage --> SystemOfInterest : "Stores MBSE Model and Developed System"

    %% New AIWorkflow Component Relationships
    AIWorkflow --> Integrations : "Collaborates with CI/CD and Github"
    AIWorkflow --> SystemOfInterest : "Guides System Development"
    AIWorkflow --> AI : "Drives AI Agent Actions"
    AIWorkflow --> ModelManagement : "Interacts with Model Management Functions"
Loading

Metadata

  • type: block

Relations

Implementation Architecture

Elements

CRUD Operations Delegation Pattern

The system shall implement all CRUD operations using a delegation pattern where the CRUD layer orchestrates user requests and delegates validation and execution to the graph_registry layer.

Details

All element manipulation operations follow this architectural pattern:

  • CRUD layer (crud.rs) provides public API and orchestration logic
  • Graph registry layer (graph_registry.rs) performs validation and executes changes
  • CRUD delegates to graph_registry for all model mutations

Operation Delegation Mapping:

crud.add_element() → graph_registry.add_element_to_file()
crud.remove_element() → graph_registry.remove_element_with_cleanup()
crud.move_element() → graph_registry.move_element_comprehensive()
crud.merge_elements() → graph_registry.merge_elements()
crud.rename_element() → graph_registry.rename_element()
crud.link() → graph_registry.add_element_relation_full()
crud.unlink() → graph_registry.remove_element_relation_full()

Benefits:

  • Clear separation of concerns between orchestration and execution
  • Centralized validation logic in graph_registry
  • Consistent error handling across all operations
  • Maintainable and testable code structure

Metadata

  • type: requirement

Relations

Shared Utility Functions

The system shall extract common code patterns into shared utility functions to reduce duplication and maintain consistency across modules.

Details

When a code pattern appears in multiple locations, it should be extracted into a shared utility function. This follows the DRY (Don't Repeat Yourself) principle and improves maintainability.

Example: Parent Directory Extraction The get_parent_dir() utility function provides consistent parent directory extraction logic used across crud.rs and graph_registry.rs, replacing 6 instances of duplicate code.

pub fn get_parent_dir(file_path: &str) -> PathBuf {
    PathBuf::from(file_path).parent()
        .map(|p| p.to_path_buf())
        .unwrap_or_default()
}

Benefits:

  • Eliminates code duplication
  • Single source of truth for common operations
  • Easier to test and maintain
  • Consistent behavior across modules

Metadata

  • type: requirement

Relations