# lokestrom/database architecture

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

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

## Overview

#### Purpose and Consumption

`Database` is a C++23 library of custom containers, string/storage primitives, algorithms, and file I/O utilities. It is consumed as a CMake subproject and linked through the `Database` target, defined by `CMakeLists.txt`. Public API is header-oriented under `include/database`; `src/String.cpp` is the visible compiled implementation unit.

#### Public API Boundary

Consumers include individual headers from `include/database`, rather than interacting with an application executable. The principal API surface is organized into:
- String and related storage: `include/database/String.hpp`, `src/String.cpp`
- Dynamic contiguous storage: `include/database/Vector.hpp`, `include/database/TemplateFiles/Vector.tpp`
- FIFO/concurrent queue facilities: `include/database/Queue.hpp`, `include/database/TemplateFiles/Queue.tpp`
- File reading/writing/editing: `include/database/ReadFile.hpp`, `include/database/WriteFile.hpp`, `include/database/EditFile.hpp`

Template declarations are separated from implementations in `include/database/TemplateFiles`, so template users must receive definitions through the public headers’ inclusion structure.

#### Core Data Structures

`String` supplies the library’s string-oriented abstraction and is the only component with a dedicated `.cpp` implementation (`include/database/String.hpp`, `src/String.cpp`). `Vector` provides generic dynamic storage and likely serves as a foundational container for higher-level types (`include/database/Vector.hpp`, `include/database/TemplateFiles/Vector.tpp`). Queue facilities include ordinary queue behavior and the documented SPSC atomic static queue family (`include/database/Queue.hpp`, `include/database/TemplateFiles/Queue.tpp`).

Generic algorithms are centralized separately from the containers in `include/database/Algorythems.hpp` and `include/database/TemplateFiles/Algorythems.tpp`.

#### File I/O Pipeline

The library exposes file access as distinct stages rather than a unified database engine:
1. Read data through `include/database/ReadFile.hpp` and its template implementation.
2. Write data through `include/database/WriteFile.hpp`.
3. Modify existing content through `include/database/EditFile.hpp`.

These APIs form the primary external-system boundary: they interact with the host filesystem, while containers and strings represent in-memory data. Their template implementations reside in `include/database/TemplateFiles/ReadFile.tpp`, `include/database/TemplateFiles/WriteFile.tpp`, and `include/database/TemplateFiles/EditFile.tpp`.

#### Error and Safety Model

Error behavior is a cross-cutting design boundary controlled by exception availability and CMake options. `include/database/exceptionHandeling.hpp` provides the error-handling layer; the README specifies selectable forced throwing or return-based behavior, with `std::expected`-style results possible. `include/database/Unsafe.hpp` marks a separate lower-safety interface boundary. Generic constraints and type traits are represented by `include/database/concepts.hpp` and `include/database/traits.hpp`, with implementation support in `include/database/TemplateFiles/traits.tpp`.

#### Build and Runtime Context

The project requires C++23 and CMake, with builds verified on Clang and MSVC. It is a native library with no indicated network, database-server, UI, or cloud-service runtime. Its material runtime dependencies are the C++ standard library and host filesystem access through the file utility APIs. Tests exercise key public families but are not the architectural entry point.

#### Dependency Shape

Higher-level file utilities and queues depend on common generic infrastructure—custom `String`/`Vector`, concepts, traits, algorithms, and error handling—rather than external frameworks. The repository’s main control flow is therefore caller-driven: a consuming program constructs library containers or invokes file operations; templates execute inline at compile time, while string functionality may link against the compiled `Database` library artifact.

