# aead/chacha20 architecture

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

- Interactive diagram: https://gitdiagram.com/aead/chacha20
- Repository: https://github.com/aead/chacha20

## Overview

##### Project type and purpose
- This is an open-source Go library implementing the ChaCha stream cipher family (ChaCha20, XChaCha20, and reduced-round variants).
- Its core purpose is to provide high-performance encryption/decryption routines selectable at build/runtime based on CPU features.

##### File structure
- Top level:
- chacha20.go, chacha20_test.go – the public API and its tests
- chacha/ – internal subpackage containing multiple implementations
- .travis.yml, LICENSE, README.md – CI, licensing, and docs
- chacha/ subfolder: multiple .go and .s files organized by architecture (amd64, 386) and variant (AVX2, SSSE3, generic, reference).
- Tests are co-located with code (chacha/chacha_test.go).

##### Key insights from README
- Implements ChaCha20 with different nonces and round counts.
- Emphasizes runtime selection of the fastest available code path.
- No external services or databases—pure computation library.

##### Main components and their interactions
a. Public API Layer (chacha20.go)
- Exposes functions like `XORKeyStream`, `NewCipher20`, `XChaCha20`, etc.
- Selects the best implementation based on CPU feature detection.
b. Implementation Layer (chacha subpackage)
- Sub-components:
- Generic Go implementation (chacha_generic.go, chacha_ref.go)
- Architecture-specific optimized assembly (chacha_amd64.s + chacha_amd64.go, chachaAVX2_amd64.s, chacha_386.s + chacha_386.go)
- Constant tables and macros (const.s, macro.s)
- Selection logic in Go stubs calls into the chosen variant.
c. Test Harness
- Unit tests in both top level and subpackage verify correctness across all variants.
d. Build/CI
- Travis CI configured in .travis.yml to run `go test` across supported Go versions.

##### Architectural patterns and design principles
- Layered design: clear separation between Public API, generic implementation, and optimized backends.
- Strategy pattern: at init time, choose the best encryption “strategy” based on runtime CPU feature detection.
- Package scope: internal details hidden in the chacha subpackage; public interface kept minimal.

- Break the library into logical layers (API vs. implementations).
- Runtime selection logic (Strategy pattern).
- Architecture‐specific path as a separate component.
- Tests and build pipeline as supporting components.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global entities
    Client["Client / User Code"]:::public
    CI["CI: .travis.yml"]:::test
    Doc["Docs & License\n(README.md, LICENSE)"]:::test

    %% Public API Layer
    API["Public API Module\nchacha20.go"]:::public
    APITest["Public API Tests\nchacha20_test.go"]:::test

    %% Implementation Subpackage
    subgraph "Implementation Subpackage: chacha" 
        direction TB
        Generic["Generic Go Implementation\nchacha_generic.go"]:::internal
        RefImpl["Reference Go Implementation\nchacha_ref.go"]:::internal
        ConstTbl["Constant Tables\nconst.s"]:::internal
        Macros["Assembly Macros\nmacro.s"]:::internal
        subgraph "AMD64 Assembly"
            direction TB
            AMDStub["Go Stub\nchacha_amd64.go"]:::internal
            AMDAsm["Assembly\nchacha_amd64.s"]:::internal
        end
        subgraph "AVX2 Optimized"
            AVX2["Assembly\nchachaAVX2_amd64.s"]:::internal
        end
        subgraph "386 Assembly"
            direction TB
            Stub386["Go Stub\nchacha_386.go"]:::internal
            Asm386["Assembly\nchacha_386.s"]:::internal
        end
        SubTest["Subpackage Tests\nchacha_test.go"]:::test
    end

    %% Connections
    Client -->|"imports"| API
    API -->|"Init selects best routine"| Generic
    API --> Generic
    API --> RefImpl
    API --> AMDStub
    API --> AVX2
    API --> Stub386

    Generic --> ConstTbl
    RefImpl --> ConstTbl
    AMDStub --> AMDAsm
    Stub386 --> Asm386
    Generic --> Macros
    RefImpl --> Macros
    AMDAsm --> Macros
    Asm386 --> Macros
    AVX2 --> Macros

    %% Tests and CI relationships
    CI -->|"runs tests on"| APITest
    CI --> SubTest
    APITest --> API
    SubTest --> Generic
    SubTest --> RefImpl
    SubTest --> AMDAsm
    SubTest --> Asm386
    SubTest --> AVX2

    Doc --> API

    %% Click Events
    click API "https://github.com/aead/chacha20/blob/master/chacha20.go"
    click APITest "https://github.com/aead/chacha20/blob/master/chacha20_test.go"
    click CI "https://github.com/aead/chacha20/blob/master/.travis.yml"
    click Doc "https://github.com/aead/chacha20/blob/master/README.md"
    click Doc "https://github.com/aead/chacha20/tree/master/LICENSE"
    click Generic "https://github.com/aead/chacha20/blob/master/chacha/chacha_generic.go"
    click RefImpl "https://github.com/aead/chacha20/blob/master/chacha/chacha_ref.go"
    click AMDStub "https://github.com/aead/chacha20/blob/master/chacha/chacha_amd64.go"
    click AMDAsm "https://github.com/aead/chacha20/blob/master/chacha/chacha_amd64.s"
    click AVX2 "https://github.com/aead/chacha20/blob/master/chacha/chachaAVX2_amd64.s"
    click Stub386 "https://github.com/aead/chacha20/blob/master/chacha/chacha_386.go"
    click Asm386 "https://github.com/aead/chacha20/blob/master/chacha/chacha_386.s"
    click ConstTbl "https://github.com/aead/chacha20/blob/master/chacha/const.s"
    click Macros "https://github.com/aead/chacha20/blob/master/chacha/macro.s"
    click SubTest "https://github.com/aead/chacha20/blob/master/chacha/chacha_test.go"

    %% Styles
    classDef public fill:#DAE8FC,stroke:#6C8EBF,color:#000
    classDef internal fill:#E1F5A9,stroke:#82B366,color:#000
    classDef test fill:#FFE6CC,stroke:#D79B00,color:#000
```
