# skadistats/clarity architecture

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

- Interactive diagram: https://gitdiagram.com/skadistats/clarity
- Repository: https://github.com/skadistats/clarity

## Overview

##### Project type and purpose
- Clarity is an open‑source Java library (not a web service or UI app) whose sole purpose is to parse and decode game replay files (Dota 2, CS:GO, CS2, Deadlock).
- The README confirms it produces structured data (combat logs, entities, modifiers, etc.) from raw replay files.

##### File structure
- **src/main/java/skadistats/clarity** is the root package. Everything under it is part of the library.
- Major top‑level subpackages (i.e., components) are:
- clarity (the API entry point, exceptions, event annotations)
- clarity.source (input sources: files, mapped memory, live stream)
- clarity.io (bitstream/decoder factories, version‑specific readers for S1/S2)
- clarity.model (in‑memory model of entities, game events, combat log entries, etc.)
- clarity.processor (annotation‑driven event dispatch pipeline: reader → packet → entities → gameevents → modifiers → sendtables → stringtables → tempentities)
- clarity.processor.runner (runnable controllers: FileRunner, RealtimeRunner, loop, context)
- clarity.platform (buffer abstractions, reflection helper)
- clarity.logger (logging interface and implementation)
- clarity.util (misc utilities: hashing, LZSS, difference evaluator, iterators, text table)
- There are no “frontend” vs. “backend” directories; this is a library with a layered, pipeline‑style architecture.

##### README for additional insights
- Confirms core functionality (parsing replays into domain data).

1. Input Sources
- FileSource/MappedFileSource
- InputStreamSource
- LiveSource
2. IO/Decoding Layer
- BitStream (32/64)
- FieldReader
- DecoderFactory(s) for S1/S2 versions
3. Processor Pipeline
- Reader stage (PacketInstanceReader)
- Packet stage (OnFullPacket, OnMessage)
- Entity stage (OnEntityCreated, OnEntityUpdated)
- GameEvent stage (OnGameEvent, OnCombatLogEntry)
- Modifier stage, SendTable stage, StringTable stage, TempEntity stage
4. Model Store
- EntityRegistry, BaselineRegistry, GameEventDescriptor, CombatLogEntry
5. Runner/Controller
- AbstractRunner, FileRunner, RealtimeRunner, LoopController
6. Event API
- Clarity (main entry), annotation interfaces: @Initializer, @InsertEvent, @EventListener
7. Logging & Platform Abstraction
- PrintfLogger, Buffer abstractions (UnsafeBuffer/CompatibleBuffer)
8. Utilities
- LZSS, MurmurHash, StateDifferenceEvaluator, TextTable, etc.
- Clarity → RunnerController (chooses FileRunner or RealtimeRunner)
- RunnerController → Source (pulls raw bytes)
- Source → IO/Decoding (BitStream → FieldReader → DecoderFactory)
- Decoding → ProcessorPipeline (PacketInstance → OnMessage events)
- Processor stages feed into Model Store and emit @EventListener callbacks
- Event API → User application (clients register listeners via Clarity)
- Throughout, Logger writes to console or file via PrintfLogger
c. Architectural patterns & design principles:
- Layered pipeline: each processor stage registers for specific annotation‑driven events.
- Inversion of Control: clients provide annotated listeners, Clarity dispatches.
- Version modularity: S1 vs. S2 decoder factories.
- Separation of concerns: IO, decoding, model-storage, processing, and control are distinct.
- Extensibility: annotation points for new event types or custom processors.
d. Key technologies & frameworks:
- Java 17+
- Gradle (build)
- No external frameworks: pure‑Java, uses reflection for annotation processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Sources"
        direction TB
        IS1["FileSource / MappedFileSource"]:::input
        IS2["InputStreamSource"]:::input
        IS3["LiveSource"]:::input
    end

    subgraph "IO/Decoding Layer"
        direction TB
        BS["BitStream"]:::io
        FR["FieldReader"]:::io
        DF["DecoderFactory (S1/S2)"]:::io
    end

    subgraph "Processor Pipeline"
        direction TB
        SR["Reader Stage"]:::processor
        SP["Packet Stage"]:::processor
        SE["Entity Stage"]:::processor
        SG["GameEvent Stage"]:::processor
        SM["Modifier Stage"]:::processor
        SST["SendTable Stage"]:::processor
        SSTR["StringTable Stage"]:::processor
        ST["TempEntity Stage"]:::processor
    end

    subgraph "Model Store"
        direction TB
        MS["EntityRegistry / BaselineRegistry / GameEventDescriptor / CombatLogEntry"]:::model
    end

    subgraph "Runner / Controller"
        direction TB
        RC["FileRunner / RealtimeRunner / LoopController"]:::runner
    end

    subgraph "Event API / Annotations"
        direction TB
        API["Clarity & @Initializer / @InsertEvent / @EventListener"]:::api
    end

    subgraph "Logging & Platform"
        direction TB
        LP["PrintfLogger / Buffer Abstractions"]:::infra
    end

    subgraph "Utilities"
        direction TB
        UT["MurmurHash / LZSS / StateDifferenceEvaluator / TextTable"]:::infra
    end

    API --> RC
    RC --> IS1
    RC --> IS2
    RC --> IS3

    IS1 --> BS
    IS2 --> BS
    IS3 --> BS

    BS --> FR
    FR --> DF

    DF --> SR
    SR --> SP
    SP --> SE
    SE --> SG
    SG --> SM
    SM --> SST
    SST --> SSTR
    SSTR --> ST

    ST --> MS
    ST --> API

    LP --> RC
    LP --> DF
    LP --> SR

    UT --> DF
    UT --> SR

    classDef input fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef io fill:#bbdefb,stroke:#1565c0,stroke-width:2px
    classDef processor fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
    classDef model fill:#fff9c4,stroke:#f9a825,stroke-width:2px
    classDef runner fill:#eceff1,stroke:#607d8b,stroke-width:2px
    classDef api fill:#e1bee7,stroke:#8e24aa,stroke-width:2px
    classDef infra fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px

    click IS1 "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/source"
    click IS2 "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/source"
    click IS3 "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/source"
    click BS "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/io/bitstream"
    click FR "https://github.com/skadistats/clarity/blob/master/src/main/java/skadistats/clarity/io/FieldReader.java"
    click DF "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/io/decoder"
    click SR "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/reader"
    click SP "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/packet"
    click SE "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/entities"
    click SG "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/gameevents"
    click SM "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/modifiers"
    click SST "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/sendtables"
    click SSTR "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/stringtables"
    click ST "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/tempentities"
    click MS "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/model"
    click RC "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/processor/runner"
    click API "https://github.com/skadistats/clarity/blob/master/src/main/java/skadistats/clarity/Clarity.java"
    click LP "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/logger"
    click UT "https://github.com/skadistats/clarity/tree/master/src/main/java/skadistats/clarity/util"
```
