# qgdev-ir/qbuild architecture

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

- Interactive diagram: https://gitdiagram.com/qgdev-ir/qbuild
- Repository: https://github.com/qgdev-ir/qbuild

## Overview

1. **Repository purpose and status**  
   This is an early-stage C project called **QBuild**. The README says it is a work in progress and currently in the “initialization” / “starting” phases, with the JSON processor still being selected or built.

2. **High-level architecture split**  
   The repo is organized into two main code areas:
   - **`qbuild/`**: the application/tool entry point.
   - **`qson/`**: a JSON-processing library that QBuild will consume.
   This makes the repository look like a tool plus an internal reusable library, rather than a single monolithic program.

3. **`qbuild` subsystem**  
   `qbuild/entry.c` is the only source file in the tool layer, which strongly suggests this is the executable front end or bootstrap point. The `qbuild/Makefile` indicates the tool is built separately from the library, likely linking against `qson`.

4. **`qson` subsystem boundary**  
   `qson/qson.h` is the public header for consumers, while `qson/_qson.h` is an internal/private header. That split implies a stable external API surface with internal implementation details hidden behind it.

5. **JSON deserialization internals**  
   The `qson/deserialize/` directory is the main implementation area today. It is broken into focused modules:
   - `array.c` / `array.h`
   - `object.c` / `object.h`
   - `string.c`
   - `deserialize.c` / `deserialize.h`
   This suggests a layered deserializer that handles JSON types separately and centralizes orchestration in `deserialize.c`.

6. **Likely data flow through the library**  
   The intended flow is: QBuild code calls the public `qson` API, which delegates into internal deserialization code, which then dispatches by JSON value type into array/object/string handlers. The separation by type is the main architectural boundary inside the library.

7. **Public API vs implementation detail**  
   The presence of both public headers and underscored private headers indicates a deliberate encapsulation boundary. External code should only include `qson/qson.h`, while internal modules share private declarations through `_qson.h` and `_deserialize.h`.

8. **Test architecture mirrors source layout**  
   The `test/` tree mirrors the `qson/` tree:
   - `test/qson/qson.c`
   - `test/qson/deserialize/*.c`
   - `test/test.c`, `test/test.h`
   This indicates unit-style coverage organized by subsystem, with tests aligned to the same module boundaries as the implementation.

9. **Build system layout**  
   There is a root `Makefile` plus nested Makefiles in `qbuild/`, `qson/`, and `test/`. That usually means each major component can be built independently, while the root makefile coordinates the overall build/test flow.

10. **CI / automation boundary**  
   `.github/workflows/test.yml` suggests automated test execution in CI. Given the repo structure, the CI likely builds the C targets and runs the test suite rather than deploying or packaging anything.

11. **External/technical context that matters**  
   The project is plain **C**, with manual headers/source organization and make-based builds. There is no sign of higher-level runtime, package manager, or framework; the architecture is intentionally low-level and library-centric.

12. **Best way to diagram this repo**  
   A clear architecture diagram would show:
   - a top-level **QBuild executable**,
   - a dependency arrow from QBuild to **QSON**,
   - inside QSON, a **public API layer** and a **private deserialization implementation**,
   - and a **test harness** that mirrors and validates the QSON modules.

