# kalexmills/krt-lite architecture

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

- Interactive diagram: https://gitdiagram.com/kalexmills/krt-lite
- Repository: https://github.com/kalexmills/krt-lite

## Overview

##### Project type and purpose
- This is a Go library (not a full-stack app) for building Kubernetes controllers using a dependency-graph–based event propagation model.
- It provides primitives for handling Kubernetes (and other) events, modeling intermediate state, and wiring up “syncer” nodes that react to state changes.

##### File structure
- Top-level Go files (core.go, informer.go, fetch.go, syncer.go, index.go) define the core engine and interfaces.
- Sub-packages/folders implement supporting data structures and patterns:
– bimap/ (state mapping)
– fifo/ (queue and ring buffer for event delivery)
– derived_collection.go, merged_collection.go, joined_collection.go, static_collection.go, scale.go (transformations on streams of events)
– singleton.go (singleton‐value collections)
- Tests and conformance_test.go ensure each piece conforms to the dependency‐graph contract.

##### Extract insights from README
- It’s a drop-in replacement for istio/krt core, minus Istio dependencies.
- Key concepts: dependency graph, intermediate state as events, multiple event sources.

##### Main components
a. Event Sources
– Kubernetes API informer (informer.go)
– Other external sources plugged via Fetcher interface (fetch.go)
b. Core Engine
– Graph builder / core (core.go)
– Syncer nodes (syncer.go)
c. State Management
– Index/cache (index.go)
– bimap (bimap/bimap.go)
– fifo queues (fifo/queue.go, fifo/ringbuf.go)
d. Collection Transformations
– StaticCollection, DerivedCollection, MergedCollection, JoinedCollection, Scale
e. Controller Output
– Syncer handlers push changes back to Kubernetes or external sinks

##### Relationships and data flows
- Syncers may in turn emit new events back into the graph (loop)
- Queues/bimaps sit alongside nodes as internal implementation details

##### Architectural patterns
- Reactive dependency graph (observer pattern)
- Functional‐style collection transformations (map, flatMap, merge, join, scale)
- Backpressure via FIFO/Ringbuffer
- Decoupling via interfaces (Fetcher, Syncer)

##### Technology and framework callouts
- Language: Go (Go modules, go test)
- CI: golang-ci, coverage badges, Makefile targets

- Components: use rounded rectangles for major subsystems (Engine, Index, Collections, Syncers)
– Blue for core engine packages
– Green for state/data structures (bimap, fifo)
– Orange for collection transformations
– Purple for external/event sources and sinks

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Event Sources"
        direction TB
        informer["K8s Informer"]:::sources
        fetcher["External Fetchers"]:::sources
    end

    core["Core Engine\n(core.go)"]:::core
    indexer["Indexer\n(index.go)"]:::state

    subgraph "Collections (Transformations)"
        direction TB
        static["StaticCollection\n(static_collection.go)"]:::coll
        derived["DerivedCollection\n(derived_collection.go)"]:::coll
        merged["MergedCollection\n(merged_collection.go)"]:::coll
        joined["JoinedCollection\n(joined_collection.go)"]:::coll
        scale["Scale\n(scale_test.go)"]:::coll
        singleton["SingletonCollection\n(singleton.go)"]:::coll
    end

    syncer["Syncer Nodes\n(syncer.go)"]:::core

    subgraph "Support Services"
        direction LR
        bimap["BiMap\n(bimap/bimap.go)"]:::state
        fifoQueue["FIFO Queue\n(fifo/queue.go)"]:::state
        ringbuf["RingBuffer\n(fifo/ringbuf.go)"]:::state
    end

    informer -->|"K8s Event"| core
    fetcher -->|"External Event"| core
    core -->|"Build Graph"| indexer
    indexer -->|"Resource Objects"| static
    static -->|"Derived Events"| derived
    derived -->|"Merged Streams"| merged
    merged -->|"Joined Data"| joined
    joined -->|"Scaled Output"| scale
    indexer -->|"Singleton Value"| singleton
    scale -->|"Final Events"| syncer
    singleton -->|"Final Events"| syncer
    syncer -.->|"Callbacks/ Patches"| core

    bimap -.-> static
    bimap -.-> derived
    fifoQueue -.-> core
    ringbuf -.-> core

    %% Click Events
    click informer "https://github.com/kalexmills/krt-lite/blob/main/informer.go"
    click fetcher "https://github.com/kalexmills/krt-lite/blob/main/fetch.go"
    click core "https://github.com/kalexmills/krt-lite/blob/main/core.go"
    click indexer "https://github.com/kalexmills/krt-lite/blob/main/index.go"
    click static "https://github.com/kalexmills/krt-lite/blob/main/static_collection.go"
    click derived "https://github.com/kalexmills/krt-lite/blob/main/derived_collection.go"
    click merged "https://github.com/kalexmills/krt-lite/blob/main/merged_collection.go"
    click joined "https://github.com/kalexmills/krt-lite/blob/main/joined_collection.go"
    click scale "https://github.com/kalexmills/krt-lite/blob/main/scale_test.go"
    click singleton "https://github.com/kalexmills/krt-lite/blob/main/singleton.go"
    click syncer "https://github.com/kalexmills/krt-lite/blob/main/syncer.go"
    click bimap "https://github.com/kalexmills/krt-lite/blob/main/bimap/bimap.go"
    click fifoQueue "https://github.com/kalexmills/krt-lite/blob/main/fifo/queue.go"
    click ringbuf "https://github.com/kalexmills/krt-lite/blob/main/fifo/ringbuf.go"

    classDef sources fill:#D8BFD8,stroke:#800080,color:#000
    classDef core fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef state fill:#98FB98,stroke:#008000,color:#000
    classDef coll fill:#FFA500,stroke:#FF8C00,color:#000
```
