Documentation Index
Fjarr is developed documentation-first: specs and ADRs land before the code that implements them (docs/13). This index is the front door — read top to bottom for the full picture, or jump by concern.
Status meaning: draft (being written, expect churn) → review (complete,
awaiting scrutiny) → stable (normative; changing it requires an ADR or PR
with rationale).
| # | Document | Concern | Status |
|---|---|---|---|
| 00 | Vision | Why Fjarr exists, for whom, and what it is not | review |
| 01 | Glossary | Shared vocabulary across all three codebases | review |
| 02 | Architecture | Three-tier library model, planes, topologies | review |
| 03 | Product strategy | The living SaaS business plan | review |
| 04 | Supported platforms | OS, GPU, browser, network matrices | review |
| 05 | Extension model | The capability/plugin API — the centerpiece | review |
| 06 | Capabilities | Catalog: camera, desktop, telemetry, files, terminal, observability, OTA | review |
| 07 | Desktop backends | X11/Wayland × XTest/libei/uinput evaluation plan | stable |
| 08 | Protocol | Normative wire spec: signaling + DataChannels | review |
| 09 | Interfaces | The three embedding APIs + backend contract | review |
| 10 | Security | Threat model, identity, tokens, TURN, privileges | review |
| 11 | Prior art | Lessons mined from five prior in-house projects (anonymized) | review |
| 12 | Development environment | Devcontainer, compose, doctor, troubleshooting | review |
| 13 | Development workflow | Doc-driven process, ADRs, definition of done | review |
| 14 | Dependencies | Every dependency: version, license, ships-or-dev | review |
| 15 | Testing strategy | Test pyramid, fault injection, latency harness | review |
| 16 | Performance budgets | Latency/bitrate/CPU targets and degradation | review |
| 17 | Roadmap | Milestones M0–M8 with entry/exit gates | review |
| 18 | Open questions | Live list of undecided items | living |
| 19 | Website & publishing | How docs + landing page ship | review |
| 20 | Agentic development | AI agents as first-class contributors | review |
| 21 | Web client architecture | @fjarr/core + @fjarr/react: sessions, subscriptions, publishing, demand-driven media | review |
| 22 | Remote desktop client | Browser-side fjarr.desktop: input pipeline, focus, cursor, latency, clipboard | review |
| 23 | Agent core architecture | libfjarr core: threading, session state machine, media plane, DC router, SessionContext, supervision, testing | review |
| 24 | Pipeline introspection | Live, visual and machine-readable GStreamer pipeline graphs — for developers, customers and AI agents | review |
| 25 | Browser lab | CDP-driven Chromium in the stack: e2e, traffic introspection, network emulation, profiling — for people and agents | review |
| 26 | Robot install & drivers | One-line install; the driver catalog, setup, drivers and --check; only the drivers a use case needs | draft |
| 27 | Network tunnel | fjarr.net: a session-scoped IP link to one robot — ssh, scp, UDP bridges and ROS 2 tooling; why it is a link and not a VPN | draft |
| 28 | What you can run over the tunnel | Ideas for fjarr.net: shells, desktops, files, debuggers, ROS, CAN, USB/IP, monitoring — what is verified, what fits, and the safety notes | review |
| 29 | How-tos over the tunnel | Step-by-step recipes for docs/28’s ideas: a few commands each, robot side and your side, and the usual pitfall | review |
| 30 | Continuous integration | How CI is laid out and kept fast: the job graph, which changes run what, CI images by content hash, caches as a budget, build once and reuse; rules for adding to it | review |
| 31 | The hosted demo | The demo stack on a public server behind Cloudflare: names, TLS (Cloudflare to Caddy), coturn, firewall, secrets, deploying and operating it | draft |
| 32 | Fleet OTA | fjarr.ota: signed releases for the whole robot (image, apps, config, peripherals), readiness and prepare, run logs, budgeted HTTPS chunks, staged campaigns, recipes for Yocto/NixOS/Ubuntu | draft |
Architecture decision records
Section titled “Architecture decision records”Decisions live in docs/adr/ — one file per decision, immutable once accepted (superseded, never edited). Start with the ADR process and the template.
Reviews
Section titled “Reviews”Gate artifacts and retrospective code reviews live in docs/reviews/:
the M1 extension-API fit review, the
slice-2 web core + React review, the
slice-3 planning review, the
slice-3a browser lab review, the
slice-3b agent core review, the
slice-3c introspection + memory ladder review,
the slice-4 camera review, the
slice-5a blob frames + introspect review
the slice-5b served viewer + agent image review
the slice-6a repair + rate control review
the slice-6b passthrough review
the M1 gate review
the slice-4.5a network tunnel review
the slice-4.5b gates review
the slice-4.5c ssh-and-scp review
the slice-4.5d ROS 2 review
the slice-4.5e operator client review
the slice-4.5f discovery and login review
the M4.5 gate review
and the M3 gate review.
Reading paths
Section titled “Reading paths”- “I’m a robot company evaluating Fjarr” → 00 → 02 → 06 → 09 → 04
- “I want to debug a robot in the field” → 27 → 26 → 10
- “I’m implementing a milestone” → 17 → the specs it gates on → 13
- “I’m writing a capability plugin” → 05 → 08 → 09
- “I’m reviewing security” → 10 → 08 → 09 → 14