# andantetribe/localprefs architecture

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

- Interactive diagram: https://gitdiagram.com/andantetribe/localprefs
- Repository: https://github.com/andantetribe/localprefs

## Overview

##### Project Type and Purpose
- This is an open-source, modular library (SDK) targeting both .NET Standard (2.1+) and Unity.
- Its goal is to provide a unified, high-performance “local preferences” (save/load) API that overcomes Unity’s PlayerPrefs limitations.

##### High-Level Architecture & Main Components
a. Core Layer (src/LocalPrefs)
- ILocalPrefs interface – abstraction for save/load operations
- LocalPrefs.Shared – singleton entry point
- FileAccessor – pluggable file I/O
- CryptoFileAccessor – decorator adding encryption/decryption
b. Serializer Adapters
- JsonLocalPrefs (src/LocalPrefs.Json) – implements ILocalPrefs via System.Text.Json
- MessagePackLocalPrefs (src/LocalPrefs.MessagePack) – implements ILocalPrefs via MessagePack-CSharp
c. Internal Utilities (src/LocalPrefs.Internal)
- ByteBufferWriter, PooledList – buffers, pooling for MessagePack
d. Unity Integration (src/LocalPrefs.Unity)
- UnityInitializer – auto-configures LocalPrefs.Shared at startup
- WebGL plugins (.jslib) – native bindings for IndexedDB/LocalStorage
- IDBUtils, LSUtils, IDBStream, LSStream – Web platform backends
e. Test Projects
- LocalPrefs.Tests – .NET unit tests for core and adapters
- LocalPrefs.Unity/Assets/Tests – Unity edit-mode & play-mode tests
f. CI/CD & Packaging (/.github/workflows, /bin)
- dotnet-test, unity-test workflow badges
- NuGet build+publish workflows for Core, Json, MessagePack packages
- Unity meta-file checker, release automation

##### Component Relationships & Data Flows
- Core Layer defines the abstraction (ILocalPrefs) and orchestration (LocalPrefs.Shared).
→ JsonLocalPrefs and MessagePackLocalPrefs implement this interface.
→ Each serializer adapter uses a FileAccessor (or CryptoFileAccessor) to read/write bytes.
- CryptoFileAccessor wraps a FileAccessor and is passed into JsonLocalPrefs/MessagePackLocalPrefs.
- UnityInitializer (Unity package) consumes LocalPrefs.Shared; on Unity startup it sets the save path depending on platform (persistentDataPath or LocalStorage/IndexedDB).
- On WebGL, jslib plugins provide low-level I/O – exposed via IDBUtils/LSUtils – and are consumed by FileAccessor under the hood when running in web.

