# hashiiiii/airules architecture

> Architecture diagram of the GitHub repository hashiiiii/airules, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hashiiiii/airules
- Repository: https://github.com/hashiiiii/airules

## Overview

##### Main Components
- CLI Interface & Command Handler: Represented by the files in the “cmd” directory (init.go, install.go, root.go, template.go, version.go) and the main.go file. This is the entry point where command-line arguments are parsed.
- Installer Modules: In the “pkg/installer” package, you have separate installer implementations for Cursor and Windsurf (e.g., cursor_installer.go, windsurf_installer.go). They encapsulate the logic for installing configuration files.
- Configuration & Template Management: The “pkg/config” and “pkg/template” components. These modules manage configuration reading, validation, and the generation or customization of configuration files using templates.
- Error & Version Handling: In packages like “pkg/errors” and “pkg/version” provide centralized error definitions and version information functionality.
- Output Management: “pkg/output” to encapsulate any display or logging/feedback routines.
- Auxiliary Resources: The “templates” directory provides default configuration templates, while the README’s mention of a “vendor/rules-for-ai” directory (though not part of the file tree) indicates additional external template resources.

##### Relationships and Interactions
- The CLI component (cmd/ and main.go) routes user commands to the appropriate installer module.
- Depending on the command (e.g., “airules windsurf” vs. “airules cursor”), control is passed to the respective installer (from pkg/installer), which then takes user options (local or global installation) and reads from the templates.
- The installer modules interact with the configuration management component (pkg/config) to determine file locations and manage file read/write operations.
- The output module (pkg/output) is used to display information regarding successful installation or errors.
- Version and error modules are invoked as needed to provide diagnostic and versioning feedback.

##### Architectural Patterns and Design Principles
- Modularity: The project is separated into well-defined packages for installer functions, configuration management, error handling, and CLI command parsing.
- Separation of Concerns: Each package has a clear responsibility (e.g., installation logic vs. version reporting) which makes the system easier to maintain and extend.
- Command Pattern: The command-line interface uses commands and flags to direct behavior, evident from separate command files under the “cmd” directory.

##### Relevant Technologies & Frameworks
- Go Modules: Indicated by go.mod and go.sum, establishing dependency management in a Go project.
- CI/CD and Linting: GitHub actions (in .github/workflows) and tools like golangci are used for testing and linting.
- Configuration File Standards: The README illustrates knowledge of platform-specific configuration storage locations.

##### Essential Elements
- From user input/command to the CLI parser
- From CLI to the appropriate installer based on command-line flags
- From installer to config/template manager (for fetching and customization)
- From installer to file system operations (write/read configuration files)
- Core business logic (installer implementations, config management)
- System interfaces (CLI, file system interactions)
- Supporting modules (error handling, output management)

##### Additional Notes
- Be very detailed and ensure that inter-module interactions (especially how different installers manage local vs. global configuration paths as per the README) are clearly represented.
- While the architecture is not overly complex, breaking down the system into small, complementary components (each with a precise role) will help in discussions with stakeholders or developers who need to extend functionality in the future.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Main["CLI Entry (main.go)"]:::cli
        CLI_CMD["CLI Command Handler (cmd)"]:::cli
    end

    %% Installer Modules
    subgraph "Installer Modules"
        Windsurf["Windsurf Installer"]:::installer
        Cursor["Cursor Installer"]:::installer
    end

    %% Configuration & Template Management
    subgraph "Configuration & Template Management"
        Config["Configuration Manager"]:::core
        Template["Template Manager"]:::core
    end

    %% Supporting Services
    subgraph "Supporting Services"
        Error["Error Handling"]:::support
        Version["Version Handling"]:::support
        Output["Output Management"]:::support
    end

    %% Auxiliary Resources
    subgraph "Auxiliary Resources"
        TemplatesDir["Templates Directory"]:::aux
    end

    %% Connections
    CLI_Main -->|"calls"| CLI_CMD
    CLI_CMD -->|"routes_to"| Windsurf
    CLI_CMD -->|"routes_to"| Cursor
    CLI_CMD -->|"version_command"| Version
    Windsurf -->|"reads_config"| Config
    Cursor -->|"reads_config"| Config
    Windsurf -->|"fetches_template"| Template
    Cursor -->|"fetches_template"| Template
    Template -->|"loads_from"| TemplatesDir
    Windsurf -->|"outputs_status"| Output
    Cursor -->|"outputs_status"| Output
    Windsurf -->|"reports_error"| Error
    Cursor -->|"reports_error"| Error

    %% Click Events
    click CLI_Main "https://github.com/hashiiiii/airules/blob/main/main.go"
    click CLI_CMD "https://github.com/hashiiiii/airules/tree/main/cmd"
    click Windsurf "https://github.com/hashiiiii/airules/blob/main/pkg/installer/windsurf_installer.go"
    click Cursor "https://github.com/hashiiiii/airules/blob/main/pkg/installer/cursor_installer.go"
    click Config "https://github.com/hashiiiii/airules/blob/main/pkg/config/config.go"
    click Template "https://github.com/hashiiiii/airules/blob/main/pkg/template/template.go"
    click TemplatesDir "https://github.com/hashiiiii/airules/tree/main/templates"
    click Error "https://github.com/hashiiiii/airules/blob/main/pkg/errors/errors.go"
    click Version "https://github.com/hashiiiii/airules/blob/main/pkg/version/version.go"
    click Output "https://github.com/hashiiiii/airules/blob/main/pkg/output/output.go"

    %% Styles
    classDef cli fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef installer fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef support fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef aux fill:#D7BDE2,stroke:#512E5F,stroke-width:2px;
```
