# 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` | done | Error types, base definitions — no dependencies |
| 2 | `media_ctrl` | done | Media Controller API — device and topology enumeration, pad format config |
| 3 | `v4l2_ctrl` | done | V4L2 controls — enumerate, get, set camera parameters |
| 4 | `serial` | not started | `put`/`get` primitives for little-endian binary serialization into byte buffers |
| 5 | `transport` | not started | Encapsulated transport — frame header, TCP stream abstraction, single-write send |
| 6 | `protocol` | not started | Typed `write_*`/`read_*` functions for all message types; builds on serial + transport |
| 7 | `frame_alloc` | not started | Per-frame allocation with bookkeeping (byte budget, ref counting) |
| 8 | `relay` | not started | Input dispatch to output queues (low-latency and completeness modes) |
| 9 | `ingest` | not started | MJPEG frame parser (two-pass EOI state machine, opaque stream → discrete frames) |
| 10 | `archive` | not started | Write frames to disk, control messages to binary 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