# mahopanda/golang-database architecture

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

- Interactive diagram: https://gitdiagram.com/mahopanda/golang-database
- Repository: https://github.com/mahopanda/golang-database

## Overview

##### Project type and purpose
- This is a Go-based, file-backed key-value NoSQL database library (inspired by Bitcask/MongoDB) that provides dynamic schema support, CRUD operations, basic query filtering, and concurrency safety.
- It is intended to be used as an embeddable storage engine rather than a standalone server.

##### File structure
- Top level:
- main.go – example usage and entry point
- go.mod / go.sum – module definitions
- .gitignore / .coderabbit.yaml – config
- database/ – core library package
- test/ – unit tests for driver and storage
- database/ sub-components:
- driver.go – high-level API, orchestrates reads/writes, applies locks, logs operations
- storage.go – implements file-based JSON persistence using a Serializer interface
- lock_manager.go – concurrency control (sync.Mutex per collection or key)
- logger.go – pluggable logging (e.g., console logger)
- serializer.go (mentioned in README) – converts Go objects to/from JSON

##### README for additional insights
- Lists key features: dynamic schema, CRUD, custom query filters, JSON file storage, concurrency safety.
- Describes how the consumer instantiates Logger, FileStore, Driver and performs Write/Read/Query/Delete calls.
- Mentions JSONSerializer, FileStore, Driver, LockManager, ConsoleLogger.

a. Main components:
- Client Code / main.go (Consumer API)
- Driver
- Lock Manager
- Logger
- Serializer
- FileStore (storage engine)
- File System (JSON files on disk)
b. Relationships & data flows:
1. Client → Driver: invokes Write/Read/Query/Delete
2. Driver → Lock Manager: acquire/release locks for concurrency
3. Driver → Logger: log operations and errors
4. Driver → FileStore: delegate persistence operations
5. FileStore ↔ Serializer: serialize objects to JSON and deserialize JSON to Go structs
6. FileStore → File System: read/write JSON files in storage directory
c. Architectural patterns & design principles:
- Layered architecture: API layer (Driver) → Storage layer → Persistence
- Dependency inversion via interfaces (Logger, Serializer, Store) for pluggability and testing
- Single responsibility: each component has a well-defined role (locking, logging, serialization, I/O)
d. Technologies & libraries:
- Go’s standard library (sync.Mutex, encoding/json, io/fs)
- Custom interfaces (Store, Serializer, Logger)

##### Final recommendations
- Be exhaustive: include every interface and its implementation class.
- Collection-level locks inside the Lock Manager component.
- Configuration input (e.g., storage path, serializer choice) feeding into FileStore.
- Component names match the code (driver.go → “Driver”, lock_manager.go → “Lock Manager”, etc.).
- Keep it simple but comprehensive—cover all moving parts without extraneous detail.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API / Driver Layer
    Client["Client Code"]:::api
    Driver["Driver"]:::api

    %% Concurrency & Logging Layer
    Lock["Lock Manager"]:::concurrency
    Logger["Logger"]:::concurrency

    %% Persistence & Serialization Layer
    Serializer["Serializer"]:::persistence
    FileStore["FileStore"]:::persistence
    FileSystem[(File System)]:::persistence

    %% Unit Tests
    subgraph "Unit Tests"
        DriverTest["driver_test.go"]:::test
        StorageTest["storage_test.go"]:::test
    end

    %% Connections
    Client -->|"Write/Read/Query/Delete"| Driver
    Driver -->|"AcquireLock/ReleaseLock"| Lock
    Driver -->|"LogOperation"| Logger
    Driver -->|"Persist/Fetch Data"| FileStore
    FileStore -->|"Serialize/Deserialize"| Serializer
    FileStore -->|"Read/Write JSON Files"| FileSystem
    DriverTest --> Driver
    StorageTest --> FileStore

    %% Click Events
    click Client "https://github.com/mahopanda/golang-database/blob/main/main.go"
    click Driver "https://github.com/mahopanda/golang-database/blob/main/database/driver.go"
    click Lock "https://github.com/mahopanda/golang-database/blob/main/database/lock_manager.go"
    click Logger "https://github.com/mahopanda/golang-database/blob/main/database/logger.go"
    click FileStore "https://github.com/mahopanda/golang-database/blob/main/database/storage.go"
    click DriverTest "https://github.com/mahopanda/golang-database/blob/main/test/driver_test.go"
    click StorageTest "https://github.com/mahopanda/golang-database/blob/main/test/storage_test.go"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#2E86C1,color:#1B4F72;
    classDef concurrency fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef persistence fill:#D4EFDF,stroke:#27AE60,color:#145A32;
    classDef test fill:#F5B7B1,stroke:#922B21,color:#641E16;
```