Main entry points: [`qson/deserialize/deserialize.c`](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/deserialize.c) (Dispatcher), [`test/test.c`](https://github.com/qgdev-ir/qbuild/blob/main/test/test.c) (Runner), [`qson/deserialize/_deserialize.h`](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/_deserialize.h) (Deserialize Internals), [`Makefile`](https://github.com/qgdev-ir/qbuild/tree/main/Makefile) (Makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["QBuild"]
  node_qbuild_makefile["Build"]
  node_qbuild_entry["Entry<br/>executable bootstrap<br/>[entry.c]"]
end

subgraph group_group_qson["QSON"]
  node_qson_makefile["Build"]
  node_qson_public["API<br/>public header<br/>[qson.h]"]
  node_qson_private["Internals<br/>private header<br/>[_qson.h]"]
  node_deserialize_public["Deserialize API<br/>public header<br/>[deserialize.h]"]
  node_deserialize_private["Deserialize Internals<br/>private header<br/>[_deserialize.h]"]
  node_deserialize_core["Dispatcher<br/>deserializer core<br/>[deserialize.c]"]
  node_deserialize_array["Array<br/>[array.c]"]
  node_deserialize_object["Object<br/>[object.c]"]
  node_deserialize_string["String<br/>[string.c]"]
end

subgraph group_group_tests["Tests"]
  node_test_makefile["Build"]
  node_test_runner["Runner<br/>test harness<br/>[test.c]"]
  node_test_qson_api["QSON tests<br/>library tests<br/>[qson.c]"]
  node_test_deserialize_core["Core tests<br/>deserializer tests<br/>[deserialize.c]"]
  node_test_deserialize_array["Array tests<br/>deserializer tests<br/>[array.c]"]
  node_test_deserialize_object["Object tests<br/>deserializer tests<br/>[object.c]"]
end

subgraph group_group_automation["Automation"]
  node_root_makefile["Makefile<br/>build root"]
  node_ci_workflow["CI<br/>github workflow<br/>[test.yml]"]
end

node_root_makefile -->|"builds"| node_qbuild_makefile
node_root_makefile -->|"builds"| node_qson_makefile
node_root_makefile -->|"builds"| node_test_makefile
node_qbuild_entry -->|"uses"| node_qson_public
node_qbuild_entry -.->|"shares internals"| node_qson_private
node_qson_public -->|"exposes"| node_deserialize_public
node_deserialize_public -.->|"depends on"| node_deserialize_private
node_deserialize_core -->|"dispatches"| node_deserialize_array
node_deserialize_core -->|"dispatches"| node_deserialize_object
node_deserialize_core -->|"dispatches"| node_deserialize_string
node_deserialize_core -->|"uses"| node_deserialize_private
node_deserialize_array -->|"uses"| node_deserialize_private
node_deserialize_object -->|"uses"| node_deserialize_private
node_deserialize_string -->|"uses"| node_deserialize_private
node_test_runner -->|"runs"| node_test_qson_api
node_test_runner -->|"runs"| node_test_deserialize_core
node_test_runner -->|"runs"| node_test_deserialize_array
node_test_runner -->|"runs"| node_test_deserialize_object
node_test_qson_api -->|"verifies"| node_qson_public
node_test_deserialize_core -->|"verifies"| node_deserialize_core
node_test_deserialize_array -->|"verifies"| node_deserialize_array
node_test_deserialize_object -->|"verifies"| node_deserialize_object
node_ci_workflow -->|"invokes"| node_root_makefile
node_ci_workflow -->|"executes"| node_test_runner

click node_root_makefile "https://github.com/qgdev-ir/qbuild/tree/main/Makefile"
click node_qbuild_makefile "https://github.com/qgdev-ir/qbuild/tree/main/qbuild/Makefile"
click node_qbuild_entry "https://github.com/qgdev-ir/qbuild/blob/main/qbuild/entry.c"
click node_qson_makefile "https://github.com/qgdev-ir/qbuild/tree/main/qson/Makefile"
click node_qson_public "https://github.com/qgdev-ir/qbuild/blob/main/qson/qson.h"
click node_qson_private "https://github.com/qgdev-ir/qbuild/blob/main/qson/_qson.h"
click node_deserialize_public "https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/deserialize.h"
click node_deserialize_private "https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/_deserialize.h"
click node_deserialize_core "https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/deserialize.c"
click node_deserialize_array "https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/array.c"
click node_deserialize_object "https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/object.c"
click node_deserialize_string "https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/string.c"
click node_test_makefile "https://github.com/qgdev-ir/qbuild/tree/main/test/Makefile"
click node_test_runner "https://github.com/qgdev-ir/qbuild/blob/main/test/test.c"
click node_test_qson_api "https://github.com/qgdev-ir/qbuild/blob/main/test/qson/qson.c"
click node_test_deserialize_core "https://github.com/qgdev-ir/qbuild/blob/main/test/qson/deserialize/deserialize.c"
click node_test_deserialize_array "https://github.com/qgdev-ir/qbuild/blob/main/test/qson/deserialize/array.c"
click node_test_deserialize_object "https://github.com/qgdev-ir/qbuild/blob/main/test/qson/deserialize/object.c"
click node_ci_workflow "https://github.com/qgdev-ir/qbuild/blob/main/.github/workflows/test.yml"

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_qbuild_makefile,node_qbuild_entry toneBlue
class node_qson_makefile,node_qson_public,node_qson_private,node_deserialize_public,node_deserialize_private,node_deserialize_core,node_deserialize_array,node_deserialize_object,node_deserialize_string toneAmber
class node_test_makefile,node_test_runner,node_test_qson_api,node_test_deserialize_core,node_test_deserialize_array,node_test_deserialize_object toneMint
class node_root_makefile,node_ci_workflow toneRose
```

## Components

### QBuild

Executable front end and top-level build entry for the project

- [Build](https://github.com/qgdev-ir/qbuild/tree/main/qbuild/Makefile): build script · Builds the QBuild executable · `qbuild/Makefile`
- [Entry](https://github.com/qgdev-ir/qbuild/blob/main/qbuild/entry.c): executable bootstrap · Tool entry point and startup logic · `qbuild/entry.c`

### QSON

Reusable JSON library consumed by QBuild

- [Build](https://github.com/qgdev-ir/qbuild/tree/main/qson/Makefile): build script · Builds the QSON library · `qson/Makefile`
- [API](https://github.com/qgdev-ir/qbuild/blob/main/qson/qson.h): public header · External interface for consumers · `qson/qson.h`
- [Internals](https://github.com/qgdev-ir/qbuild/blob/main/qson/_qson.h): private header · Shared private declarations for QSON implementation · `qson/_qson.h`
- [Deserialize API](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/deserialize.h): public header · Public deserialization declarations · `qson/deserialize/deserialize.h`
- [Deserialize Internals](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/_deserialize.h): private header · Private declarations for deserializer modules · `qson/deserialize/_deserialize.h`
- [Dispatcher](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/deserialize.c): deserializer core · Coordinates JSON type dispatch and orchestration · `qson/deserialize/deserialize.c`
- [Array](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/array.c): json array handler · Array deserialization logic · `qson/deserialize/array.c`
- [Object](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/object.c): json object handler · Object deserialization logic · `qson/deserialize/object.c`
- [String](https://github.com/qgdev-ir/qbuild/blob/main/qson/deserialize/string.c): json string handler · String deserialization logic · `qson/deserialize/string.c`

### Tests

Mirror of the QSON modules for unit-style validation

- [Build](https://github.com/qgdev-ir/qbuild/tree/main/test/Makefile): test build script · Builds the test suite · `test/Makefile`
- [Runner](https://github.com/qgdev-ir/qbuild/blob/main/test/test.c): test harness · Test entry point and assertions · `test/test.c`
- [QSON tests](https://github.com/qgdev-ir/qbuild/blob/main/test/qson/qson.c): library tests · Tests for the public QSON API · `test/qson/qson.c`
- [Core tests](https://github.com/qgdev-ir/qbuild/blob/main/test/qson/deserialize/deserialize.c): deserializer tests · Tests for deserializer orchestration · `test/qson/deserialize/deserialize.c`
- [Array tests](https://github.com/qgdev-ir/qbuild/blob/main/test/qson/deserialize/array.c): deserializer tests · Tests for array handling · `test/qson/deserialize/array.c`
- [Object tests](https://github.com/qgdev-ir/qbuild/blob/main/test/qson/deserialize/object.c): deserializer tests · Tests for object handling · `test/qson/deserialize/object.c`

### Automation

Repository-level build and CI coordination

- [Makefile](https://github.com/qgdev-ir/qbuild/tree/main/Makefile): build root · Top-level build coordinator · `Makefile`
- [CI](https://github.com/qgdev-ir/qbuild/blob/main/.github/workflows/test.yml): github workflow · Automated build and test execution · `.github/workflows/test.yml`

## Connections

- Makefile → Build: builds · Coordinates the executable build
- Makefile → Build: builds · Coordinates the library build
- Makefile → Build: builds · Coordinates the test build
- Entry → API: uses · Executable depends on the public library API
- Entry → Internals: shares internals · Tool may rely on library-private declarations through the library boundary
- API → Deserialize API: exposes · Public API forwards into deserialization support
- Deserialize API → Deserialize Internals: depends on · Public declarations are implemented with private internals
- Dispatcher → Array: dispatches · Core routes array values to array handler
- Dispatcher → Object: dispatches · Core routes object values to object handler
- Dispatcher → String: dispatches · Core routes string values to string handler
- Dispatcher → Deserialize Internals: uses · Core orchestrator uses private shared declarations
- Array → Deserialize Internals: uses · Array handler uses private deserializer declarations
- Object → Deserialize Internals: uses · Object handler uses private deserializer declarations
- String → Deserialize Internals: uses · String handler uses private deserializer declarations
- Runner → QSON tests: runs · Harness executes library-level tests
- Runner → Core tests: runs · Harness executes core deserializer tests
- Runner → Array tests: runs · Harness executes array tests
- Runner → Object tests: runs · Harness executes object tests
- QSON tests → API: verifies · Tests validate the public API surface
- Core tests → Dispatcher: verifies · Tests validate orchestration behavior
- Array tests → Array: verifies · Tests validate array handling
- Object tests → Object: verifies · Tests validate object handling
- CI → Makefile: invokes · CI runs repository build entry point
- CI → Runner: executes · CI runs the test suite