# simonask/werk architecture

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

- Interactive diagram: https://gitdiagram.com/simonask/werk
- Repository: https://github.com/simonask/werk

## Overview

##### Main Components Identification
The project is structured as a set of Rust crates, each with distinct responsibilities. The main components to include are:

a) Core Components (Primary Crates):
- werk-cli: Entry point and CLI interface
- werk-runner: Core build system and execution engine
- werk-parser: Language parser and AST handling
- werk-fs: File system operations
- werk-vscode: IDE integration

##### Component Relationships and Data Flow

**Top Level:**
**[User Input] → [werk-cli] → [werk-runner] → [File System Output]**

**Detailed Components:**
- ┌─────────────┐
- werk-cli   │
- ┬───────┘

- ┌───────────────────────┬─▼─┬───────────────────────┐

- ┌──────▼──────┐        ┌──────▼───▼──┐            ┌──────▼──────┐
- werk-parser │◄─────►│ werk-runner │◄────────►   │   werk-fs   │
- ┘        └────────────┘             └─────────────┘
- ▲

- ┌─────▼──┴────┐
- werk-vscode │
- ┘

##### Important Subsystems to Detail

For the werk-runner component, show internal modules:
**werk-runner**
- Runner Core
- Evaluator
- Cache System
- Workspace Manager
- I/O Handling
- Shell Operations
- Child Processes
- Dependency Management
- Outdatedness Checker
- Depfile Handler

##### Notes for Implementation Details

- The declarative nature of the system
- The separation between parsing and execution
- The file system abstraction layer
- The VS Code integration pathway

Remember to maintain a balance between showing enough detail to understand the system while keeping it clean and readable. Focus on the core architectural decisions that make Werk unique, such as its approach to build system functionality combined with command running capabilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph User["User Interface Layer"]
        CLI["CLI Interface"]:::cli
        VSC["VS Code Integration"]:::vscode
        FW["File Watcher"]:::cli
    end

    subgraph Core["Core Execution Layer"]
        Runner["Core Runner"]:::runner
        Eval["Evaluator"]:::runner
        Cache["Cache System"]:::runner
        WM["Workspace Manager"]:::runner
        EE["Expression Evaluator"]:::runner
        Val["Value System"]:::runner
        PM["Pattern Matching"]:::runner
        EH["Error Handling"]:::runner
    end

    subgraph IO["I/O Layer"]
        Shell["Shell Operations"]:::io
        Child["Child Process Handler"]:::io
        IOOps["I/O Operations"]:::io
    end

    subgraph Parser["Parser Layer"]
        PC["Parser Core"]:::parser
        AST["AST Handling"]:::parser
    end

    subgraph FS["File System Layer"]
        FSCore["File System Core"]:::fs
        Path["Path Operations"]:::fs
    end

    subgraph DependencyMgmt["Dependency Management"]
        DT["Dependency Tracker"]:::dep
        OC["Outdatedness Checker"]:::dep
    end

    %% Relationships
    CLI --> Runner
    FW --> Runner
    VSC --> Runner

    Runner --> Eval
    Runner --> Cache
    Runner --> WM
    Runner --> EE
    Runner --> Val
    Runner --> PM
    Runner --> EH

    Runner --> Shell
    Runner --> Child
    Runner --> IOOps

    Runner --> PC
    PC --> AST

    Runner --> FSCore
    FSCore --> Path

    Runner --> DT
    Runner --> OC

    %% Click Events
    click CLI "https://github.com/simonask/werk/blob/main/werk-cli/main.rs"
    click FW "https://github.com/simonask/werk/blob/main/werk-cli/watcher.rs"
    click Runner "https://github.com/simonask/werk/blob/main/werk-runner/runner.rs"
    click Eval "https://github.com/simonask/werk/blob/main/werk-runner/eval.rs"
    click Cache "https://github.com/simonask/werk/blob/main/werk-runner/cache.rs"
    click WM "https://github.com/simonask/werk/blob/main/werk-runner/workspace.rs"
    click Shell "https://github.com/simonask/werk/blob/main/werk-runner/shell.rs"
    click Child "https://github.com/simonask/werk/blob/main/werk-runner/io/child.rs"
    click DT "https://github.com/simonask/werk/blob/main/werk-runner/depfile.rs"
    click OC "https://github.com/simonask/werk/blob/main/werk-runner/outdatedness.rs"
    click PC "https://github.com/simonask/werk/blob/main/werk-parser/parser.rs"
    click AST "https://github.com/simonask/werk/blob/main/werk-parser/ast.rs"
    click FSCore "https://github.com/simonask/werk/blob/main/werk-fs/lib.rs"
    click Path "https://github.com/simonask/werk/blob/main/werk-fs/path.rs"
    click VSC "https://github.com/simonask/werk/blob/main/werk-vscode/syntaxes/werk.tmLanguage.json"
    click EE "https://github.com/simonask/werk/blob/main/werk-runner/eval/used.rs"
    click IOOps "https://github.com/simonask/werk/blob/main/werk-runner/io.rs"
    click EH "https://github.com/simonask/werk/blob/main/werk-runner/error.rs"
    click Val "https://github.com/simonask/werk/blob/main/werk-runner/value.rs"
    click PM "https://github.com/simonask/werk/blob/main/werk-runner/pattern.rs"

    %% Styling
    classDef cli fill:#9370DB
    classDef vscode fill:#9370DB
    classDef runner fill:#4169E1
    classDef io fill:#FFA500
    classDef parser fill:#90EE90
    classDef fs fill:#FF7F50
    classDef dep fill:#20B2AA

    %% Legend
    subgraph Legend
        CLI_L["UI Components"]:::cli
        RUNNER_L["Core Components"]:::runner
        IO_L["I/O Components"]:::io
        PARSER_L["Parser Components"]:::parser
        FS_L["File System Components"]:::fs
        DEP_L["Dependency Components"]:::dep
    end
```
