How qgdev-ir/qbuild works
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: deserialize.c Dispatcher · test.c Runner · _deserialize.h Deserialize Internals · Makefile Makefile
Components 19
QBuild
Executable front end and top-level build entry for the project
QSON
Reusable JSON library consumed by QBuild
- Build · Builds the QSON library
qson/Makefile - API · External interface for consumers
qson/qson.h - Internals · Shared private declarations for QSON implementation
qson/_qson.h - Deserialize API · Public deserialization declarations
qson/deserialize/deserialize.h - Deserialize Internals · Private declarations for deserializer modules
qson/deserialize/_deserialize.h - Dispatcher · Coordinates JSON type dispatch and orchestration
qson/deserialize/deserialize.c - Array · Array deserialization logic
qson/deserialize/array.c - Object · Object deserialization logic
qson/deserialize/object.c - String · String deserialization logic
qson/deserialize/string.c
Tests
Mirror of the QSON modules for unit-style validation
- Build · Builds the test suite
test/Makefile - Runner · Test entry point and assertions
test/test.c - QSON tests · Tests for the public QSON API
test/qson/qson.c - Core tests · Tests for deserializer orchestration
test/qson/deserialize/deserialize.c - Array tests · Tests for array handling
test/qson/deserialize/array.c - Object tests · Tests for object handling
test/qson/deserialize/object.c
Connections 24
- 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