# coding-pelican/dasae-headers architecture

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

- Interactive diagram: https://gitdiagram.com/coding-pelican/dasae-headers
- Repository: https://github.com/coding-pelican/dasae-headers

## Overview

##### Project Type and Purpose
- This is a C-language extension library (header+source), plus a CLI build/test tool (dh-c), documentation in Markdown, example/sample code, and a small runtime (BlocksRuntime) for language extensions (blocks).
- Purpose: Provide modern safety, generics, error handling, testing framework, and a transpiler-like macro layer on top of C17, plus a project generator/build orchestrator and docs.

A. dh-c CLI Tool
– File: dh-c.c
– Responsibilities:
- “dh-c project” scaffolds new user projects
- “dh-c build/run/test” invokes the C compiler, runs tests, and orchestrates includes and macros.
– Interacts with configuration files (.clang-format, BUILD.md, install scripts).

B. Core Library
– Headers: dh/include/dh/**/*.h (API definitions, macros, builtin, core, debug, fs, heap, etc.)
– Sources: dh/src/*.c (implementations of runtime helpers, allocators, sort, time, etc.)
– Organization pattern: modular C code organized by feature (Arr, Err, TEST, heap, time, etc.)

C. External Runtime Library
– BlocksRuntime under dh/libs (provides micro-runtime support for “blocks” syntax).
– Compiled and linked into the core library or user binaries as needed.

D. Examples & Samples
– dh/examples/* and dh/samples/*: demonstration programs (Barnes-Hut N-body, engine samples, Game of Life, etc.)
– Show how users include “dh/*.h” and invoke macros.
– Built and run by dh-c or manually via Makefiles/clang commands.

E. Tests
– dh/tests/unit and dh/tests/integration:
- Unit tests for individual modules
- Integration tests using mockups
– They include “dh/TEST.h”, run by dh-c test or via C test harness.

F. Documentation
– dh/docs: Markdown docs in English/ Korean (home, quick-start, API, tutorials)
– Static content; consumed by docs generator (e.g., MkDocs, Docusaurus) or served as GitHub Pages.

##### Relationships & Data Flows
- dh-c CLI → reads configuration (install scripts, .clang‐*, BUILD.md) → orchestrates build/test tasks
- dh-c CLI → invokes C preprocessor + compiler (clang/gcc/msvc) on:
1. Core Library Sources (dh/src → object files)
2. Examples/Samples & Tests (dh/examples, dh/samples, dh/tests) linking against core library
- Core Library Headers → are #included by user code (examples/tests/scaffolded projects) → macros expand at compile time
- BlocksRuntime → compiled into core library or linked into executables requiring “blocks” support
- Documentation → authored in Markdown → consumed by doc generator (outside current build pipeline)

##### Architectural Patterns and Design Principles
- Modular C architecture: each feature is a separate module under dh/include & dh/src
- Header‐only API + optional compiled sources: user can include only headers or link compiled runtime
- Macro‐based transpiler: extensive use of C preprocessor for language extensions (defer, errdefer, union enum, etc.)
- Built-in test runner combined with macros for succinct test definitions
- CLI orchestrator (dh-c) implements the builder pattern for project scaffolding and reproducible builds

##### Essential Elements to Capture
– Component labels: dh-c CLI, C Compiler/Linker, Core Library (dh/include + dh/src), BlocksRuntime, Examples/Samples, Tests, Documentation.
- Tool → Compiler (build tasks)
- User code ← includes from Library
- Library → Compiled object/static lib
- Tests & Examples → Link against library

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Tooling
    dhc["dh-c CLI Tool"]:::tooling
    compiler["C Compiler/Linker"]:::tooling

    %% Core Library
    subgraph "Core Library"
        headers["Headers (dh/include/dh/)"]:::library
        sources["Sources (dh/src/)"]:::library
        compiled[("Compiled Objects / Static Lib")]:::storage
    end

    %% External Runtime
    blocks["BlocksRuntime"]:::library

    %% Consumer Code
    examples_ex["Examples (dh-examples/)"]:::consumer
    examples_sa["Samples (dh/samples/)"]:::consumer
    tests_unit["Unit Tests (dh/tests/unit/)"]:::consumer
    tests_int["Integration Tests (dh/tests/integration/)"]:::consumer

    %% Documentation
    docs["Documentation (dh/docs/)"]:::docs

    %% Generated Project Artifact
    generated[("Generated Project")]:::storage

    %% Connections
    dhc -->|"scaffold project"| generated
    dhc -->|"invoke compiler"| compiler
    compiler -->|"compile & link"| compiled
    sources --> compiled
    blocks --> compiled
    headers -->|"#include & macro expansion"| examples_ex
    headers -->|"#include & macro expansion"| examples_sa
    headers -->|"#include & macro expansion"| tests_unit
    headers -->|"#include & macro expansion"| tests_int
    examples_ex -->|"link against"| compiled
    examples_sa -->|"link against"| compiled
    tests_unit -->|"link & run tests"| compiled
    tests_int -->|"link & run tests"| compiled

    docs -.->|"consumed by doc generator"| docs

    %% Click Events
    click dhc "https://github.com/coding-pelican/dasae-headers/blob/main/dh-c.c"
    click headers "https://github.com/coding-pelican/dasae-headers/tree/main/dh/include/dh/"
    click sources "https://github.com/coding-pelican/dasae-headers/tree/main/dh/src/"
    click blocks "https://github.com/coding-pelican/dasae-headers/tree/main/dh/libs/BlocksRuntime/"
    click examples_ex "https://github.com/coding-pelican/dasae-headers/tree/main/dh-examples/"
    click examples_sa "https://github.com/coding-pelican/dasae-headers/tree/main/dh/samples/"
    click tests_unit "https://github.com/coding-pelican/dasae-headers/tree/main/dh/tests/unit/"
    click tests_int "https://github.com/coding-pelican/dasae-headers/tree/main/dh/tests/integration/"
    click docs "https://github.com/coding-pelican/dasae-headers/tree/main/dh/docs/"

    %% Styles
    classDef tooling fill:#ADD8E6,stroke:#000,color:#000;
    classDef library fill:#90EE90,stroke:#000,color:#000;
    classDef consumer fill:#FFA500,stroke:#000,color:#000;
    classDef docs fill:#D3D3D3,stroke:#000,color:#000;
    classDef storage fill:#F0E68C,stroke:#000,color:#000;
```
