# thebigby10/picodb architecture

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

- Interactive diagram: https://gitdiagram.com/thebigby10/picodb
- Repository: https://github.com/thebigby10/picodb

## Overview

##### Project Type and Purpose
- PicoDB is a C++‐based, embeddable library simulating SQL database operations over CSV files.
- It can be used either via a Command‐Line Interface (CommandLineInterface.cpp) or linked into other C++ projects as a static library (libpicoDB.a).
- Core use case: provide SELECT, INSERT, UPDATE, DELETE, schema management, joins, key constraints, basic encryption, and data functions without a full RDBMS.

##### File Structure
Top‑level:
- CMakeLists.txt – build configuration.
- CommandLineInterface.cpp – optional CLI entry point.
- /PicoDB – public API headers.
- src/ – library implementation subdivided into:
– core/ (Database, Table, ConfigManager, UserPermissionManager, Cell)
– storage/ (FileHandler, Encryptor)
– utils/ (Date, Map, String, Vector, converters)
- examples/ – sample applications and CSV databases.
- tests/ – unit and integration tests.
- resources/ – images or other assets.
Patterns:
- Modular layering: API → core engine → storage layer → utilities.
- No external process; everything runs in‐process.
- CMake enables building static library and examples/tests.

##### Extract Insights from README
- Confirms the modules: CSV storage, XOR encryption, SQL operation support, schema management, join capabilities, key enforcement, filtering, functions, subqueries.
- Identifies intended usage (embedding via CMake, CLI demos).
- Suggests future docs folder (not yet present).

##### Main Architectural Components
a. Public API / Client Layer
- PicoDB class (PicoDB.h / PicoDB.cpp) – entry point for consumers and CLI.
- Command‐Line Interface (if used).
b. Core Engine
- Query Processor (part of Database and Table classes): parses incoming SQL commands.
- Schema Manager (ConfigManager) – loads/stores database and table configurations.
- Catalog / Metadata (Table, Cell, UserPermissionManager) – enforces schemas, primary/foreign keys, user permissions.
c. Storage Layer
- FileHandler – reads/writes CSV files to disk.
- Encryptor – applies XOR cipher on data streams when encryption is enabled.
d. Utilities Layer
- Data types and helpers: Date, String, Vector, Map, StringVectorConverter for parsing/conversion, Vector for result sets.
e. Build and Deployment
- CMake – orchestrates compilation into libpicoDB.a, builds examples and tests.
- Tests – unit test harness using custom tests in tests/ and basic_tests.
f. External Dependencies (C++17, standard library).

##### Relationships and Interactions
- Client/API → invokes methods on PicoDB instance.
- PicoDB instance → delegates to ConfigManager to initialize or load database metadata.
- For each SQL call: PicoDB → Database → Query Processor → performs in‐memory operations across Table and Cell structures, referencing metadata.
- Write operations → pass through storage layer: Table → FileHandler → optionally Encryptor → CSV file.
- Read operations → FileHandler reads CSV, optionally decrypts, then Query Processor filters and projects results.
- Utility classes assist parsing, type conversion, and internal data representation.

##### Architectural Patterns and Principles
- Layered architecture: clear separation between API, core logic, storage, and utilities.
- Single Responsibility: each module (ConfigManager, FileHandler, Encryptor) has a focused purpose.
- Dependency inversion: high‑level modules (Database) depend on abstractions (FileHandler interface).
- In‑process library design: embeddable static library, minimal external infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Client / Public API"
    PicoDB["PicoDB Class"]:::api
    CLI["CommandLineInterface"]:::api
  end

  subgraph "Core Engine"
    DB["Database (Query Processor)"]:::core
    Table["Table (Metadata Store)"]:::core
    Config["ConfigManager (Schema Manager)"]:::core
    Permissions["UserPermissionManager"]:::core
    Cell["Cell"]:::core
  end

  subgraph "Storage Layer"
    FileHandler["FileHandler (CSV I/O)"]:::storage
    Encryptor["Encryptor (XOR encryption)"]:::storage
    CSV["CSV Files"]:::storage
  end

  subgraph "Utilities"
    Date["Date"]:::utils
    Map["Map"]:::utils
    String["String"]:::utils
    Vector["Vector"]:::utils
    Converter["StringVectorConverter"]:::utils
  end

  subgraph "Build & Deployment"
    CMake["CMakeLists.txt"]:::build
  end

  subgraph "Example Applications"
    Examples["examples/"]:::build
  end

  subgraph "Tests"
    TestsNode["tests/"]:::build
  end

  CLI -->|"invoke"| PicoDB
  PicoDB -->|"init/load schema"| Config
  PicoDB -->|"init permissions"| Permissions
  PicoDB -->|"execute SQL"| DB
  DB -->|"metadata"| Table
  DB -->|"data cell ops"| Cell
  DB -->|"storage ops"| FileHandler
  FileHandler -->|"optional encryption"| Encryptor
  Encryptor -->|"persist data"| CSV
  Date -.-> DB
  Map -.-> Table
  String -.-> Config
  Vector -.-> DB
  Converter -.-> FileHandler
  CMake --> PicoDB
  Examples -->|"link against"| PicoDB
  TestsNode -->|"test API"| PicoDB

  click PicoDB "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/PicoDB.h"
  click CLI "https://github.com/thebigby10/picodb/blob/main/CommandLineInterface.cpp"
  click DB "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Database.h"
  click Table "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Table.h"
  click Config "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/ConfigManager.h"
  click Permissions "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/UserPermissionManager.h"
  click Cell "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Cell.h"
  click FileHandler "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/FileHandler.h"
  click Encryptor "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Encryptor.h"
  click Date "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Date.h"
  click Map "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Map.h"
  click String "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/String.h"
  click Vector "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/Vector.h"
  click Converter "https://github.com/thebigby10/picodb/blob/main/include/PicoDB/StringVectorConverter.h"
  click CMake "https://github.com/thebigby10/picodb/blob/main/CMakeLists.txt"
  click Examples "https://github.com/thebigby10/picodb/tree/main/examples/"
  click TestsNode "https://github.com/thebigby10/picodb/tree/main/tests/"

  classDef api fill:#cce5ff,stroke:#333,stroke-width:1px
  classDef core fill:#d4edda,stroke:#333,stroke-width:1px
  classDef storage fill:#fff3cd,stroke:#333,stroke-width:1px
  classDef utils fill:#e2e3e5,stroke:#333,stroke-width:1px
  classDef build fill:#ffeeba,stroke:#333,stroke-width:1px
```
