# thisisdevelopment/mightymap architecture

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

- Interactive diagram: https://gitdiagram.com/thisisdevelopment/mightymap
- Repository: https://github.com/thisisdevelopment/mightymap

## Overview

##### Project Type and Purpose
- MightyMap is an open-source Go library (plus accompanying CLI tools) providing a thread-safe, generic map abstraction with swappable storage backends (in-memory, Swiss, BadgerDB, Redis) and migration utilities for on-disk backends. Its primary purpose is to offer a flexible, high-performance key/value store API for Go programs and standalone migration commands.

##### File Structure Analysis
- Top-level:
- mightymap.go – core generic Map[K,V] implementation and API
- storage/ – interface and implementations for each storage backend plus MessagePack adapter
- cmd/ – two CLI binaries (migrate-badger, migrate-redis) with sample YAML configs
- tests & benchmarks scattered alongside production code
- Key patterns:
- Strategy pattern: core Map depends on storage.IMightyMapStorage interface
- Adapter pattern: msgpackAdapter implements encoding for persistent backends
- CLI tools as separate binaries under cmd/
- Deployment/config:
- YAML example files in cmd/ for migration tool configuration
- .circleci/, .github/ workflows for CI

##### README Insights
- Explicit section on “Configurable Storage Backends” and “Migration Tools”
- Detailed description of default, Swiss, Badger, and Redis storages, with options
- CLI usage examples

1. Core Library (Map[K,V] API)
2. Storage Interface (IMightyMapStorage)
3. Storage Implementations:
– Default (mutex-protected Go map)
– SwissStorage (Swiss-table in-memory)
– BadgerStorage (encodes via MessagePack → BadgerDB embedded engine)
– RedisStorage (encodes via MessagePack → external Redis server)
4. MessagePack Adapter (shared by Badger & Redis backends)
5. External Services:
– BadgerDB (on-disk key/value store)
– Redis instance (network service)
6. CLI Migration Tools:
– migrate-badger binary (reads old Badger config, reads old data format, writes new MessagePack format)
– migrate-redis binary (similar for Redis)
7. Configuration (YAML files)
8. CI/CD (CircleCI / GitHub Actions)

- [K,V] → calls → Storage Interface methods (Load, Store, Delete, etc.)
- Storage Interface → implemented by → each storage backend
- BadgerStorage/RedisStorage → use → MessagePack Adapter → serialize/deserialize → underlying DB or Redis
- BadgerStorage → directly embeds → BadgerDB (local file system)
- RedisStorage → connects over network → Redis server
- CLI Tools → utilize → core library + storage implementations → driven by config → perform migration
- Configuration files → loaded by → CLI Tools
- CI/CD workflows → run → Tests & Benchmarks → on pushes/PRs

c. Architectural Patterns & Principles
- Strategy Pattern: pluggable storage backends behind a unified interface
- Adapter Pattern: msgpackAdapter decouples serialization format from storage logic
- Single Responsibility: core Map logic is separate from backend implementations
- Dependency Injection: storage implementations are injected into Map constructor
- Context Propagation: all methods accept context.Context for cancellation and tracing

