# botingw/rulebook-ai architecture

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

- Interactive diagram: https://gitdiagram.com/botingw/rulebook-ai
- Repository: https://github.com/botingw/rulebook-ai

## Overview

##### Project type and purpose
- This is a Python-based CLI “template manager” for AI-coding-assistant rule sets.
- It ships with:
- A library of predefined rule sets (`rule_sets/`)
- Memory-starter documents (`memory_starters/`)
- Tool starter scripts (`tool_starters/`)
- A core script (`src/manage_rules.py`) that installs/synchronizes/cleans these assets into a user’s target project.
- Goal: standardize AI assistant behavior (Cursor, CLINE, RooCode, Windsurf, GitHub Copilot) across any codebase.

##### File structure
- Top-level:
- `.env.example`, `requirements.txt` – environment bootstrap files
- `src/manage_rules.py` – CLI entrypoint implementing subcommands: `list-rules`, `install`, `sync`, `clean-rules`, `clean-all`
- `rule_sets/` – multiple rule-set variants (light, medium, heavy, no-memory)
- `memory_starters/` & `tool_starters/` – seed files for the target project’s `memory/` and `tools/`
- `memory/` – actual “memory bank” docs after install
- `tests/` – integration & unit tests for the CLI and tool scripts
- Patterns:
- Template + generator pattern: transforms static templates into target-project artifacts
- Clear separation of “source” (in this repo) vs. “target” (user’s project)

##### Key insights from the README
- Defines the **Source Template Repo** vs. a **Target Repo**
- Describes workflow & commands:
- **install** → copies templates into target (`project_rules/`, `memory/`, `tools/`, `env.example`, `requirements.txt`), then **sync**
- **sync** → regenerates platform-specific rule directories (`.cursor/`, `.clinerules/`, `.roo/`, `.windsurf/`, `.github/copilot-instructions.md`)
- **clean-rules**, **clean-all** → cleanup workflows
- Highlights cross-platform outputs consumed by AI assistants

##### Main components
a. Inputs (blue rectangles):
- rule_sets/ (templates)
- memory_starters/ (docs templates)
- tool_starters/ (utility scripts)
- env.example, requirements.txt
- CLI (`manage_rules.py`) with subcommands:
- -rules
- install
- sync
- clean-rules / clean-all
- Target-project directories:
- project_rules/ (copied rule files)
- memory/ (populated docs/tasks)
- tools/ (copied scripts)
- env.example, requirements.txt
- Generated AI-assistant rule modules:
- .cursor/rules/
- .clinerules/
- .roo/…
- .windsurf/rules/
- .github/copilot-instructions.md
d. External actors/services (gray parallelogram):
- AI coding assistants (Cursor, CLINE, RooCode, Windsurf, Copilot)
- Python runtime & dependencies (Conda environment, Playwright)

##### Relationships & data flow
- AI assistants consume the generated rule directories/files in the target project.

##### Architectural patterns & design principles
- Template + generator (code-generation)
- Clear separation of concerns: “source templates” vs “generated artifacts”
- Modular (each rule set is a plugin)
- Idempotent file operations (non-destructive copy for starters, destructive for clean commands)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Inputs
    subgraph "Inputs"
        RS["rule_sets/"]:::input
        MS["memory_starters/"]:::input
        TS["tool_starters/"]:::input
        EE[".env.example"]:::input
        RT["requirements.txt"]:::input
    end

    %% Core Engine
    subgraph "Core Engine"
        CLI["manage_rules.py"]:::core
        CLIB["manage_rules_backup.py"]:::core
    end

    %% Outputs
    subgraph "Generated Artifacts"
        PR["project_rules/"]:::output
        MO["memory/"]:::output
        MD["memory/docs/... & memory/tasks/..."]:::output
        TO["tools/"]:::output
        EO["env.example & requirements.txt"]:::output
        subgraph "AI Assistant Modules"
            CUR[".cursor/rules/"]:::output
            CLINE[".clinerules/"]:::output
            ROO[".roo/…"]:::output
            WIN[".windsurf/rules/"]:::output
            COP[".github/copilot-instructions.md"]:::output
        end
    end

    %% External Actors
    subgraph "External Services & Runners"
        AI["AI Coding Assistants"]:::external
        PY["Python Runtime & Dependencies"]:::external
        subgraph "Tests"
            IT["test_manage_rules.py"] 
            ITB["test_manage_rules_backup.py"] 
            UT1["test_llm_api.py"] 
            UT2["test_screenshot_verification.py"] 
            UT3["test_search_engine.py"] 
            UT4["test_web_scraper.py"] 
        end
    end

    %% Data Flows
    RS -->|"template source"| CLI
    MS -->|"template source"| CLI
    TS -->|"template source"| CLI
    EE -->|"template source"| CLI
    RT -->|"template source"| CLI

    CLI -->|"install"| PR
    CLI -->|"install"| MO
    CLI -->|"install"| TO
    CLI -->|"install"| EO

    CLI -->|"sync"| CUR
    CLI -->|"sync"| CLINE
    CLI -->|"sync"| ROO
    CLI -->|"sync"| WIN
    CLI -->|"sync"| COP

    CLI -->|"clean-rules"| PR
    CLI -->|"clean-all"| PR
    CLI -->|"clean-all"| MO
    CLI -->|"clean-all"| TO

    AI -->|"consumes"| CUR
    AI -->|"consumes"| CLINE
    AI -->|"consumes"| ROO
    AI -->|"consumes"| WIN
    AI -->|"consumes"| COP

    IT -.->|invokes| CLI
    ITB -.->|invokes| CLIB
    UT1 -.->|tests| CLI
    UT2 -.->|tests| CLI
    UT3 -.->|tests| CLI
    UT4 -.->|tests| CLI

    PY -->|"runs"| CLI

    %% Click Events
    click RS "https://github.com/botingw/rulebook-ai/tree/main/rule_sets/"
    click MS "https://github.com/botingw/rulebook-ai/tree/main/memory_starters/"
    click TS "https://github.com/botingw/rulebook-ai/tree/main/tool_starters/"
    click EE "https://github.com/botingw/rulebook-ai/blob/main/.env.example"
    click RT "https://github.com/botingw/rulebook-ai/blob/main/requirements.txt"
    click CLI "https://github.com/botingw/rulebook-ai/blob/main/src/manage_rules.py"
    click CLIB "https://github.com/botingw/rulebook-ai/blob/main/src/manage_rules_backup.py"
    click IT "https://github.com/botingw/rulebook-ai/blob/main/tests/integration/test_manage_rules.py"
    click ITB "https://github.com/botingw/rulebook-ai/blob/main/tests/integration/test_manage_rules_backup.py"
    click UT1 "https://github.com/botingw/rulebook-ai/blob/main/tests/test_llm_api.py"
    click UT2 "https://github.com/botingw/rulebook-ai/blob/main/tests/test_screenshot_verification.py"
    click UT3 "https://github.com/botingw/rulebook-ai/blob/main/tests/test_search_engine.py"
    click UT4 "https://github.com/botingw/rulebook-ai/blob/main/tests/test_web_scraper.py"
    click MO "https://github.com/botingw/rulebook-ai/tree/main/memory/"
    click MD "https://github.com/botingw/rulebook-ai/tree/main/memory/docs/ and memory/tasks/"

    %% Styles
    classDef input fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef output fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
