# thought-machine/please architecture

> Architecture diagram of the GitHub repository thought-machine/please, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thought-machine/please
- Repository: https://github.com/thought-machine/please

## Overview

##### Main Components

a. Core Build Engine:
- Build Graph Management (src/core/graph.go)
- Target Resolution (src/core/build_target.go)
- Configuration System (src/core/config.go)
- State Management (src/core/state.go)

b. Parser Layer:
- ASP Parser (src/parse/asp)
- Build File Parser
- Configuration Parser

c. Execution Layer:
- Build Step Executor (src/build)
- Test Runner (src/test)
- Remote Execution Support (src/remote)
- Sandbox Environment (src/sandbox)

d. Cache System:
- Local Cache (src/cache)
- Remote Cache
- HTTP Cache Support
- Directory Cache

e. CLI Interface:
- Command Processing (src/cli)
- Output Formatting (src/output)
- Progress Tracking
- Interactive Display

##### Relationships

- Data flow between components
- Dependency relationships
- Control flow
- Cache interactions

##### Design Elements

Use these visual elements:
- Rectangles: Core components
- Hexagons: External interfaces

##### Detailed Component Breakdown

Core Build Engine:
**┌─────────────────────┐**
- Build Engine      │
- ┤
- Graph Management  │
- Target Resolution │
- Config System     │
- State Management  │
- ┘

Parser Layer:
**┌─────────────────┐**
- Parser Layer   │
- ┤
- ASP Parser    │
- Build Parser  │
- Config Parser │
- ┘

##### Integration Points

Integration with:
- External build tools
- Language-specific compilers
- Remote build systems
- CI/CD systems

##### Key Workflows

Main workflows:
a. Build Process:
CLI → Parser → Build Engine → Executor → Cache
b. Test Process:
CLI → Parser → Test Runner → Results
c. Remote Execution:
Build Engine → Remote Executor → Cache

##### Performance Features

Emphasize:
- Parallel execution paths
- Caching mechanisms
- Incremental build support
- Remote execution capabilities

##### Extension Points

Plugin architecture:
- Custom build rules
- Language support
- Tool integration
- Remote execution adapters

##### Implementation Notes

Technical details:
- Written in Go
- Hermetic build execution
- Hash-based caching
- Parallel execution support

Remember to emphasize the key features that make Please unique:
- Cross-language support
- Extensibility
- Performance optimization
- Caching strategy
- Hermetic builds

This will create a comprehensive yet clear representation of the Please build system's architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph CLI
        CLI_PROC["Command Processing"]:::cli
        PROGRESS["Progress Tracking"]:::cli
        OUTPUT["Output Formatting"]:::cli
        DISPLAY["Interactive Display"]:::cli
    end

    subgraph Core["Core Build Engine"]
        GRAPH["Build Graph Management"]:::core
        TARGET["Target Resolution"]:::core
        CONFIG["Configuration System"]:::core
        STATE["State Management"]:::core
        BUILD_ENV["Build Environment"]:::core
        PACKAGE["Package Management"]:::core
        SUBREPO["Subrepo Support"]:::core
    end

    subgraph Parser
        ASP["ASP Parser"]:::parser
        BUILD_PARSER["Build File Parser"]:::parser
        PKG_PARSER["Package Parser"]:::parser
    end

    subgraph Execution
        BUILD_EXEC["Build Step Executor"]:::exec
        TEST_RUNNER["Test Runner"]:::exec
        REMOTE_EXEC["Remote Execution"]:::exec
        SANDBOX["Sandbox Environment"]:::exec
    end

    subgraph Cache
        CORE_CACHE["Core Cache Interface"]:::cache
        DIR_CACHE["Directory Cache"]:::cache
        HTTP_CACHE["HTTP Cache"]:::cache
        ASYNC_CACHE["Async Cache"]:::cache
    end

    %% Relationships
    CLI_PROC --> GRAPH
    PROGRESS --> STATE
    OUTPUT --> STATE
    DISPLAY --> STATE

    GRAPH --> BUILD_EXEC
    TARGET --> BUILD_EXEC
    CONFIG --> STATE
    STATE --> BUILD_EXEC

    ASP --> GRAPH
    BUILD_PARSER --> GRAPH
    PKG_PARSER --> PACKAGE

    BUILD_EXEC --> CORE_CACHE
    TEST_RUNNER --> CORE_CACHE
    REMOTE_EXEC --> CORE_CACHE

    CORE_CACHE --> DIR_CACHE
    CORE_CACHE --> HTTP_CACHE
    CORE_CACHE --> ASYNC_CACHE

    BUILD_ENV --> BUILD_EXEC
    PACKAGE --> BUILD_EXEC
    SUBREPO --> BUILD_EXEC

    %% Click Events
    click GRAPH "https://github.com/thought-machine/please/blob/master/src/core/graph.go"
    click TARGET "https://github.com/thought-machine/please/blob/master/src/core/build_target.go"
    click CONFIG "https://github.com/thought-machine/please/blob/master/src/core/config.go"
    click STATE "https://github.com/thought-machine/please/blob/master/src/core/state.go"
    click BUILD_ENV "https://github.com/thought-machine/please/blob/master/src/core/build_env.go"
    click PACKAGE "https://github.com/thought-machine/please/blob/master/src/core/package.go"
    click SUBREPO "https://github.com/thought-machine/please/blob/master/src/core/subrepo.go"
    click ASP "https://github.com/thought-machine/please/tree/master/src/parse/asp/"
    click BUILD_PARSER "https://github.com/thought-machine/please/blob/master/src/parse/parse_step.go"
    click PKG_PARSER "https://github.com/thought-machine/please/blob/master/src/parse/internal_package.go"
    click BUILD_EXEC "https://github.com/thought-machine/please/blob/master/src/build/build_step.go"
    click TEST_RUNNER "https://github.com/thought-machine/please/blob/master/src/test/test_step.go"
    click REMOTE_EXEC "https://github.com/thought-machine/please/blob/master/src/remote/remote.go"
    click SANDBOX "https://github.com/thought-machine/please/blob/master/src/sandbox/sandbox_linux.go"
    click CORE_CACHE "https://github.com/thought-machine/please/blob/master/src/cache/cache.go"
    click DIR_CACHE "https://github.com/thought-machine/please/blob/master/src/cache/dir_cache.go"
    click HTTP_CACHE "https://github.com/thought-machine/please/blob/master/src/cache/http_cache.go"
    click ASYNC_CACHE "https://github.com/thought-machine/please/blob/master/src/cache/async_cache.go"
    click CLI_PROC "https://github.com/thought-machine/please/blob/master/src/cli/flags.go"
    click OUTPUT "https://github.com/thought-machine/please/blob/master/src/output/print.go"
    click PROGRESS "https://github.com/thought-machine/please/blob/master/src/cli/progress.go"
    click DISPLAY "https://github.com/thought-machine/please/blob/master/src/output/interactive_display.go"

    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef parser fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef exec fill:#4CAF50,stroke:#388E3C,color:white
    classDef cache fill:#FFC107,stroke:#FFA000,color:black
    classDef cli fill:#607D8B,stroke:#455A64,color:white

    %% Legend
    subgraph Legend
        L_CORE["Core Components"]:::core
        L_PARSER["Parser Components"]:::parser
        L_EXEC["Execution Components"]:::exec
        L_CACHE["Cache Components"]:::cache
        L_CLI["CLI Components"]:::cli
    end
```
