# alecthomas/chroma architecture

> Architecture diagram of the GitHub repository alecthomas/chroma, 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/alecthomas/chroma
- Repository: https://github.com/alecthomas/chroma

## Overview

##### Main Components

a) Core Components:
- Lexer System
- Formatter System
- Style System
- Registry Management
- Token Processing Pipeline

b) Supporting Components:
- CLI Interface
- Quick Highlighting API
- Testing Infrastructure

**┌─ Application Layer ─────────────────────┐**
- CLI (cmd/chroma)   Web UI (cmd/chromad) │
- ┬────────────────────┘
**┌─ Public API Layer ─────────────────────┐**
- Quick Highlight API    Registry API     │
- ┬────────────────────┘
**┌─ Core Processing Layer ─────────────────┐**
- ┌─────────┐  ┌──────────┐ ┌─────────┐  │
- Lexers  │→ │ Iterator │→│Formatter│  │
- ┘  └──────────┘ └─────────┘  │
- ↑          ↑           ↑         │
- ┌─────────────────────────┐        │
- Styles           │        │
- ┘        │
- ┘
**┌─ Storage Layer ──────────────────────────┐**
- Embedded Lexer Definitions (XML)         │
- Style Definitions (XML)                  │
- ┘

##### Key Relationships

a) Data Flow:
- Source text → Lexer → Token Iterator → Formatter → Output
- Style definitions affecting both Lexers and Formatters
- Registry managing component lookup and registration

b) Component Interactions:
- Lexer selection process (filename/content analysis)
- Style application to tokens
- Formatter output generation

##### Special Elements

a) Input/Output:
- Source code input
- Multiple output formats (HTML, ANSI, etc.)
- Style definitions (XML)
- Lexer definitions (XML)

b) Extension Points:
- Custom lexer registration
- Custom formatter implementation
- Custom style definition

##### Implementation Details

- Rectangles: Core components
- Rounded rectangles: APIs
- Blue: Core processing
- Green: Input/Output
- Yellow: Extension points
- Gray: Supporting infrastructure

##### Additional Notes

- Component relationships
- Data flow directions
- Extension points
- Configuration options

##### The pipeline-based processing model

This design reflects Chroma's architecture as a library that processes source code through distinct stages (lexing, token processing, formatting) while maintaining flexibility through its registry system and style definitions.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Application
        CLI["CLI Interface"]:::cli
        WebUI["Web UI"]:::cli
    end

    subgraph "Public API"
        QuickAPI["Quick Highlight API"]:::api
        RegistryAPI["Registry API"]:::api
    end

    subgraph "Core Processing"
        LexerSystem["Lexer System"]:::core
        Iterator["Token Iterator"]:::core
        Formatter["Formatter System"]:::core
        StyleSystem["Style System"]:::core
    end

    subgraph Storage
        LexerDefs["Lexer Definitions (XML)"]:::storage
        StyleDefs["Style Definitions (XML)"]:::storage
    end

    %% Relationships
    CLI --> QuickAPI
    WebUI --> QuickAPI
    QuickAPI --> LexerSystem
    RegistryAPI --> LexerSystem
    RegistryAPI --> Formatter
    RegistryAPI --> StyleSystem
    
    LexerSystem --> Iterator
    Iterator --> Formatter
    StyleSystem --> LexerSystem
    StyleSystem --> Formatter
    
    LexerDefs --> LexerSystem
    StyleDefs --> StyleSystem

    %% Click Events
    click LexerSystem "https://github.com/alecthomas/chroma/tree/master/lexers/"
    click Formatter "https://github.com/alecthomas/chroma/tree/master/formatters/"
    click StyleSystem "https://github.com/alecthomas/chroma/tree/master/styles/"
    click CLI "https://github.com/alecthomas/chroma/tree/master/cmd/chroma/"
    click WebUI "https://github.com/alecthomas/chroma/tree/master/cmd/chromad/"
    click QuickAPI "https://github.com/alecthomas/chroma/blob/master/quick/quick.go"
    click Iterator "https://github.com/alecthomas/chroma/blob/master/iterator.go"
    click RegistryAPI "https://github.com/alecthomas/chroma/blob/master/registry.go"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:2px
    classDef api fill:#9ef,stroke:#333,stroke-width:2px
    classDef core fill:#9f9,stroke:#333,stroke-width:2px
    classDef storage fill:#ff9,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        CLI_L["Application Components"]:::cli
        API_L["API Layer"]:::api
        Core_L["Core Components"]:::core
        Storage_L["Storage Layer"]:::storage
    end
```
