# nam178/foodb architecture

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

- Interactive diagram: https://gitdiagram.com/nam178/foodb
- Repository: https://github.com/nam178/foodb

## Overview

##### Project type and purpose
- This is a tutorial/example project showing how to build a block-based embedded database with a B-Tree index in C#.
- It consists of three main deliverables:
- FooCore: the core database engine (block storage, record storage, B-Tree index, serializers).
- FooApplication: a sample console app that demonstrates storing/retrieving “Cow” records on top of FooCore.
- FooTest: unit tests (NUnit) that validate core behaviors (block storage, B-Tree operations, serialization).

##### File structure
- Top-level solution FooDB.sln orchestrates three projects.
- FooCore directory:
- Interfaces (IBlockStorage, IRecordStorage, ITreeNodeManager, ISerializer, etc.)
- Implementations (BlockStorage, RecordStorage, TreeDiskNodeManager, TreeMemoryNodeManager, Tree, serializers, helpers)
- B-Tree classes (TreeNode, TreeTraverser, TreeHelper, TreeDiskNodeSerializer, etc.)
- Byte‐order and stream‐extension utilities.
- FooApplication directory:
- Domain model (CowModel)
- Database façade (ICowDatabase, CowDatabase)
- Serializers specific to domain (CowSerializer, GuidSerializer, StringIntSerializer)
- Console entrypoint (Program.cs)
- FooTest directory: NUnit test fixtures covering storage and tree operations.
- packages folder holds external dependencies (NUnit).

