Developer Guide¶

This guide is for engineers who read, modify, or extend the HyperbyteDB codebase. It covers the internal architecture, development setup, code conventions, testing strategy, and contribution process.

Contents¶

1. Architecture — Hexagonal design, component overview, data flow diagrams (Mermaid), and how the system fits together.

2. System architecture — Long-form internal design: module structure, write/query paths, WAL, Parquet, clustering, services, and dependencies (companion to the deep dive series).

3. Development Setup — Local environment, prerequisites, building, running, and debugging.

4. Internals

5. Core Modules — Module-by-module source code guide covering every directory under src/.
6. Key Design Decisions — Deep dives into the write path, read path, compaction, clustering, and replication.
7. Replication design — Replication wire protocol, sync_quorum, hinted handoff, flow control.

8. Extension Points — How to add new InfluxQL statements, storage backends, background services, and HTTP endpoints.

9. Coding Standards — Error handling, async patterns, naming conventions, metrics, logging, and dependency injection.

10. Testing — Test suite inventory, how to run tests, how to write new tests, and test architecture.

11. Building & CI — CI pipeline, Docker builds, release profiles, and the container workflow.

12. Contributing — PR process, code review rubric, engineering policies, and the review checklist.

Quick Reference¶