##### Architectural Patterns & Design Principles
- Layered Architecture: Core abstraction → concrete adapters → platform plug-ins
- Dependency Inversion: high-level modules (LocalPrefs.Shared) depend on ILocalPrefs, not implementations
- Decorator Pattern: CryptoFileAccessor wraps FileAccessor for optional encryption
- Strategy Pattern: choice between JSON vs. MessagePack via interchangeable implementations
- Plugin Architecture: WebGL native .jslib plugins injected at runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Layer
    subgraph "Core Layer"
        direction TB
        ILocalPrefs["ILocalPrefs<br/>(interface)"]:::core
        LocalPrefsShared["LocalPrefs.Shared<br/>(singleton)"]:::core
        FileAccessor["FileAccessor<br/>(I/O)"]:::core
        CryptoFileAccessor["CryptoFileAccessor<br/>(decorator)"]:::core
    end

    %% Serializer Adapters
    subgraph "Serializer Adapters"
        direction TB
        JsonLocalPrefs["JsonLocalPrefs<br/>(ILocalPrefs impl)"]:::adapter
        HeaderJsonConverter["HeaderJsonConverter"]:::adapter
        MessagePackLocalPrefs["MessagePackLocalPrefs<br/>(ILocalPrefs impl)"]:::adapter
        HeaderFormatterResolver["HeaderFormatterResolver"]:::adapter
        IntIntValueTupleFormatter["IntIntValueTupleFormatter"]:::adapter
    end

    %% Internal Utilities
    subgraph "Internal Utilities"
        direction TB
        ByteBufferWriter["ByteBufferWriter"]:::util
        PooledList["PooledList"]:::util
    end

    %% Unity Integration & Plugins
    subgraph "Unity Integration & Plugins"
        direction TB
        UnityInitializer["UnityInitializer"]:::unity
        IDBUtils["IDBUtils"]:::unity
        LSUtils["LSUtils"]:::unity
        IDBStream["IDBStream"]:::unity
        LSStream["LSStream"]:::unity
        native_idb["native_idb.jslib"]:::plugin
        native_ls["native_ls.jslib"]:::plugin
    end

    %% Test Suites
    subgraph "Test Suites"
        direction TB
        DotNetTests["LocalPrefs.Tests"]:::test
        UnityTests["Assets/Tests"]:::test
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        DotnetCI["dotnet-test.yml"]:::ci
        UnityCI["unity-test.yml"]:::ci
        PublishNuGet["publish-nuget.yml"]:::ci
        ReleaseWorkflow["release.yml"]:::ci
        CorePkg["bin/LocalPrefs.Core"]:::pkg
        JsonPkg["bin/LocalPrefs.Json"]:::pkg
        MPkg["bin/LocalPrefs.MessagePack"]:::pkg
    end

    %% Relationships
    JsonLocalPrefs -->|"implements"| ILocalPrefs
    MessagePackLocalPrefs -->|"implements"| ILocalPrefs
    LocalPrefsShared -->|"depends on"| ILocalPrefs
    JsonLocalPrefs -->|"uses"| FileAccessor
    MessagePackLocalPrefs -->|"uses"| FileAccessor
    CryptoFileAccessor -->|"decorates"| FileAccessor
    FileAccessor -->|"wrapped by"| CryptoFileAccessor
    UnityInitializer -->|"configures"| LocalPrefsShared
    native_idb -->|"provides"| IDBUtils
    native_ls -->|"provides"| LSUtils
    FileAccessor -->|"calls"| IDBUtils
    FileAccessor -->|"calls"| LSUtils
    IDBStream -->|"binds"| FileAccessor
    LSStream -->|"binds"| FileAccessor

    DotnetCI -->|"runs tests on"| DotNetTests
    UnityCI -->|"runs tests on"| UnityTests
    PublishNuGet -->|"publishes"| CorePkg
    PublishNuGet -->|"publishes"| JsonPkg
    PublishNuGet -->|"publishes"| MPkg
    ReleaseWorkflow -->|"automates release for"| CorePkg
    ReleaseWorkflow -->|"automates release for"| JsonPkg
    ReleaseWorkflow -->|"automates release for"| MPkg

    %% Click Events
    click ILocalPrefs "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs/ILocalPrefs.cs"
    click LocalPrefsShared "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs/LocalPrefs.cs"
    click FileAccessor "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs/FileAccessor.cs"
    click CryptoFileAccessor "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs/CryptoFileAccessor.cs"
    click JsonLocalPrefs "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Json/JsonLocalPrefs.cs"
    click HeaderJsonConverter "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Json/HeaderJsonConverter.cs"
    click MessagePackLocalPrefs "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.MessagePack/MessagePackLocalPrefs.cs"
    click HeaderFormatterResolver "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.MessagePack/HeaderFormatterResolver.cs"
    click IntIntValueTupleFormatter "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.MessagePack/IntIntValueTupleFormatter.cs"
    click ByteBufferWriter "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Internal/ByteBufferWriter.cs"
    click PooledList "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Internal/PooledList.cs"
    click UnityInitializer "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Runtime/UnityInitializer.cs"
    click IDBUtils "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Runtime/IDBUtils.cs"
    click LSUtils "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Runtime/LSUtils.cs"
    click IDBStream "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Runtime/IDBStream.cs"
    click LSStream "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Runtime/LSStream.cs"
    click native_idb "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Plugins/WebGL/native_idb.jslib"
    click native_ls "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Unity/Packages/jp.andantetribe.localprefs/Plugins/WebGL/native_ls.jslib"
    click DotNetTests "https://github.com/andantetribe/localprefs/blob/main/src/LocalPrefs.Tests"
    click UnityTests "https://github.com/andantetribe/localprefs/tree/main/src/LocalPrefs.Unity/Assets/Tests"
    click DotnetCI "https://github.com/andantetribe/localprefs/blob/main/.github/workflows/dotnet-test.yml"
    click UnityCI "https://github.com/andantetribe/localprefs/blob/main/.github/workflows/unity-test.yml"
    click PublishNuGet "https://github.com/andantetribe/localprefs/blob/main/.github/workflows/publish-nuget.yml"
    click ReleaseWorkflow "https://github.com/andantetribe/localprefs/blob/main/.github/workflows/release.yml"
    click CorePkg "https://github.com/andantetribe/localprefs/blob/main/bin/LocalPrefs.Core"
    click JsonPkg "https://github.com/andantetribe/localprefs/blob/main/bin/LocalPrefs.Json"
    click MPkg "https://github.com/andantetribe/localprefs/blob/main/bin/LocalPrefs.MessagePack"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#006064,color:#000
    classDef adapter fill:#E8F5E9,stroke:#1B5E20,color:#000
    classDef util fill:#F5F5F5,stroke:#616161,color:#000
    classDef unity fill:#FFF9C4,stroke:#F57F17,color:#000
    classDef plugin fill:#FFF3E0,stroke:#E65100,color:#000
    classDef test fill:#FFE0B2,stroke:#E65100,color:#000
    classDef ci fill:#E1BEE7,stroke:#6A1B9A,color:#000
    classDef pkg fill:#D1C4E9,stroke:#4A148C,color:#000
```
