# wxn0brp/valtheradb architecture

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

- Interactive diagram: https://gitdiagram.com/wxn0brp/valtheradb
- Repository: https://github.com/wxn0brp/valtheradb

## Overview

##### Project Type and Purpose
- ValtheraDB is a reusable, file-based database management library (an open-source tool).
- It provides CRUD operations, custom queries, graph structures, and remote synchronization.

##### File Structure
- Top-level “src” directory contains all TS modules.
- “cdn” folder holds browser/CDN builds.
- “docs” hosts Markdown-based documentation.
- Config & build scripts: tsconfig.json, package.json, GitHub workflows.

##### Main Components
a. API Layer
- Public classes exported from src/index.ts: Valthera, Graph, Relation, etc.
- Client-side proxies under src/client/* (function.ts, graph.ts, remote.ts, valthera.ts).
b. Core Engine
- CollectionManager.ts orchestrates operations.
- executor.ts runs actions.
- action.ts defines commands (CRUD, graph).
c. Persistence Adapters
- File-based adapter modules in src/file/* (customFileCpu.ts, find.ts, update.ts, remove.ts, transactions.ts).
- Memory adapter in src/memory.ts for in-RAM storage.
- AutoCreate adapter in src/autoCreate.ts for auto-schema creation.
d. Data Model & Utilities
- Graph and Relation modules (src/graph.ts, src/relation.ts).
- ID generator (gen.ts) and utilities (src/utils/*).
- Type definitions under src/types/*.
e. Remote & CDN
- ValtheraRemote & GraphRemote client definitions in src/client/remote.ts.
- cdn/index.js & kyShim.js — browser-friendly bundles.

##### Relationships & Data Flow
- Conditional branching in Persistence Adapters: file vs memory vs autoCreate.
- Remote clients call over HTTP (or fetch) to a server endpoint (if applicable), or communicate peer-to-peer.
- CDN bundle wraps API Layer for browser usage.

##### Architectural Patterns & Design Principles
- Strategy Pattern for interchangeable storage adapters (file, memory, auto-create).
- Command Pattern via action.ts and executor.ts.
- Modular architecture: clear separation of concerns (API, engine, storage, utils, types).
- Extensibility: new adapters conform to the same interface.

3. Beneath, lay out three storage adapters side by side (File Adapter, Memory Adapter, AutoCreate).
5. At right, show “Remote Client” interacting with a “Remote Server” or service endpoint.
6. At left or bottom, add “CDN Bundle” block to indicate browser usage.
7. Link utility modules (utils, types, gen) as supporting components feeding into all layers.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% API Layer
  subgraph "API Layer"
    API_Index["index.ts (API Layer)"]:::core
    Client_Function["function.ts (Client Proxy)"]:::core
    Client_Graph["graph.ts (Client Proxy)"]:::core
    Client_Remote["remote.ts (Client Proxy)"]:::core
    Client_Valthera["valthera.ts (Client Proxy)"]:::core
  end

  %% Core Engine
  subgraph "Core Engine"
    CollectionManager["CollectionManager.ts"]:::core
    Executor["executor.ts"]:::core
    Action["action.ts"]:::core
  end

  %% Persistence Adapters
  subgraph "Persistence Adapters"
    subgraph "File-Based Adapters"
      File_Index["index.ts"]:::adapter
      File_CustomCpu["customFileCpu.ts"]:::adapter
      File_Find["find.ts"]:::adapter
      File_Update["update.ts"]:::adapter
      File_Remove["remove.ts"]:::adapter
      File_Transactions["transactions.ts"]:::adapter
      File_Utils["utils.ts"]:::adapter
    end
    Memory["memory.ts"]:::adapter
    AutoCreate["autoCreate.ts"]:::adapter
  end

  %% Data Model
  subgraph "Data Model"
    Graph["graph.ts"]:::core
    Relation["relation.ts"]:::core
  end

  %% Utilities & Types
  subgraph "Utilities & Types"
    Gen["gen.ts"]:::util
    Utils_HasFields["hasFields.ts"]:::util
    Utils_HasFieldsAdvanced["hasFieldsAdvanced.ts"]:::util
    Utils_UpdateFindObject["updateFindObject.ts"]:::util
    Utils_UpdateObject["updateObject.ts"]:::util
    Types["types/*"]:::util
  end

  %% Remote & CDN
  subgraph "Remote & CDN"
    CDN_Index["cdn/index.js"]:::external
    CDN_KyShim["cdn/kyShim.js"]:::external
    Remote_Client["Client Remote"]:::external
    Remote_Server["Remote Server"]:::external
  end

  %% Documentation
  Docs["docs/*.md"]:::external

  %% Connections
  API_Index -->|"uses"| CollectionManager
  API_Index -->|"uses"| Executor
  API_Index -->|"defines"| Action

  Client_Function -->|calls| API_Index
  Client_Graph -->|calls| API_Index
  Client_Remote -->|calls| API_Index
  Client_Valthera -->|calls| API_Index

  CollectionManager -->|"orchestrates"| Executor
  Executor -->|"executes"| Action
  Action -->|"invokes"| File_Index
  Action -->|"invokes"| Memory
  Action -->|"invokes"| AutoCreate

  File_Index --> File_CustomCpu
  File_Index --> File_Find
  File_Index --> File_Update
  File_Index --> File_Remove
  File_Index --> File_Transactions
  File_Index --> File_Utils

  Graph -->|integrates with| CollectionManager
  Relation -->|integrates with| CollectionManager
  Graph -->|reads/writes| File_Index
  Relation -->|reads/writes| File_Index

  Remote_Client -->|HTTP/fetch| Remote_Server
  Remote_Client -->|wraps| Client_Remote

  CDN_Index -->|bundle wraps| API_Index
  CDN_KyShim -->|shim for| CDN_Index

  Gen -->|generates IDs for| CollectionManager
  Utils_HasFields -->|utility for| Action
  Utils_HasFieldsAdvanced -->|utility for| Action
  Utils_UpdateFindObject -->|utility for| Executor
  Utils_UpdateObject -->|utility for| Executor
  Types -->|types for| API_Index
  Types -->|types for| Action
  Types -->|types for| Executor

  Docs -->|documentation for| API_Index
  Docs -->|documentation for| CollectionManager

  %% Click Events
  click API_Index "https://github.com/wxn0brp/valtheradb/blob/main/src/index.ts"
  click Client_Function "https://github.com/wxn0brp/valtheradb/blob/main/src/client/function.ts"
  click Client_Graph "https://github.com/wxn0brp/valtheradb/blob/main/src/client/graph.ts"
  click Client_Remote "https://github.com/wxn0brp/valtheradb/blob/main/src/client/remote.ts"
  click Client_Valthera "https://github.com/wxn0brp/valtheradb/blob/main/src/client/valthera.ts"
  click Action "https://github.com/wxn0brp/valtheradb/blob/main/src/action.ts"
  click Executor "https://github.com/wxn0brp/valtheradb/blob/main/src/executor.ts"
  click CollectionManager "https://github.com/wxn0brp/valtheradb/blob/main/src/CollectionManager.ts"
  click File_CustomCpu "https://github.com/wxn0brp/valtheradb/blob/main/src/file/customFileCpu.ts"
  click File_Find "https://github.com/wxn0brp/valtheradb/blob/main/src/file/find.ts"
  click File_Update "https://github.com/wxn0brp/valtheradb/blob/main/src/file/update.ts"
  click File_Remove "https://github.com/wxn0brp/valtheradb/blob/main/src/file/remove.ts"
  click File_Transactions "https://github.com/wxn0brp/valtheradb/blob/main/src/file/transactions.ts"
  click File_Index "https://github.com/wxn0brp/valtheradb/blob/main/src/file/index.ts"
  click File_Utils "https://github.com/wxn0brp/valtheradb/blob/main/src/file/utils.ts"
  click Memory "https://github.com/wxn0brp/valtheradb/blob/main/src/memory.ts"
  click AutoCreate "https://github.com/wxn0brp/valtheradb/blob/main/src/autoCreate.ts"
  click Graph "https://github.com/wxn0brp/valtheradb/blob/main/src/graph.ts"
  click Relation "https://github.com/wxn0brp/valtheradb/blob/main/src/relation.ts"
  click Gen "https://github.com/wxn0brp/valtheradb/blob/main/src/gen.ts"
  click Utils_HasFields "https://github.com/wxn0brp/valtheradb/blob/main/src/utils/hasFields.ts"
  click Utils_HasFieldsAdvanced "https://github.com/wxn0brp/valtheradb/blob/main/src/utils/hasFieldsAdvanced.ts"
  click Utils_UpdateFindObject "https://github.com/wxn0brp/valtheradb/blob/main/src/utils/updateFindObject.ts"
  click Utils_UpdateObject "https://github.com/wxn0brp/valtheradb/blob/main/src/utils/updateObject.ts"
  click Types "https://github.com/wxn0brp/valtheradb/tree/main/src/types/*"
  click CDN_Index "https://github.com/wxn0brp/valtheradb/blob/main/cdn/index.js"
  click CDN_KyShim "https://github.com/wxn0brp/valtheradb/blob/main/cdn/kyShim.js"

  %% Styles
  classDef core fill:#ADD8E6,stroke:#000;
  classDef adapter fill:#90EE90,stroke:#000;
  classDef util fill:#FFA500,stroke:#000;
  classDef external fill:#D3D3D3,stroke:#000;
```
