# chipsalliance/cde architecture

> Architecture diagram of the GitHub repository chipsalliance/cde, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chipsalliance/cde
- Repository: https://github.com/chipsalliance/cde

## Overview

##### Project type and purpose
- This is a Scala library (not a webapp or microservice) called “CDE” for Context-Dependent Environments.
- It exposes an API for defining key-value environments that thread through a module hierarchy, with context-sensitive lookup semantics.
- It provides core classes: Parameters, Field, Config, ChainParameters, ChainView, and utility methods (alter, orElse, alterMap, alterPartial).
- It includes tests (cde/tests), documentation (doc/*), and is buildable via Mill (build.sc), with Nix/Flake integration and GitHub Actions CI.

##### File structure
- Top-level build and config: Makefile, build.sc (Mill), .github/workflows/test.yml, flake.nix, overlay.nix, common.sc.
- Source code under cde/src/chipsalliance/rocketchip/config.scala – so package namespace is chipsalliance.rocketchip.cde.
- Test code under cde/tests/src/SanityTest.scala.
- Root README.md describes the API and internal details.
- Formatting config: .scalafmt.conf.

##### README for additional insights
- Public API: `Parameters`, `Field[T]`, `Config`, plus overrides via `alter`, `orElse`.
- Environment reference semantics: `(site, here, up)`.
- Internal representation: binary tree of ChainParameters & ChainView, tree-traversal on lookup.
- Example svg in doc/ChainParameters.svg showing query flow.

a. Main components
- Public API module (Parameters, Field, Config)
- Internal engine (ChainParameters, ChainView, query algorithm)
- Data structures (binary tree of Config layers)
- Test harness (SanityTest)
- Documentation (ChainParameters.tex, ChainParameters.svg)
- Build & CI (Mill build.sc, Nix flakes, GitHub Actions)
b. Relationships & interactions
- Client code invokes Config.apply to produce a Parameters instance.
- Parameters delegates queries to ChainParameters.chain.
- ChainParameters holds left/right child references forming a binary tree.
- ChainView wraps right subtrees, tracking `up` context.
- Query flow: Parameters→ChainParameters→(ChainView)→leaf→(back up tree) until Field found.
- Build system compiles src and tests, runs docs build; CI workflow triggers tests on push.
c. Architectural patterns & principles
- Pure functional API: immutable parameter objects, first-class functions as lookup tables.
- Composite Pattern: Config layers form a tree of Composite nodes (ChainParameters).
- Visitor-like traversal: chain method traverses the tree at query time.
- Separation of concerns: public API vs internal engine vs build & docs vs CI.
d. Key technologies & frameworks
- Scala 2.x/3.x (as implied by .sc sources)
- Mill build tool (build.sc)
- Nix flakes (flake.nix, overlay.nix) for reproducible environment
- GitHub Actions for CI
- LaTeX for documentation (ChainParameters.tex)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Components
    subgraph "Runtime Components"
        direction TB
        PublicAPI["Public API\n(Parameters, Field, Config,\nalter/orElse)"]:::runtime
        InternalEngine["Internal Engine\n(ChainParameters, ChainView,\nquery logic)"]:::runtime
        DataModel["Data Model\n(Config layer binary tree)"]:::runtime
    end

    %% Development Infrastructure
    subgraph "Development Infrastructure"
        direction TB
        TestHarness["Test Harness\n(SanityTest suite)"]:::infra
        Documentation["Documentation\n(LaTeX source)"]:::infra
        subgraph "Build System"
            direction TB
            BuildSC["build.sc"]:::infra
            CommonSC["common.sc"]:::infra
            Makefile["Makefile"]:::infra
        end
        subgraph "Continuous Integration"
            direction TB
            CI["GitHub Actions\n(test.yml)"]:::infra
        end
        subgraph "Nix Environment"
            direction TB
            Flake["flake.nix"]:::infra
            Overlay["overlay.nix"]:::infra
        end
        Formatting[".scalafmt.conf"]:::infra
        Overview["Project Overview\n(README.md & LICENSE)"]:::infra
    end

    %% Query Flow
    PublicAPI -->|"calls chain()"| InternalEngine
    InternalEngine -->|"manages tree"| DataModel
    DataModel -->|"provides lookup"| InternalEngine

    %% Dependency Flow
    PublicAPI -.-> TestHarness
    PublicAPI -.-> Documentation
    PublicAPI -.-> BuildSC
    BuildSC --> CI
    BuildSC -.-> Flake
    BuildSC -.-> Overlay
    BuildSC -.-> Formatting
    BuildSC -.-> Overview
    CI -.-> TestHarness

    %% Click Events
    click PublicAPI "https://github.com/chipsalliance/cde/blob/master/cde/src/chipsalliance/rocketchip/config.scala"
    click InternalEngine "https://github.com/chipsalliance/cde/blob/master/cde/src/chipsalliance/rocketchip/config.scala"
    click DataModel "https://github.com/chipsalliance/cde/blob/master/cde/src/chipsalliance/rocketchip/config.scala"
    click TestHarness "https://github.com/chipsalliance/cde/blob/master/cde/tests/src/SanityTest.scala"
    click Documentation "https://github.com/chipsalliance/cde/blob/master/doc/ChainParameters.tex"
    click BuildSC "https://github.com/chipsalliance/cde/blob/master/build.sc"
    click CommonSC "https://github.com/chipsalliance/cde/blob/master/common.sc"
    click Makefile "https://github.com/chipsalliance/cde/tree/master/Makefile"
    click CI "https://github.com/chipsalliance/cde/blob/master/.github/workflows/test.yml"
    click Flake "https://github.com/chipsalliance/cde/blob/master/flake.nix"
    click Overlay "https://github.com/chipsalliance/cde/blob/master/overlay.nix"
    click Formatting "https://github.com/chipsalliance/cde/blob/master/.scalafmt.conf"
    click Overview "https://github.com/chipsalliance/cde/blob/master/README.md"

    %% Styles
    classDef runtime fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef infra fill:#D5F5E3,stroke:#196F3D,color:#196F3D
```
