# lmittmann/go-solc architecture

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

- Interactive diagram: https://gitdiagram.com/lmittmann/go-solc
- Repository: https://github.com/lmittmann/go-solc

## Overview

##### Project type and purpose
- This is a Go library/CLI‐style tool (“go-solc”) that provides Go bindings around the Solidity compiler.
- Purpose: fetch a specified Solidity compiler version from the official binaries site, cache it locally, and invoke it with configured arguments via a Go API.

##### File structure
- Top level:
- compiler.go / console.go / download.go / options.go / params.go / types.go — public API surfaces and orchestrators
- params_*.go + params_gen.go — OS/arch–specific compiler parameter definitions
- internal/console — arguments templating and process spawning
- internal/mod — module/root selection (resolving solc root directory)
- internal/version — version management logic
- examples/ — sample usage and tests
- testdata/ — integration‐style test inputs
- Configuration & metadata: go.mod, CI (/.github/workflows/go.yml), tests alongside each module.

##### README for additional insights
- Describes automatic download of solc binary from https://binaries.soliditylang.org
- Caching location: .solc/bin/solc_vX.Y.Z
- API usage: `solc.New(...).Compile(...)` with optional optimizer settings
- Emphasis on pre-1.0, API may change

##### Main components
a. API Layer
- Public API (compiler.go, console.go, options.go, types.go)
- Exposes New(), Compile(), WithOptimizer(), etc.
b. Version Manager (internal/version)
- Determines requested version, validates, formats version tag
c. Download Manager (download.go)
- Contacts external Solidity binaries endpoint
- Downloads the .tar.gz or binary, unpacks it into cache
d. Local Cache
- Filesystem directory (.solc/bin/)
- Stores versioned solc executables
e. Module Resolver (internal/mod)
- Determines which cache root or external fallback to use
f. Parameter Provider (params_*.go + params_gen.go)
- Supplies OS-arch specific compiler parameters (paths, exec names)
g. Console/Process Runner (internal/console)
- Renders argument templates (args.go.tmpl)
- Spawns child process, captures stdout/stderr
h. External Service
- Solidity compiler binary repository (binaries.soliditylang.org)

##### Relationships and data flows
- User Code → calls Public API →
- API invokes Version Manager → resolves version
- API calls Module Resolver → locates cache path
- If binary not present, API invokes Download Manager → External Service → caches to Local Cache
- Parameter Provider → supplies exec path & flags
- API triggers Console/Process Runner → launches solc → compiler output → returned to caller

##### Architectural patterns & design principles
- Modular layering: each responsibility in its own package (single responsibility)
- Dependency inversion: public API depends on interfaces implemented by internal modules
- Caching layer: avoids redundant downloads
- Template‐driven argument construction for flexibility
- OS/arch abstraction via generated params files

##### Putting it all together
- “Parameter Provider” feeds flags to “Console/Process Runner”
- “Console/Process Runner” executes binary from cache → returns output to API → back to User Code

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Code/Test"] 

    subgraph "API Layer"
        direction TB
        Cmp["compiler.go"]:::api
        Csl["console.go"]:::api
        Opt["options.go"]:::api
        Typ["types.go"]:::api
    end

    subgraph "Version Manager"
        direction TB
        VM["version.go"]:::internal
    end

    subgraph "Module Resolver"
        direction TB
        MR["root.go"]:::internal
    end

    subgraph "Download Manager"
        direction TB
        DM["download.go"]:::internal
    end

    subgraph "Parameter Provider"
        direction TB
        PP["params.go"]:::internal
        PP_gen["params_gen.go"]:::internal
        PP_darwin_amd64["params_darwin_amd64.go"]:::internal
        PP_darwin_arm64["params_darwin_arm64.go"]:::internal
        PP_linux_amd64["params_linux_amd64.go"]:::internal
    end

    subgraph "Console/Process Runner"
        direction TB
        Args["args.go"]:::internal
        ArgT["args.go.tmpl"]:::internal
        ConsoleDrv["console.go"]:::internal
        Gen["gen.go"]:::internal
    end

    subgraph "Infrastructure"
        direction TB
        Cache["Local Cache (.solc/bin/)"]:::infra
        Ext["External Service\nbinaries.soliditylang.org"]:::infra
    end

    %% Flows
    User --> Cmp
    User --> Csl
    User --> Opt
    User --> Typ

    Cmp --> VM
    Csl --> VM
    Opt --> VM
    Typ --> VM

    VM --> MR
    MR -->|check cache| Cache
    MR -->|cache miss| DM
    DM -->|GET solc_vX.Y.Z.tar.gz| Ext
    Ext -->|downloaded binary| DM
    DM -->|unpack| Cache

    Cmp --> PP
    Csl --> PP

    PP --> PP_gen
    PP_gen --> Args
    PP_darwin_amd64 --> PP
    PP_darwin_arm64 --> PP
    PP_linux_amd64 --> PP

    Args --> ConsoleDrv
    ArgT --> ConsoleDrv
    Gen --> ConsoleDrv

    ConsoleDrv -->|spawn process| Cache
    ConsoleDrv -->|stdout/stderr| Cmp

    %% Click Events
    click Cmp "https://github.com/lmittmann/go-solc/blob/main/./compiler.go"
    click Csl "https://github.com/lmittmann/go-solc/blob/main/./console.go"
    click Opt "https://github.com/lmittmann/go-solc/blob/main/./options.go"
    click Typ "https://github.com/lmittmann/go-solc/blob/main/./types.go"
    click VM "https://github.com/lmittmann/go-solc/blob/main/./internal/version/version.go"
    click DM "https://github.com/lmittmann/go-solc/blob/main/./download.go"
    click MR "https://github.com/lmittmann/go-solc/blob/main/./internal/mod/root.go"
    click PP "https://github.com/lmittmann/go-solc/blob/main/./params.go"
    click PP_gen "https://github.com/lmittmann/go-solc/blob/main/./params_gen.go"
    click PP_darwin_amd64 "https://github.com/lmittmann/go-solc/blob/main/./params_darwin_amd64.go"
    click PP_darwin_arm64 "https://github.com/lmittmann/go-solc/blob/main/./params_darwin_arm64.go"
    click PP_linux_amd64 "https://github.com/lmittmann/go-solc/blob/main/./params_linux_amd64.go"
    click Args "https://github.com/lmittmann/go-solc/blob/main/./internal/console/args.go"
    click ArgT "https://github.com/lmittmann/go-solc/blob/main/./internal/console/args.go.tmpl"
    click ConsoleDrv "https://github.com/lmittmann/go-solc/blob/main/./internal/console/console.go"
    click Gen "https://github.com/lmittmann/go-solc/blob/main/./internal/console/gen.go"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef internal fill:#DFFFD0,stroke:#28a745,color:#28a745
    classDef infra fill:#FFD8A8,stroke:#d73a49,color:#d73a49
```
