# coreruleset/crs-toolchain architecture

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

- Interactive diagram: https://gitdiagram.com/coreruleset/crs-toolchain
- Repository: https://github.com/coreruleset/crs-toolchain

## Overview

##### Project type and purpose
- This is an open‑source, command‑line developer utility (“crs‑toolchain”) written in Go.
- Its purpose is to provide a suite of regex tools, test‑renumbering, self‑update, copyright‑update, and other developer helpers for the OWASP Core Rule Set.

##### File structure
- Top‑level executables:
- main.go
- cmd/ (implements all subcommands: regex, chore, self‑update, etc.)
- Core libraries/packages:
- regex/ (parser, operators, processors, utils)
- configuration/ (app configuration management)
- context/ (shared runtime context)
- internal/updater/ (self‑update logic)
- logger/ (centralized logging)
- util, utils (miscellaneous utilities)
- CI/CD and release:
- .github/workflows, goreleaser.yml, Dockerfile

##### README for additional insights
- It’s a developer “utility belt” with multiple commands.
- Documentation and usage guides are external, so the code itself is the canonical source of architecture.

##### Elements
- Blue for user‑facing CLI components
- Green for core libraries
- Orange for internal services
- Gray for external systems (filesystem, network)
- Rectangles for packages/modules

##### Final advice
- Be exhaustive: include every major package as its own node.
- Dependencies so that a new engineer can see “this module calls that module.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "CLI Frontend"
        direction TB
        Main["main.go"]:::cli
        Root["cmd/root.go"]:::cli
        RegexCmd["cmd/regex.go"]:::cli
        ChoreCmd["cmd/chore.go"]:::cli
        ChoreUpdate["cmd/chore_update_copyright.go"]:::cli
        SelfUpdateCmd["cmd/self_update.go"]:::cli
        VersionCmd["cmd/version.go"]:::cli
        CompletionCmd["cmd/completion.go"]:::cli
    end

    subgraph "Core Libraries"
        direction TB
        Parser["regex/parser/parser.go"]:::core
        Operators["regex/operators/assembler.go\n& operators.go"]:::core
        Processors["regex/processors/processors.go"]:::core
        RegexUtils["regex/utils.go"]:::core
        Config["configuration/configuration.go"]:::core
        ContextMgr["context/context.go"]:::core
        Logger["logger/logger.go"]:::core
        Renumber["util/renumber_tests.go"]:::core
        Utils["utils/utils.go"]:::core
    end

    subgraph "Internal Services"
        direction TB
        Updater["internal/updater/updater.go"]:::internal
    end

    subgraph "External Systems"
        direction TB
        FS[(File System)]:::external
        Network((Network)):::external
        CICD[(CI/CD & Release Config)]:::external
    end

    %% Connections CLI
    Main --> Root
    Root --> RegexCmd
    Root --> ChoreCmd
    Root --> SelfUpdateCmd
    Root --> VersionCmd
    Root --> CompletionCmd

    %% Regex flow
    RegexCmd --> Parser
    Parser --> Operators
    Operators --> Processors
    Processors --> FS

    %% Chore flow
    ChoreCmd --> Renumber
    ChoreCmd --> Config
    ChoreUpdate --> FS

    %% Self-update flow
    SelfUpdateCmd --> Updater
    Updater --> Network

    %% Common dependencies
    RegexCmd --> Logger
    ChoreCmd --> Logger
    SelfUpdateCmd --> Logger
    VersionCmd --> Logger
    CompletionCmd --> Logger

    RegexCmd --> ContextMgr
    ChoreCmd --> ContextMgr
    SelfUpdateCmd --> ContextMgr
    VersionCmd --> ContextMgr
    CompletionCmd --> ContextMgr

    RegexCmd --> Config
    ChoreCmd --> Config
    SelfUpdateCmd --> Config

    %% External CI/CD
    Main --> CICD
    Root --> CICD

    %% Click Events
    click Main "https://github.com/coreruleset/crs-toolchain/blob/main/main.go"
    click Root "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/root.go"
    click RegexCmd "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/regex.go"
    click ChoreCmd "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/chore.go"
    click ChoreUpdate "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/chore_update_copyright.go"
    click SelfUpdateCmd "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/self_update.go"
    click VersionCmd "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/version.go"
    click CompletionCmd "https://github.com/coreruleset/crs-toolchain/blob/main/cmd/completion.go"
    click Parser "https://github.com/coreruleset/crs-toolchain/blob/main/regex/parser/parser.go"
    click Operators "https://github.com/coreruleset/crs-toolchain/blob/main/regex/operators/assembler.go"
    click Processors "https://github.com/coreruleset/crs-toolchain/blob/main/regex/processors/processors.go"
    click RegexUtils "https://github.com/coreruleset/crs-toolchain/blob/main/regex/utils.go"
    click Config "https://github.com/coreruleset/crs-toolchain/blob/main/configuration/configuration.go"
    click ContextMgr "https://github.com/coreruleset/crs-toolchain/blob/main/context/context.go"
    click Logger "https://github.com/coreruleset/crs-toolchain/blob/main/logger/logger.go"
    click Renumber "https://github.com/coreruleset/crs-toolchain/blob/main/util/renumber_tests.go"
    click Utils "https://github.com/coreruleset/crs-toolchain/blob/main/utils/utils.go"
    click Updater "https://github.com/coreruleset/crs-toolchain/blob/main/internal/updater/updater.go"
    click CICD "https://github.com/coreruleset/crs-toolchain/blob/main/.goreleaser.yml"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,color:#004085
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef internal fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
