# chadski/nimbus architecture

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

- Interactive diagram: https://gitdiagram.com/chadski/nimbus
- Repository: https://github.com/chadski/nimbus

## Overview

##### Project Type and Purpose
- This is a domain-specific library for modding Halo games via runtime or disk-based mapfile editing.
- Key use cases include reading, parsing, and editing binary Halo map files, and exposing an API for modders.
- The README’s mem_example.py shows how the library is used to modify map elements (weapons, vehicles, projectiles).

##### And Segment the File Structure
- Three main submodules can be identified:
- basicstruct: Likely provides the fundamental data structures (fields, structs) that model the underlying binary data.
- byteaccess: Provides file and memory access functionality, handling the reading and processing of raw bytes.
- nimbus: The domain layer that builds upon the lower-level components to offer Halo-specific parsing and manipulation (e.g., halofield, halomap, halostruct, halotag). It also includes components for legacy “old_plugins” that support earlier parsing or conversion logic.
- Other files like mem_example.py, readme.md, and offsets.txt support usage examples and configuration.

##### Main Components
a. Core Data Structures (basicstruct)
- Components like Field and Struct classes that represent binary structures.
- Test files under basicstruct/test to show verification of these constructs.
b. Byte Access Mechanism (byteaccess)
- Classes handling file-based and memory-based I/O such as BaseByteAccess and File.
- Extra modules like process and windowsinterop indicating platform-specific operations.
- Their test suites under byteaccess/test validate these operations.
c. Halo-Specific Parsing and Editing (nimbus)
- Classes and modules such as HaloMap, HaloField, HaloStruct, HaloTag that encapsulate Halo-specific parsing.
- Plugins and legacy support found in subdirectories like clean_plugins and old_plugins.
- Utility modules (like headers.py and tags.py) assist in resolving and manipulating map internal metadata.
d. Supporting Files and Examples
- mem_example.py: Demonstrates runtime modifications.
- Configuration/documentation files like offsets.txt and readme.md provide context and integration guidelines.

##### Relationships, Interactions, and Architectural Patterns
- The high-level Nimbus layer (the domain API) uses both basicstruct and byteaccess as underlying services:
- Nimbus calls byteaccess classes to read raw binary data from disk or memory.
- Nimbus then maps these raw bytes to structured objects using functionality from basicstruct.
- Data flows from low-level byte access to structured domain objects and eventually to the higher-level API used by modders.
- Testing folders within each module indicate an emphasis on validation, ensuring each module’s components work both independently and together.
- Separation of concerns is evident, reflecting a modular architecture. This aligns with common design principles like the Single Responsibility Principle.

##### Detail and Clarity
- Do not oversimplify; include as many relevant components as possible, especially the layers and how they interconnect.
- Modular nature and the separation between low-level data handling, file/memory I/O, and high-level Halo-specific logic.
- Incorporate notes about platform dependencies (e.g., Windows-specific interop in byteaccess/windowsinterop.py) if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Basic Data Structures (basicstruct)
    subgraph "Basic Data Structures (basicstruct)"
        BS_Field["Field"]:::basic
        BS_Struct["Struct"]:::basic
        BS_Tests["Tests"]:::basic
    end

    %% Byte Access Mechanism (byteaccess)
    subgraph "Byte Access Mechanism (byteaccess)"
        BA_Base["BaseByteAccess"]:::byte
        BA_File["File"]:::byte
        BA_Process["Process"]:::byte
        BA_Windows["WindowsInterop"]:::byte
        BA_Tests["Tests"]:::byte
    end

    %% Halo-Specific Parsing and Editing (nimbus)
    subgraph "Halo-Specific Parsing and Editing (nimbus)"
        N_HaloField["HaloField"]:::nimbus
        N_HaloMap["HaloMap"]:::nimbus
        N_HaloStruct["HaloStruct"]:::nimbus
        N_HaloTag["HaloTag"]:::nimbus
        N_Headers["Headers"]:::nimbus
        N_Tags["Tags"]:::nimbus
        N_Clean["Clean Plugins"]:::nimbus
        N_Old["Old Plugins"]:::nimbus
        N_Tests["Tests"]:::nimbus
    end

    %% API/Usage Example
    subgraph "API/Usage"
        API["mem_example.py"]:::api
    end

    %% Documentation & Configuration
    subgraph "Documentation & Configuration"
        DOC1["readme.md"]:::doc
        DOC2["offsets.txt"]:::doc
    end

    %% Relationships between API and Nimbus components
    API -->|"uses"| N_HaloMap
    API -->|"uses"| N_HaloField
    API -->|"uses"| N_HaloStruct
    API -->|"uses"| N_HaloTag

    %% Nimbus layer dependencies on ByteAccess and Basicstruct components
    N_HaloField ---|"depends_on"| BA_Base
    N_HaloField ---|"maps_with"| BS_Field

    N_HaloMap ---|"reads_via"| BA_File
    N_HaloMap ---|"struct_by"| BS_Struct

    N_HaloStruct ---|"converts_with"| BA_Process
    N_HaloStruct ---|"utilizes"| BS_Struct

    N_HaloTag ---|"interop_with"| BA_Windows
    N_HaloTag ---|"references"| BS_Field

    %% Test dependencies (illustrative connection)
    N_Tests -.-> BA_Tests
    N_Tests -.-> BS_Tests

    %% Click Events for Core Data Structures
    click BS_Field "https://github.com/chadski/nimbus/blob/master/basicstruct/field.py"
    click BS_Struct "https://github.com/chadski/nimbus/blob/master/basicstruct/struct.py"
    click BS_Tests "https://github.com/chadski/nimbus/tree/master/basicstruct/test"

    %% Click Events for Byte Access Mechanism
    click BA_Base "https://github.com/chadski/nimbus/blob/master/byteaccess/basebyteaccess.py"
    click BA_File "https://github.com/chadski/nimbus/blob/master/byteaccess/file.py"
    click BA_Process "https://github.com/chadski/nimbus/blob/master/byteaccess/process.py"
    click BA_Windows "https://github.com/chadski/nimbus/blob/master/byteaccess/windowsinterop.py"
    click BA_Tests "https://github.com/chadski/nimbus/tree/master/byteaccess/test"

    %% Click Events for Halo-Specific Parsing and Editing
    click N_HaloField "https://github.com/chadski/nimbus/blob/master/nimbus/halofield.py"
    click N_HaloMap "https://github.com/chadski/nimbus/blob/master/nimbus/halomap.py"
    click N_HaloStruct "https://github.com/chadski/nimbus/blob/master/nimbus/halostruct.py"
    click N_HaloTag "https://github.com/chadski/nimbus/blob/master/nimbus/halotag.py"
    click N_Headers "https://github.com/chadski/nimbus/blob/master/nimbus/headers.py"
    click N_Tags "https://github.com/chadski/nimbus/blob/master/nimbus/tags.py"
    click N_Clean "https://github.com/chadski/nimbus/tree/master/nimbus/clean_plugins"
    click N_Old "https://github.com/chadski/nimbus/tree/master/nimbus/old_plugins"
    click N_Tests "https://github.com/chadski/nimbus/tree/master/nimbus/test"

    %% Click Events for API/Usage and Documentation
    click API "https://github.com/chadski/nimbus/blob/master/mem_example.py"
    click DOC1 "https://github.com/chadski/nimbus/blob/master/readme.md"
    click DOC2 "https://github.com/chadski/nimbus/blob/master/offsets.txt"

    %% Styles
    classDef basic fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef byte fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef nimbus fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef api fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef doc fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
```