d. Relevant Technologies/Frameworks
- Go 1.18+ Generics for Map[K,V]
- BadgerDB (embedded, ACID key/value store)
- Redis client library (for persistent in-network storage)
- MessagePack (binary serialization)
- Swiss hash-map (dolthub/swiss)
- Cobra/flag (for CLI binaries)
- YAML (configuration files)
- CircleCI & GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        Map["Map[K,V] (core API)"]:::core
    end
    click Map "https://github.com/thisisdevelopment/mightymap/blob/master/mightymap.go"

    %% Storage Layer
    subgraph "Storage Layer"
        Interface["IMightyMapStorage"]:::interface
        Default["DefaultStorage (mutex map)"]:::inmem
        Swiss["SwissStorage"]:::inmem
        BadgerStorage["BadgerStorage"]:::pers
        RedisStorage["RedisStorage"]:::pers
    end
    click Interface "https://github.com/thisisdevelopment/mightymap/blob/master/storage/mightymapStore.go"
    click Default "https://github.com/thisisdevelopment/mightymap/blob/master/storage/mightymapStore.go"
    click Swiss "https://github.com/thisisdevelopment/mightymap/blob/master/storage/mightymapStoreSwiss.go"
    click BadgerStorage "https://github.com/thisisdevelopment/mightymap/blob/master/storage/mightymapStoreBadger.go"
    click RedisStorage "https://github.com/thisisdevelopment/mightymap/blob/master/storage/mightymapRedisStore.go"

    %% Adapter
    Adapter["MessagePack Adapter"]:::adapter
    click Adapter "https://github.com/thisisdevelopment/mightymap/blob/master/storage/msgpackAdapter.go"

    %% External Services
    subgraph "External Services"
        BadgerDB["BadgerDB (local)"]:::db
        RedisServer["Redis Server"]:::db
    end

    %% CLI Migration Tools
    subgraph "Migration CLI"
        subgraph "migrate-badger"
            MBMain["main.go"]:::cli
            MBMod["go.mod"]:::cli
            MBConf["yaml.example"]:::config
        end
        subgraph "migrate-redis"
            MRMain["main.go"]:::cli
            MRMod["go.mod"]:::cli
            MRConf["yaml.example"]:::config
        end
    end
    click MBMain "https://github.com/thisisdevelopment/mightymap/blob/master/cmd/migrate-badger/main.go"
    click MBMod "https://github.com/thisisdevelopment/mightymap/blob/master/cmd/migrate-badger/go.mod"
    click MBConf "https://github.com/thisisdevelopment/mightymap/blob/master/cmd/migrate-badger.yaml.example"
    click MRMain "https://github.com/thisisdevelopment/mightymap/blob/master/cmd/migrate-redis/main.go"
    click MRMod "https://github.com/thisisdevelopment/mightymap/blob/master/cmd/migrate-redis/go.mod"
    click MRConf "https://github.com/thisisdevelopment/mightymap/blob/master/cmd/migrate-redis.yaml.example"

    %% Config Files
    subgraph "Configuration"
        GlobalConfig["YAML Config Files"]:::config
    end

    %% CI/CD
    subgraph "CI/CD"
        CircleCI["CircleCI Workflow"]:::ci
        GitHubActions["GitHub Actions"]:::ci
    end
    click CircleCI "https://github.com/thisisdevelopment/mightymap/blob/master/.circleci/config.yml"
    click GitHubActions "https://github.com/thisisdevelopment/mightymap/blob/master/.github/workflows/main.yml"

    %% Tests & Benchmarks
    subgraph "Tests & Benchmarks"
        Tests["Unit Tests & Benchmarks"]:::test
    end

    %% Relationships
    Map -->|"uses"| Interface
    Interface -->|"implemented by"| Default
    Interface -->|"implemented by"| Swiss
    Interface -->|"implemented by"| BadgerStorage
    Interface -->|"implemented by"| RedisStorage

    BadgerStorage -->|"serializes via"| Adapter
    RedisStorage -->|"serializes via"| Adapter

    Adapter -->|"writes to"| BadgerDB
    Adapter -->|"writes to"| RedisServer

    MBMain -->|"calls"| Map
    MBMain -->|"uses"| BadgerStorage
    MBMain -->|"reads"| MBConf

    MRMain -->|"calls"| Map
    MRMain -->|"uses"| RedisStorage
    MRMain -->|"reads"| MRConf

    GlobalConfig -->|"loaded by"| MBMain
    GlobalConfig -->|"loaded by"| MRMain

    CircleCI -->|"runs"| Tests
    GitHubActions -->|"runs"| Tests

    %% Context Flow
    Map -.->|"ctx.Context"| Default
    Map -.->|"ctx.Context"| Swiss
    Map -.->|"ctx.Context"| BadgerStorage
    Map -.->|"ctx.Context"| RedisStorage

    %% Legend (implicit via classes)

    %% Styles
    classDef core fill:#D6E4FF,stroke:#3B5BDB,color:#1E3A8A
    classDef interface fill:#E0E7FF,stroke:#3730A3,color:#1E3A8A
    classDef inmem fill:#D1FAE5,stroke:#10B981,color:#065F46
    classDef pers fill:#FFEDD5,stroke:#F97316,color:#7C2D12
    classDef adapter fill:#F5E0FC,stroke:#9333EA,color:#582C83
    classDef db fill:#FEE2E2,stroke:#DC2626,color:#991B1B
    classDef cli fill:#E5E7EB,stroke:#6B7280,color:#111827
    classDef config fill:#FEF9C3,stroke:#D97706,color:#92400E
    classDef ci fill:#E0F2FE,stroke:#0284C7,color:#075985
    classDef test fill:#F3F4F6,stroke:#4B5563,color:#111827
```
