# cstack/db_tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/cstack/db_tutorial
- Repository: https://github.com/cstack/db_tutorial

## Overview

##### Project type and purpose
- This is a mixed-content repository that combines:
- A static site/tour tutorial built with Jekyll (Markdown parts, layouts, includes, Sass, etc.)
- A “Let's Build a Simple Database” C implementation (db.c, Makefile) with an accompanying test suite (spec/main_spec.rb).
- Purpose: render a step-by-step tutorial website and provide the reference C code for a toy database engine.

##### Main components
a. Content & Site Generator (Jekyll)
- Source content:
- `_parts/*.md` (tutorial chapters)
- `index.md`, `_includes/*`, `_layouts/*`
- `assets/css/style.scss`, `assets/images/*`
- `_config.yml`
- Toolchain:
- Ruby + Bundler (`Gemfile`, `Gemfile.lock`)
- Jekyll (`bundle exec jekyll serve`)
- Output:
- Static HTML/CSS/JS served locally or deployed (e.g., GitHub Pages)
b. Database Engine (C)
- Source: `db.c`
- Build: `Makefile` invokes gcc/clang
- Test harness: `spec/main_spec.rb` (Ruby test script or RSpec)
c. Deployment / Site Delivery
- The generated `feed.xml` and rendered HTML pages
- Can be hosted on GitHub Pages or any static-site host

##### Relationships & data flow
- Markdown & assets → Jekyll → Static website (HTML/CSS/JS)
- C source + Makefile → Compiler → db executable
- Test suite → Runs against db executable → Verification reports

##### Architectural patterns & principles
- Static-site generator pattern: separation of content, presentation (layouts), and theming (Sass).
- Single-responsibility: Jekyll handles only site build; Makefile handles only C code build.
- Test-driven or behavior-driven snippet: the spec folder demonstrates testing of the C engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository Root
    Repo["Repository Root"] 

    %% Site Generation Subgraph
    subgraph "Site Generation"
        direction TB
        subgraph "Content Layer"
            direction TB
            ContentParts["_parts/"]:::fileGroup
            Index["index.md"]:::fileGroup
        end
        subgraph "Presentation Layer"
            direction TB
            Layouts["_layouts/"]:::fileGroup
            Includes["_includes/"]:::fileGroup
            Styles["assets/css/"]:::fileGroup
            Images["assets/images/"]:::fileGroup
        end
        subgraph "Site Generator Toolchain"
            direction TB
            Gemfile["Gemfile"]:::fileGroup
            GemfileLock["Gemfile.lock"]:::fileGroup
            Config["_config.yml"]:::fileGroup
            Bundler["Bundler"]:::processor
            Jekyll["Jekyll"]:::processor
        end
        subgraph "Site Output"
            direction TB
            Feed["feed.xml"]:::output
            StaticSite["Static HTML/CSS/JS"]:::output
        end
    end

    %% Database Engine Subgraph
    subgraph "Database Engine"
        direction TB
        subgraph "Source & Build"
            direction TB
            DBC["db.c"]:::fileGroup
            Makefile["Makefile"]:::fileGroup
            Compiler["gcc/clang"]:::processor
            Executable["db executable"]:::output
        end
        subgraph "Test Suite"
            direction TB
            SpecDir["spec/"]:::fileGroup
            SpecFile["spec/main_spec.rb"]:::fileGroup
            TestRunner["Test Runner"]:::processor
            TestReport["Test Report"]:::output
        end
    end

    %% Connections
    Repo -->|"contains"| ContentParts
    Repo -->|"contains"| Index
    Repo -->|"contains"| Layouts
    Repo -->|"contains"| Includes
    Repo -->|"contains"| Styles
    Repo -->|"contains"| Images
    Repo -->|"contains"| Gemfile
    Repo -->|"contains"| GemfileLock
    Repo -->|"contains"| Config
    Repo -->|"contains"| DBC
    Repo -->|"contains"| Makefile
    Repo -->|"contains"| SpecDir

    ContentParts -->|"parse & render"| Jekyll
    Index -->|"parse & render"| Jekyll
    Layouts -->|"apply templates"| Jekyll
    Includes -->|"include snippets"| Jekyll
    Styles -->|"compile Sass"| Jekyll
    Images -->|"copy assets"| Jekyll
    Gemfile -->|"bundle install"| Bundler
    GemfileLock -->|"deps locked"| Bundler
    Config -->|"config loaded"| Jekyll
    Bundler -->|"runs"| Jekyll
    Jekyll -->|"generates"| Feed
    Jekyll -->|"generates"| StaticSite

    DBC -->|"provided to"| Compiler
    Makefile -->|"invoke"| Compiler
    Compiler -->|"compiles"| Executable

    Executable -->|"tested by"| TestRunner
    SpecFile -->|"defines tests"| TestRunner
    SpecDir -->|"contains tests"| TestRunner
    TestRunner -->|"produces"| TestReport

    %% Click Events
    click ContentParts "https://github.com/cstack/db_tutorial/tree/master/_parts/"
    click Index "https://github.com/cstack/db_tutorial/blob/master/index.md"
    click Layouts "https://github.com/cstack/db_tutorial/tree/master/_layouts/"
    click Includes "https://github.com/cstack/db_tutorial/tree/master/_includes/"
    click Styles "https://github.com/cstack/db_tutorial/tree/master/assets/css/"
    click Images "https://github.com/cstack/db_tutorial/tree/master/assets/images/"
    click Gemfile "https://github.com/cstack/db_tutorial/tree/master/Gemfile"
    click GemfileLock "https://github.com/cstack/db_tutorial/blob/master/Gemfile.lock"
    click Config "https://github.com/cstack/db_tutorial/blob/master/_config.yml"
    click DBC "https://github.com/cstack/db_tutorial/blob/master/db.c"
    click Makefile "https://github.com/cstack/db_tutorial/tree/master/Makefile"
    click SpecDir "https://github.com/cstack/db_tutorial/tree/master/spec/"
    click SpecFile "https://github.com/cstack/db_tutorial/blob/master/spec/main_spec.rb"

    %% Styles
    classDef fileGroup fill:#E8F1FA,stroke:#034BB5,color:#034BB5
    classDef processor fill:#E8F4E8,stroke:#24822E,color:#24822E
    classDef output fill:#FFF8E1,stroke:#C89F00,color:#C89F00
```