Main entry points: [`include/database/ReadFile.hpp`](https://github.com/lokestrom/database/blob/main/include/database/ReadFile.hpp) (Read File), [`include/database/WriteFile.hpp`](https://github.com/lokestrom/database/blob/main/include/database/WriteFile.hpp) (Write File), [`include/database/EditFile.hpp`](https://github.com/lokestrom/database/blob/main/include/database/EditFile.hpp) (Edit File), [`include/database/exceptionHandeling.hpp`](https://github.com/lokestrom/database/blob/main/include/database/exceptionHandeling.hpp) (Error Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_string_api["String<br/>[String.hpp]"]
  node_vector_api["Vector<br/>public container API<br/>[Vector.hpp]"]
  node_queue_api["Queue<br/>[Queue.hpp]"]
  node_algorithms_api["Algorithms<br/>[Algorythems.hpp]"]
end

subgraph group_templates["Template Implementations"]
  node_vector_templates["Vector Templates<br/>template definitions<br/>[Vector.tpp]"]
  node_queue_templates["Queue Templates<br/>template definitions<br/>[Queue.tpp]"]
  node_algorithm_templates["Algorithm Templates<br/>template definitions<br/>[Algorythems.tpp]"]
  node_traits_templates["Trait Templates<br/>template definitions<br/>[traits.tpp]"]
  node_read_templates["Read Templates<br/>template definitions<br/>[ReadFile.tpp]"]
  node_write_templates["Write Templates<br/>template definitions<br/>[WriteFile.tpp]"]
  node_edit_templates["Edit Templates<br/>template definitions<br/>[EditFile.tpp]"]
end

subgraph group_foundation["Core Infrastructure"]
  node_string_impl["String Implementation<br/>compiled implementation<br/>[String.cpp]"]
  node_concepts["Concepts<br/>generic constraints<br/>[concepts.hpp]"]
  node_traits["Traits<br/>[traits.hpp]"]
  node_errors["Error Handling<br/>error policy"]
  node_unsafe["Unsafe API<br/>safety boundary<br/>[Unsafe.hpp]"]
end

subgraph group_fileio["File I/O"]
  node_read["Read File<br/>file read API<br/>[ReadFile.hpp]"]
  node_write["Write File<br/>file write API<br/>[WriteFile.hpp]"]
  node_edit["Edit File<br/>file edit API<br/>[EditFile.hpp]"]
end

node_consumer(("C++ Consumer"))
node_build{{"Database CMake Target<br/>build target<br/>[CMakeLists.txt]"}}
node_filesystem[("Host Filesystem<br/>external runtime")]

node_consumer -->|"links"| node_build
node_build -->|"compiles"| node_string_impl
node_consumer -->|"includes"| node_string_api
node_consumer -->|"includes"| node_vector_api
node_consumer -->|"includes"| node_queue_api
node_consumer -->|"includes"| node_algorithms_api
node_consumer -->|"invokes"| node_read
node_consumer -->|"invokes"| node_write
node_consumer -->|"invokes"| node_edit
node_string_api -->|"implemented by"| node_string_impl
node_vector_api -->|"includes definitions"| node_vector_templates
node_queue_api -->|"includes definitions"| node_queue_templates
node_algorithms_api -->|"includes definitions"| node_algorithm_templates
node_traits -->|"includes definitions"| node_traits_templates
node_vector_api -.->|"constrained by"| node_concepts
node_queue_api -.->|"constrained by"| node_concepts
node_algorithms_api -.->|"uses"| node_traits
node_read -->|"includes definitions"| node_read_templates
node_write -->|"includes definitions"| node_write_templates
node_edit -->|"includes definitions"| node_edit_templates
node_read -->|"reads"| node_filesystem
node_write -->|"writes"| node_filesystem
node_edit -->|"modifies"| node_filesystem
node_read -.->|"reports through"| node_errors
node_write -.->|"reports through"| node_errors
node_edit -.->|"reports through"| node_errors
node_unsafe -.->|"separate safety policy"| node_errors

click node_build "https://github.com/lokestrom/database/blob/main/CMakeLists.txt"
click node_string_api "https://github.com/lokestrom/database/blob/main/include/database/String.hpp"
click node_vector_api "https://github.com/lokestrom/database/blob/main/include/database/Vector.hpp"
click node_queue_api "https://github.com/lokestrom/database/blob/main/include/database/Queue.hpp"
click node_algorithms_api "https://github.com/lokestrom/database/blob/main/include/database/Algorythems.hpp"
click node_string_impl "https://github.com/lokestrom/database/blob/main/src/String.cpp"
click node_vector_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/Vector.tpp"
click node_queue_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/Queue.tpp"
click node_algorithm_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/Algorythems.tpp"
click node_concepts "https://github.com/lokestrom/database/blob/main/include/database/concepts.hpp"
click node_traits "https://github.com/lokestrom/database/blob/main/include/database/traits.hpp"
click node_traits_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/traits.tpp"
click node_errors "https://github.com/lokestrom/database/blob/main/include/database/exceptionHandeling.hpp"
click node_unsafe "https://github.com/lokestrom/database/blob/main/include/database/Unsafe.hpp"
click node_read "https://github.com/lokestrom/database/blob/main/include/database/ReadFile.hpp"
click node_read_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/ReadFile.tpp"
click node_write "https://github.com/lokestrom/database/blob/main/include/database/WriteFile.hpp"
click node_write_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/WriteFile.tpp"
click node_edit "https://github.com/lokestrom/database/blob/main/include/database/EditFile.hpp"
click node_edit_templates "https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/EditFile.tpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_string_api,node_vector_api,node_queue_api,node_algorithms_api toneBlue
class node_vector_templates,node_queue_templates,node_algorithm_templates,node_traits_templates,node_read_templates,node_write_templates,node_edit_templates toneAmber
class node_string_impl,node_concepts,node_traits,node_errors,node_unsafe toneMint
class node_read,node_write,node_edit toneRose
class node_consumer,node_build,node_filesystem toneNeutral
```

## Components

### Public API

Header-oriented interfaces consumed by C++ callers.

- [String](https://github.com/lokestrom/database/blob/main/include/database/String.hpp): public string API · `include/database/String.hpp`
- [Vector](https://github.com/lokestrom/database/blob/main/include/database/Vector.hpp): public container API · `include/database/Vector.hpp`
- [Queue](https://github.com/lokestrom/database/blob/main/include/database/Queue.hpp): public queue API · Includes ordinary and SPSC atomic static queue facilities. · `include/database/Queue.hpp`
- [Algorithms](https://github.com/lokestrom/database/blob/main/include/database/Algorythems.hpp): generic algorithms · `include/database/Algorythems.hpp`

### Template Implementations

Inline definitions included through public headers.

- [Vector Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/Vector.tpp): template definitions · `include/database/TemplateFiles/Vector.tpp`
- [Queue Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/Queue.tpp): template definitions · `include/database/TemplateFiles/Queue.tpp`
- [Algorithm Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/Algorythems.tpp): template definitions · `include/database/TemplateFiles/Algorythems.tpp`
- [Trait Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/traits.tpp): template definitions · `include/database/TemplateFiles/traits.tpp`
- [Read Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/ReadFile.tpp): template definitions · `include/database/TemplateFiles/ReadFile.tpp`
- [Write Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/WriteFile.tpp): template definitions · `include/database/TemplateFiles/WriteFile.tpp`
- [Edit Templates](https://github.com/lokestrom/database/blob/main/include/database/TemplateFiles/EditFile.tpp): template definitions · `include/database/TemplateFiles/EditFile.tpp`

### Core Infrastructure

Shared data, generic, and safety foundations.

- [String Implementation](https://github.com/lokestrom/database/blob/main/src/String.cpp): compiled implementation · `src/String.cpp`
- [Concepts](https://github.com/lokestrom/database/blob/main/include/database/concepts.hpp): generic constraints · `include/database/concepts.hpp`
- [Traits](https://github.com/lokestrom/database/blob/main/include/database/traits.hpp): type traits · `include/database/traits.hpp`
- [Error Handling](https://github.com/lokestrom/database/blob/main/include/database/exceptionHandeling.hpp): error policy · Supports throwing or return-based error behavior. · `include/database/exceptionHandeling.hpp`
- [Unsafe API](https://github.com/lokestrom/database/blob/main/include/database/Unsafe.hpp): safety boundary · Separates lower-safety interfaces. · `include/database/Unsafe.hpp`

### File I/O

Filesystem-facing read, write, and edit stages.

- [Read File](https://github.com/lokestrom/database/blob/main/include/database/ReadFile.hpp): file read API · `include/database/ReadFile.hpp`
- [Write File](https://github.com/lokestrom/database/blob/main/include/database/WriteFile.hpp): file write API · `include/database/WriteFile.hpp`
- [Edit File](https://github.com/lokestrom/database/blob/main/include/database/EditFile.hpp): file edit API · `include/database/EditFile.hpp`

### Other components

- **C++ Consumer**: consumer · Links the Database target and includes public headers.
- [Database CMake Target](https://github.com/lokestrom/database/blob/main/CMakeLists.txt): build target · C++23 library target consumed as a subproject. · `CMakeLists.txt`
- **Host Filesystem**: external runtime · Primary external-system boundary.

## Connections

- C++ Consumer → Database CMake Target: links
- Database CMake Target → String Implementation: compiles
- C++ Consumer → String: includes
- C++ Consumer → Vector: includes
- C++ Consumer → Queue: includes
- C++ Consumer → Algorithms: includes
- C++ Consumer → Read File: invokes
- C++ Consumer → Write File: invokes
- C++ Consumer → Edit File: invokes
- String → String Implementation: implemented by
- Vector → Vector Templates: includes definitions
- Queue → Queue Templates: includes definitions
- Algorithms → Algorithm Templates: includes definitions
- Traits → Trait Templates: includes definitions
- Vector → Concepts: constrained by
- Queue → Concepts: constrained by
- Algorithms → Traits: uses
- Read File → Read Templates: includes definitions
- Write File → Write Templates: includes definitions
- Edit File → Edit Templates: includes definitions
- Read File → Host Filesystem: reads
- Write File → Host Filesystem: writes
- Edit File → Host Filesystem: modifies
- Read File → Error Handling: reports through
- Write File → Error Handling: reports through
- Edit File → Error Handling: reports through
- Unsafe API → Error Handling: separate safety policy