##### README for additional insights
- Describes purpose: “build a block-based database with B-Tree index”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Console UI\nProgram.cs"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer"
        ICow["ICowDatabase"]:::domain
        CowDB["CowDatabase"]:::domain
        CowModel["CowModel"]:::domain
        CowSer["CowSerializer"]:::domain
        GuidSer["GuidSerializer"]:::domain
        StrIntSer["StringIntSerializer"]:::domain
    end

    %% Core Engine
    subgraph "Core Engine"
        subgraph "Storage Engine"
            IBlockStorage["IBlockStorage"]:::core
            IRecordStorage["IRecordStorage"]:::core
            BlockStorage["BlockStorage"]:::core
            RecordStorage["RecordStorage"]:::core
            IBlock["IBlock"]:::core
            Block["Block"]:::core
        end
        subgraph "Index Engine"
            IIndex["IIndex"]:::core
            Tree["Tree"]:::core
            ITreeNodeMgr["ITreeNodeManager"]:::core
            TreeDiskMgr["TreeDiskNodeManager"]:::core
            TreeMemMgr["TreeMemoryNodeManager"]:::core
            TreeTrav["TreeTraverser"]:::core
            TreeHelp["TreeHelper"]:::core
            TreeEnum["TreeEnumerator"]:::core
            TreeDir["TreeTraverseDirection"]:::core
            ISer["ISerializer<T>"]:::core
            TreeDiskSer["TreeDiskNodeSerializer"]:::core
            TreeSerEx["TreeNodeSerializationException"]:::core
            TreeIntSer["TreeIntSerializer"]:::core
            TreeLongSer["TreeLongSerializer"]:::core
            TreeStrSer["TreeStringSerializer"]:::core
        end
        subgraph "Utilities"
            LittleEndian["LittleEndianByteOrder"]:::util
            BufferHelp["BufferHelper"]:::util
            StreamExt["StreamExtension"]:::util
            StreamReadWrap["StreamReadWrapper"]:::util
        end
    end

    %% Physical Layer
    FileSys["File System/Disk I/O"]:::disk

    %% Test Harness
    FooTest["FooTest (NUnit Tests)"]:::test

    %% Interactions
    UI -->|invokes| ICow
    ICow -->|implements| CowDB
    CowDB -->|uses| RecordStorage
    CowDB -->|uses| Tree
    RecordStorage -->|writes/reads| BlockStorage
    BlockStorage -->|reads/writes pages| FileSys
    Tree -->|traverses| ITreeNodeMgr
    Tree -->|uses| ISer
    ITreeNodeMgr -->|serializes nodes| TreeDiskSer
    TreeDiskSer -->|depends on| LittleEndian
    RecordStorage -->|depends on| IBlockStorage
    IBlockStorage -->|defines| Block
    IRecordStorage -->|defines| IBlock
    StreamExt -->|extends| BufferHelp

    FooTest -->|tests| RecordStorage
    FooTest -->|tests| Tree

    %% Click Events
    click UI "https://github.com/nam178/foodb/blob/master/FooApplication/Program.cs"
    click ICow "https://github.com/nam178/foodb/blob/master/FooApplication/ICowDatabase.cs"
    click CowDB "https://github.com/nam178/foodb/blob/master/FooApplication/CowDatabase.cs"
    click CowModel "https://github.com/nam178/foodb/blob/master/FooApplication/CowModel.cs"
    click CowSer "https://github.com/nam178/foodb/blob/master/FooApplication/CowSerializer.cs"
    click GuidSer "https://github.com/nam178/foodb/blob/master/FooApplication/GuidSerializer.cs"
    click StrIntSer "https://github.com/nam178/foodb/blob/master/FooApplication/StringIntSerializer.cs"
    click IBlockStorage "https://github.com/nam178/foodb/blob/master/FooCore/IBlockStorage.cs"
    click IRecordStorage "https://github.com/nam178/foodb/blob/master/FooCore/IRecordStorage.cs"
    click BlockStorage "https://github.com/nam178/foodb/blob/master/FooCore/BlockStorage.cs"
    click RecordStorage "https://github.com/nam178/foodb/blob/master/FooCore/RecordStorage.cs"
    click IBlock "https://github.com/nam178/foodb/blob/master/FooCore/IBlock.cs"
    click Block "https://github.com/nam178/foodb/blob/master/FooCore/Block.cs"
    click LittleEndian "https://github.com/nam178/foodb/blob/master/FooCore/LittleEndianByteOrder.cs"
    click BufferHelp "https://github.com/nam178/foodb/blob/master/FooCore/BufferHelper.cs"
    click StreamExt "https://github.com/nam178/foodb/blob/master/FooCore/StreamExtension.cs"
    click StreamReadWrap "https://github.com/nam178/foodb/blob/master/FooCore/StreamReadWrapper.cs"
    click IIndex "https://github.com/nam178/foodb/blob/master/FooCore/IIndex.cs"
    click Tree "https://github.com/nam178/foodb/blob/master/FooCore/Tree.cs"
    click ITreeNodeMgr "https://github.com/nam178/foodb/blob/master/FooCore/ITreeNodeManager.cs"
    click TreeDiskMgr "https://github.com/nam178/foodb/blob/master/FooCore/TreeDiskNodeManager.cs"
    click TreeMemMgr "https://github.com/nam178/foodb/blob/master/FooCore/TreeMemoryNodeManager.cs"
    click TreeTrav "https://github.com/nam178/foodb/blob/master/FooCore/TreeTraverser.cs"
    click TreeHelp "https://github.com/nam178/foodb/blob/master/FooCore/TreeHelper.cs"
    click TreeEnum "https://github.com/nam178/foodb/blob/master/FooCore/TreeEnumerator.cs"
    click TreeDir "https://github.com/nam178/foodb/blob/master/FooCore/TreeTraverseDirection.cs"
    click ISer "https://github.com/nam178/foodb/blob/master/FooCore/ISerializer.cs"
    click TreeDiskSer "https://github.com/nam178/foodb/blob/master/FooCore/TreeDiskNodeSerializer.cs"
    click TreeSerEx "https://github.com/nam178/foodb/blob/master/FooCore/TreeNodeSerializationException.cs"
    click TreeIntSer "https://github.com/nam178/foodb/blob/master/FooCore/TreeIntSerializer.cs"
    click TreeLongSer "https://github.com/nam178/foodb/blob/master/FooCore/TreeLongSerializer.cs"
    click TreeStrSer "https://github.com/nam178/foodb/blob/master/FooCore/TreeStringSerialzier.cs"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef domain fill:#90EE90,stroke:#333,stroke-width:1px
    classDef core fill:#FFA500,stroke:#333,stroke-width:1px
    classDef util fill:#FFD700,stroke:#333,stroke-width:1px
    classDef disk fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef test fill:#CCCCCC,stroke:#333,stroke-width:1px
```
