# plutonomicon/plutarch-plutus architecture

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

- Interactive diagram: https://gitdiagram.com/plutonomicon/plutarch-plutus
- Repository: https://github.com/plutonomicon/plutarch-plutus

## Overview

##### Project type and purpose
- This is a multi-package Haskell monorepo whose centerpiece is Plutarch, a typed embedded DSL (eDSL) for writing efficient Plutus Core validators.
- Subpackages provide:
- Core eDSL implementation (`Plutarch/…`)
- Ledger API adapters (`plutarch-ledger-api/…`)
- Orphan instances & QuickCheck helpers (`plutarch-orphanage/…`)
- Test harness & golden benchmarks (`plutarch-testlib/…`)
- Documentation site (`plutarch-docs/…`)

##### File structure
- Top‐level: configuration (Cabal, Nix, CI keys), then each subdirectory is a self‐contained Cabal package.
- Core package (`Plutarch/…`) is organized into layers:
- Public façade modules (BitString.hs, Pair.hs, etc.)
- Built-in symbols & primitive types (`Plutarch/Builtin/…`)
- Data representation & generic machinery (`Plutarch/DataRepr/…`)
- Internal combinators & type-level plumbing (`Plutarch/Internal/…`)
- Pretty-printing & code generation (`Plutarch/Pretty/…`)
- `plutarch-ledger-api`: adapters that map Plutarch types to on-chain ledger API types (V1, V2, V3).
- `plutarch-orphanage`: implements orphan instances for Plutus Ledger types and QuickCheck instances.
- `plutarch-testlib`: benchmarking, golden tests, QuickCheck laws, scripts generation and evaluation.
- `plutarch-docs`: markdown sources and literate Haskell examples to build the user/developer guide.

##### README for additional insights
- Confirms eDSL purpose, efficiency gains versus PlutusTx, and points to benchmarks.
- Encourages reading the guide under `plutarch-docs`.

##### Main components & relationships
a. Core eDSL Library (Plutarch)
b. Ledger‐API Adapter (plutarch-ledger-api)
c. Orphan Instances & Test Helpers (plutarch-orphanage)
d. Test & Benchmark Suite (plutarch-testlib)
e. Documentation Generator (plutarch-docs)
f. Build & CI (Cabal, Nix, Hercules)

- Core → produces an AST of UPLC terms and a code generator that emits Plutus Core scripts.
- Ledger‐API Adapter depends on Core to map eDSL types to on-chain types (Address, Tx, Value, etc.).
- Orphanage builds on Ledger‐API Adapter to supply missing instances and QuickCheck utilities.
- Testlib pulls in Core + Ledger‐API + Orphanage to generate, benchmark, and golden-test UPLC output.
- Docs import Core (and sometimes examples from Adapter) to render API docs and tutorials.

##### Key architectural patterns
- Layered modular design (Core → Adapter → Orphan → Tests)
- eDSL to AST to code generation pipeline
- Separation of concerns: language core vs. on-chain bindings vs. testing vs. docs
- Heavy use of Haskell’s type classes, generic programming, and type-level guarantees

##### Detail
- Decompose Core into sub-layers to show its internal architecture
- Call out package interdependencies so a reader can trace how new features propagate
- Don’t hesitate to show all four packages plus build infrastructure as distinct nodes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core eDSL Library
    subgraph "Core eDSL Library (Plutarch)"
        direction TB
        Syntax["Syntax & Combinators"]:::code
        TypeRepr["Type Representation"]:::code
        PrimOps["Primitive Operations"]:::code
        Runtime["Runtime Evaluation"]:::code
        CodeGen["Code Emission"]:::code
        AST["UPLC AST"]:::code
        Script["Plutus Core Script"]:::code

        Syntax --> TypeRepr
        TypeRepr --> PrimOps
        PrimOps --> Runtime
        Runtime --> CodeGen
        CodeGen --> AST
        AST --> Script
    end

    %% Other Packages
    Ledger["Ledger API Adapter"]:::code
    Orphan["Orphan Instances & QuickCheck Helpers"]:::code
    Testlib["Test & Benchmark Suite"]:::test
    Docs["Documentation Site"]:::docs
    CI["Build & CI Infrastructure"]:::ci
    Node["Cardano Node / Plutus Interpreter"]:::external

    %% Dependencies
    Ledger -->|"depends on"| Syntax
    Orphan -->|"depends on"| Ledger
    Testlib -->|"depends on"| Syntax
    Testlib -->|"depends on"| Ledger
    Testlib -->|"depends on"| Orphan
    Docs -->|"depends on"| Syntax
    CI -->|"builds & tests"| Syntax
    CI -->|"builds & tests"| Ledger
    CI -->|"builds & tests"| Orphan
    CI -->|"builds & tests"| Testlib
    CI -->|"builds & tests"| Docs
    Script -->|"consumed by"| Node

    %% Click Events for Component Mapping
    click Syntax "https://github.com/plutonomicon/plutarch-plutus/blob/master/Plutarch/Internal/Term.hs"
    click TypeRepr "https://github.com/plutonomicon/plutarch-plutus/blob/master/Plutarch/DataRepr.hs"
    click PrimOps "https://github.com/plutonomicon/plutarch-plutus/blob/master/Plutarch/Builtin.hs"
    click Runtime "https://github.com/plutonomicon/plutarch-plutus/blob/master/Plutarch/Internal/Trace.hs"
    click CodeGen "https://github.com/plutonomicon/plutarch-plutus/blob/master/Plutarch/Pretty.hs"
    click Script "https://github.com/plutonomicon/plutarch-plutus/blob/master/Plutarch/Script.hs"
    click Ledger "https://github.com/plutonomicon/plutarch-plutus/tree/master/plutarch-ledger-api/src/Plutarch/LedgerApi/"
    click Orphan "https://github.com/plutonomicon/plutarch-plutus/tree/master/plutarch-orphanage/src/PlutusLedgerApi/Orphans/"
    click Testlib "https://github.com/plutonomicon/plutarch-plutus/tree/master/plutarch-testlib/Plutarch/Test/"
    click Docs "https://github.com/plutonomicon/plutarch-plutus/blob/master/plutarch-docs/Main.lhs"
    click CI "https://github.com/plutonomicon/plutarch-plutus/blob/master/cabal.project"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#004E89,color:#004E89;
    classDef test fill:#E2F8E9,stroke:#1C7C33,color:#1C7C33;
    classDef docs fill:#FFE6C7,stroke:#CC6600,color:#CC6600;
    classDef ci fill:#E0E0E0,stroke:#666666,color:#333333;
    classDef external fill:#F2F2F2,stroke:#999999,color:#666666;
```
