[P0] Specify architecture, component boundaries, and data flow #3

New issue

Closed

opened 2026-07-17 23:58:05 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-17 23:58:05 +00:00

(Migrated from github.com)

Goal

Define the implementation architecture before writing feature code.

Required components

Capture controller and hard capture gate.
Capture backend strategies.
Metadata-source strategies.
Policy resolver and filtering pipeline.
OCR and secret-redaction pipeline.
Encryption and key-management strategies.
Encrypted storage and indexing.
Local/remote model-provider strategies and routing policies.
Retrieval, summarization, and provenance.
CLI, local API, and visible status surface.

Actor and transport decisions

Python actors use Pykka, initially through a bounded set of ThreadingActor components.
ZeroMQ/PyZMQ is the actor data-plane and local IPC transport.
Raw capture pipeline data uses inproc:// only.
Owner-only local control/query IPC uses ipc://.
RabbitMQ, Kafka, persistent message queues, and filesystem queue fallbacks are prohibited.
Pykka inboxes are limited to low-volume control and supervision; bulk pipeline payloads use bounded ZeroMQ edges.
ZeroMQ high-water marks, application credits, deadlines, finite retries, and zero-linger teardown must be explicit and tested.

Design requirements

Strategy interfaces must separate policy from concrete implementations.
No provider may bypass policy, redaction, or encryption stages.
Cancellation must propagate through all in-flight work when capture is turned off.
Components communicate through typed, versioned messages/events.
Every actor and transport edge must have bounded work and explicit overload behavior.
Architecture must support Xorg first and Wayland later without changing the core pipeline.

Deliverables

docs/architecture.md
Component and sequence diagrams.
Initial ADRs covering language/runtime, actors/transport, storage, encryption, and plugin boundaries.

Acceptance criteria

Every component has a narrow responsibility and explicit interface.
Pykka actor ownership and ZeroMQ transport responsibilities are unambiguous.
Data lifecycle is documented from pixels in memory through deletion.
Security-critical ordering is unambiguous: capture → in-memory analysis/redaction → encryption → persistence.
No authoritative document selects RabbitMQ or AnyIO memory streams as the Local Recall actor bus.

Depends on

## Goal Define the implementation architecture before writing feature code. ## Required components - Capture controller and hard capture gate. - Capture backend strategies. - Metadata-source strategies. - Policy resolver and filtering pipeline. - OCR and secret-redaction pipeline. - Encryption and key-management strategies. - Encrypted storage and indexing. - Local/remote model-provider strategies and routing policies. - Retrieval, summarization, and provenance. - CLI, local API, and visible status surface. ## Actor and transport decisions - Python actors use Pykka, initially through a bounded set of `ThreadingActor` components. - ZeroMQ/PyZMQ is the actor data-plane and local IPC transport. - Raw capture pipeline data uses `inproc://` only. - Owner-only local control/query IPC uses `ipc://`. - RabbitMQ, Kafka, persistent message queues, and filesystem queue fallbacks are prohibited. - Pykka inboxes are limited to low-volume control and supervision; bulk pipeline payloads use bounded ZeroMQ edges. - ZeroMQ high-water marks, application credits, deadlines, finite retries, and zero-linger teardown must be explicit and tested. ## Design requirements - Strategy interfaces must separate policy from concrete implementations. - No provider may bypass policy, redaction, or encryption stages. - Cancellation must propagate through all in-flight work when capture is turned off. - Components communicate through typed, versioned messages/events. - Every actor and transport edge must have bounded work and explicit overload behavior. - Architecture must support Xorg first and Wayland later without changing the core pipeline. ## Deliverables - `docs/architecture.md` - Component and sequence diagrams. - Initial ADRs covering language/runtime, actors/transport, storage, encryption, and plugin boundaries. ## Acceptance criteria - Every component has a narrow responsibility and explicit interface. - Pykka actor ownership and ZeroMQ transport responsibilities are unambiguous. - Data lifecycle is documented from pixels in memory through deletion. - Security-critical ordering is unambiguous: capture → in-memory analysis/redaction → encryption → persistence. - No authoritative document selects RabbitMQ or AnyIO memory streams as the Local Recall actor bus. ## Depends on - #1 - #2