mikael-lovqvists-claude-agent
bf18054a2c
Move modules under src/modules/ and public headers under include/, keeping dev/, tests/, and docs at the top level. Adds a placeholder for src/node/ where the final video node entry point will live. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# Planning
|
|
|
|
## Approach
|
|
|
|
Build the system module by module in C11. Each module is a translation unit (`.h` + `.c`) with a clearly defined API. Modules are exercised by small driver programs in `dev/` before anything depends on them. This keeps each unit independently testable and prevents architectural decisions from being made prematurely in code.
|
|
|
|
The final binary is a single configurable node program. That integration work comes after the modules are solid.
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
video-setup/
|
|
src/
|
|
modules/
|
|
common/ - shared definitions (error types, base types)
|
|
media_ctrl/ - Linux Media Controller API (topology, pad formats, links)
|
|
v4l2_ctrl/ - V4L2 camera controls (enumerate, get, set)
|
|
node/ - video node entry point and top-level integration (later)
|
|
include/ - public headers
|
|
dev/
|
|
cli/ - exploratory CLI drivers, one per module
|
|
experiments/ - freeform experiments
|
|
tests/ - automated tests (later)
|
|
Makefile
|
|
architecture.md
|
|
planning.md
|
|
conventions.md
|
|
```
|
|
|
|
---
|
|
|
|
## Module Order
|
|
|
|
Modules are listed in intended build order. Each depends only on modules above it.
|
|
|
|
| # | Module | Status | Notes |
|
|
|---|---|---|---|
|
|
| 1 | `common` | not started | Error types, base definitions — no dependencies |
|
|
| 2 | `media_ctrl` | not started | Media Controller API — device and topology enumeration, pad format config |
|
|
| 3 | `v4l2_ctrl` | not started | V4L2 controls — enumerate, get, set camera parameters |
|
|
| 4 | `transport` | not started | Encapsulated transport — header encode/decode, framed TCP read/write |
|
|
| 5 | `frame_alloc` | not started | Per-frame allocation with bookkeeping (byte budget, ref counting) |
|
|
| 6 | `relay` | not started | Input dispatch to output queues (low-latency and completeness modes) |
|
|
| 7 | `ingest` | not started | MJPEG frame parser (two-pass EOI state machine, opaque stream → discrete frames) |
|
|
| 8 | `archive` | not started | Write frames to disk, control messages to JSON log |
|
|
|
|
---
|
|
|
|
## Dev CLI Drivers
|
|
|
|
Each module gets a corresponding CLI driver in `dev/cli/` that exercises its API and serves as both an integration check and a useful development tool.
|
|
|
|
| Driver | Exercises | Notes |
|
|
|---|---|---|
|
|
| `media_ctrl_cli` | `media_ctrl` | List media devices, show topology, configure pad formats |
|
|
| `v4l2_ctrl_cli` | `v4l2_ctrl` | List controls, get/set values — lightweight `v4l2-ctl` equivalent |
|
|
| `transport_cli` | `transport` | Send/receive framed messages, inspect headers |
|
|
|
|
---
|
|
|
|
## Deferred Decisions
|
|
|
|
These are open questions tracked in `architecture.md` that do not need to be resolved before module work begins:
|
|
|
|
- Graph representation format
|
|
- Connection establishment model (push vs pull)
|
|
- Completeness queue drop policy (oldest vs newest, per-output config)
|
|
- Stream ID remapping across relay hops
|
|
- Transport for relay edges (TCP / UDP / shared memory)
|
|
- Node discovery mechanism
|
|
- Hard vs soft byte budget limits
|