# legitatx/fortnite-replay-parser architecture

> Architecture diagram of the GitHub repository legitatx/fortnite-replay-parser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/legitatx/fortnite-replay-parser
- Repository: https://github.com/legitatx/fortnite-replay-parser

## Overview

##### Project Type and Purpose
- This is a Python library (“fortnite-replay-parser”) whose sole purpose is parsing Fortnite replay files (binary `.replay` files) into Python objects (header, metadata, events) for downstream processing or analysis. It is not a full-stack app but a domain-specific parser library.

##### Main Architectural Components
a. Input Layer
- **Replay File**: Binary `.replay` file on disk
- **FortniteReplayReader (reader.py)**: Entry point; opens file, manages context, orchestrates parsing
b. Parsing Core
- **Low-Level Reader/Deserializer (models/reader.py)**: Reads binary chunks, respects protocol versions
- **Event Parser (events/parser.py)**: Dispatches raw event payloads to specific event handlers
- **Event Handlers (events/match.py, events/player.py, …)**: Each module extracts fields from the binary stream
c. Data Model Layer
- **Pydantic Models (models/events.py, models/fortnite.py)**: Strongly typed classes for header, metadata, events
- **Reader Model (models/reader.py)**: Represents binary structures, endianness, offsets
d. Infrastructure & Utilities
- **Exceptions (exceptions.py)**: Centralized custom exceptions for parse errors
- **Logger (logger.py)**: Configurable logger for debugging/tracing parsing steps
- **Utils (utils.py)**: Common functions (e.g., byte conversions, version checks)
e. Output/Consumer Layer
- The consumer calls `reader.events` to get a list of Pydantic event objects; they are then serialized or processed further
f. Test Harness
- **Tests Directory**: Contains sample `.replay` files and test suites verifying correct event extraction

##### Dependencies & External Services
- Pydantic for data validation & serialization
- Python standard library (struct, io, contextlib, logging)
- No external network or database—purely local file parsing

##### Architectural Patterns & Principles
- **Layered Architecture**: Clear separation between Input, Parsing, Modeling, and Output
- **Strategy/Dispatcher Pattern**: `events/parser.py` dynamically picks the right handler based on event type
- **Model-Driven Design**: Binary structures are mirrored in Pydantic models for type safety and clarity
- **Single Responsibility**: Each module does one thing—reading raw bytes, parsing a specific event, modeling data, or logging

- Parsing Core (Low-Level Reader, Event Parser, Event Handlers)
- Data Model Layer (Pydantic Models)
- Infrastructure (Exceptions, Logger, Utils)
- Output/Consumer (your application script or JSON serializer)
- Test Harness (with sample files)
- From Replay File → FortniteReplayReader → Low-Level Reader → Event Parser → Event Handlers → Pydantic Models → Consumer
- Test Harness reads from sample files and invokes reader in a similar flow
- Another for “Data Models” (Pydantic classes)
- A third for “Infrastructure” (utils, exceptions, logger)
- A separate style for “External Entities” (Replay File, Consumer, Tests)
d. Labels & Callouts:
- Call out protocol version handling in the Low-Level Reader
- That the Parser uses a dynamic lookup (Strategy pattern) to pick handlers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    ReplayFile["Replay File (.replay)"]:::external
    Consumer["Consumer"]:::external

    %% Input Layer
    subgraph "Input Layer"
        direction TB
        FortniteReplayReader["FortniteReplayReader"]:::core
    end

    %% Parsing Core
    subgraph "Parsing Core"
        direction TB
        LowLevelReader["Low-Level Reader/Deserializer"]:::core
        EventParser["Event Parser"]:::core
        subgraph "Event Handlers"
            direction TB
            MatchHandler["Match Events Handler"]:::core
            PlayerHandler["Player Events Handler"]:::core
        end
    end

    %% Data Model Layer
    subgraph "Data Model Layer"
        direction TB
        EventModels["Event Models"]:::data
        FortniteModels["Fortnite Replay Models"]:::data
    end

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        Exceptions["Exceptions"]:::infra
        Logger["Logger"]:::infra
        Utils["Utils"]:::infra
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        Tests["Test Suite & Fixtures"]:::external
        SampleReplays["Sample .replay Files"]:::external
    end

    %% Primary Data Flow
    ReplayFile -->|"binary data"| FortniteReplayReader
    FortniteReplayReader -->|"byte stream"| LowLevelReader
    LowLevelReader -->|"raw event payload"| EventParser
    EventParser -->|"dispatch by type (Strategy)"| MatchHandler
    EventParser --> MatchHandler
    EventParser --> PlayerHandler
    MatchHandler -->|"EventModel instance"| EventModels
    PlayerHandler --> EventModels
    EventModels --> FortniteModels
    FortniteModels --> Consumer

    %% Utilities & Error Pathways (dashed)
    Exceptions -.-> FortniteReplayReader
    Exceptions -.-> LowLevelReader
    Exceptions -.-> EventParser
    Exceptions -.-> MatchHandler
    Exceptions -.-> PlayerHandler

    Logger -.-> FortniteReplayReader
    Logger -.-> LowLevelReader
    Logger -.-> EventParser
    Logger -.-> MatchHandler
    Logger -.-> PlayerHandler

    Utils -.-> LowLevelReader
    Utils -.-> EventParser

    %% Test Flow
    SampleReplays --> Tests
    SampleReplays --> FortniteReplayReader
    Tests --> FortniteReplayReader

    %% Notes
    note_low["Handles protocol versions\nand endianness"]:::note
    LowLevelReader --- note_low

    %% Click Events
    click FortniteReplayReader "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/reader.py"
    click LowLevelReader "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/models/reader.py"
    click EventParser "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/events/parser.py"
    click MatchHandler "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/events/match.py"
    click PlayerHandler "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/events/player.py"
    click EventModels "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/models/events.py"
    click FortniteModels "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/models/fortnite.py"
    click Exceptions "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/exceptions.py"
    click Logger "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/logger.py"
    click Utils "https://github.com/legitatx/fortnite-replay-parser/blob/master/fortnite_replay_parser/utils.py"
    click Tests "https://github.com/legitatx/fortnite-replay-parser/tree/master/tests/"
    click SampleReplays "https://github.com/legitatx/fortnite-replay-parser/tree/master/tests/Replays/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#3B82F6,stroke-width:2px
    classDef data fill:#E6FFFA,stroke:#10B981,stroke-width:2px
    classDef infra fill:#FFF7DB,stroke:#F59E0B,stroke-width:2px
    classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:2px
    classDef note fill:#FFFFFF,stroke:#9CA3AF,stroke-dasharray: 2 2,stroke-width:1px,font-style:italic
```
