lfg2025/archy
1
0
Fork 0
Code Issues 24 Pull Requests 1 Actions Packages Projects Releases 63 Wiki Activity
archy/.planning/ROADMAP.md

14 KiB
Raw Blame History

Roadmap: Archipelago — v1.8.0 Developer-Ready App Platform

Overview

Brownfield milestone starting from a green single-node production gate (5/5 on .228, 2026-06-23). The journey: make federation and mesh rock-solid (node removal, sync, messaging parity), fix the UI slowness users feel on every tab switch, prove the platform across the fleet (multinode pass), make the container lifecycle bulletproof (Quadlet default, self-healing, honest progress, no ghosts), flip manifest distribution from OTA disk files to the signed registry, harden manifest security enforcement to the full ADR-009 bar, ship the archy app developer CLI, and land the decentralized Nostr marketplace — ending at the north star: a third-party developer publishes an app via the signed/decentralized registry and a user installs it on their node.

Phases

Phase Numbering:

  • Integer phases (1, 2, 3): Planned milestone work

  • Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

  • Phase 1: Federation & Mesh Hardening - Deep review of federation/fleet + mesh code; node removal sticks, sync converges, mesh messaging behaves identically on demo and real nodes

  • Phase 2: UI Performance - Tab switches and secondary screens render fast; worst transitions measured and fixed

  • Phase 3: Multinode Verification Pass - Lifecycle gate green on a second node; cross-node federation/mesh/transport suites pass; federation removal sticks

  • Phase 4: Lifecycle Perfection & Quadlet Default - Quadlet backends default, failed-unit self-healing, flap observability, cascade gate, truthful progress

  • Phase 5: Registry-Distributed Manifests - Signed catalog carries full manifests; fleet flipped off OTA disk-file distribution

  • Phase 6: Manifest Security Enforcement - Validation matches ADR-009 mandates; generated security profiles actually applied

  • Phase 7: Developer Tooling CLI - archy app validate/render/local-install/lifecycle-test + developer guide

  • Phase 8: Decentralized Marketplace - DID-signed publish to Nostr relays, trust-tier discovery, verified third-party install end-to-end

Phase Details

Phase 1: Federation & Mesh Hardening

Goal: Federation and mesh are tight — a structured review of the fleet/federation and mesh code feeds fixes so node removal sticks, sync converges, and mesh messaging (including attachments) behaves identically everywhere it runs Depends on: Nothing (first phase) Requirements: FED-01, FED-02, FED-03, FED-04, FED-05, FED-06 Success Criteria (what must be TRUE):

  1. A structured code review of the federation/fleet area (core/archipelago/src/federation, node sync, FIPS/transport dial layer) and the mesh area (core/archipelago/src/mesh, mesh RPC surface) produces a findings list, and every finding is fixed or explicitly deferred with a reason
  2. Removing a federation node removes it everywhere — it disappears from all UI surfaces, tombstones propagate, and it never reappears after later sync cycles; a failed removal surfaces an error instead of silently no-opping
  3. Federation sync converges: after sync settles, fleet nodes agree on the node list and node status is fresh — stale entries, duplicates, and silent sync failures are gone, and sync errors are visible to the operator
  4. Mesh attachment send works identically on the demo and on real nodes — same modals, same transport decisions, same success — with the demo backend implementing the same RPC surface the UI calls (no "Method not found", no demo-only chooser modal)
  5. Channel-opening between nodes is first-class UI: a user can copy/share their node's Lightning URI; sees a list of trusted (federated) nodes by hostname to open a channel with in one flow; and can browse/request channels with public nodes — built with the existing design system (Teleport-to-body modals, house style), tested live on the :8100 dev preview against archi-dev, and fixed there before any deploy
  6. The invoice/payment "paid" success animation is on-brand: the tick's circle is the screensaver-style ring with the outer EQ-segment lines (reuse neode-ui/src/components/ScreensaverRing.vue, which already ships a compact overlay size), replacing the current burst in the payment success pane (neode-ui/src/components/SendBitcoinModal.vue) and matching wherever else the paid tick appears

Plans: 10 plans

Plans:

  • 01-01-PLAN.md — Serialize the federation node store and make removal stick (FED-01)
  • 01-02-PLAN.md — Demo mesh/federation RPC parity + automated parity harness (FED-04)
  • 01-03-PLAN.md — On-brand paid tick: ScreensaverRing badge variant on both success surfaces (FED-06)
  • 01-04-PLAN.md — Lightning identity: own-node URI + meshed Lightning peer discovery (FED-05)
  • 01-05-PLAN.md — Federation sync convergence and operator-visible sync errors (FED-02)
  • 01-06-PLAN.md — Lightning URI on the federation sync payload, sharing default decided (FED-05)
  • 01-07-PLAN.md — Channel-open request messaging over the mesh (FED-05)
  • 01-08-PLAN.md — Channel-open UX: own URI, trusted-node picker, meshed-peer requests (FED-05)
  • 01-09-PLAN.md — Structured federation/mesh review + dev-pair deploy (FED-03)
  • 01-10-PLAN.md — Consolidated phase verification on the dev pair (FED-01/02/05/06)

UI hint: yes

Phase 2: UI Performance

Goal: The UI feels fast — switching tabs and opening secondary screens (screens reached from a tab's main page) renders promptly instead of stalling on refetches and remounts Depends on: Nothing (frontend-focused; parallelizable with Phase 1) Requirements: PERF-01, PERF-02, PERF-03 Success Criteria (what must be TRUE):

  1. The slowest tab switches and secondary-screen opens are profiled and the causes named (remount storms, serial RPC waterfalls, uncached fetches) before fixes land
  2. Switching between main tabs renders the target view immediately from cached state, refreshing data in the background — no blank screens or long spinners on tabs already visited this session
  3. Secondary screens open without a blocking full reload; repeat visits are instant
  4. The fixes are verified on real node hardware (not just the dev box) — the sluggishness the user reported is gone on-device

Plans: 5/8 plans executed

Plans: Wave 1

  • 02-01-PLAN.md — Profile every D-09 surface on archi-dev-box and commit the findings doc (PERF-01)

Wave 2 (blocked on Wave 1 completion)

  • 02-02-PLAN.md — TRACER: KeepAlive host, hook reactivation, app-store tab, refresh indicator (PERF-02)
  • 02-03-PLAN.md — Secondary screens: per-item cache, parallel loads, purge on logout (PERF-03)

Wave 3 (blocked on Wave 2 completion)

  • 02-04-PLAN.md — Keep every main tab alive safely: lifecycle audit + full registration (PERF-02)

Wave 4 (blocked on Wave 3 completion)

  • 02-05-PLAN.md — Mesh: cache the six fetch groups, bound the D3 graph and Leaflet map (PERF-02)
  • 02-06-PLAN.md — Server and Home: cache the uncached fan-out, guarantee wallet freshness (PERF-02)
  • 02-07-PLAN.md — Chat/AIUI: stable embed URL + the two D-14 UX defaults (PERF-02)

Wave 5 (blocked on Wave 4 completion)

  • 02-08-PLAN.md — Dev-pair deploy, on-device re-measure, D-11 pass bar (PERF-01/02/03)

UI hint: yes

Phase 3: Multinode Verification Pass

Goal: The platform's lifecycle and federation guarantees are proven across the fleet, not just on .228 — the declared next exit criterion Depends on: Phase 1 (proves the federation/mesh fixes hold fleet-wide) Requirements: MNODE-01, MNODE-02, MNODE-03 Success Criteria (what must be TRUE):

  1. The 5× destructive lifecycle gate reports 0 failures on a second fleet node (archy-x250-beta), run on-node
  2. The cross-node smoke suite (federation pairing both directions, FIPS anchors, peer content browse) passes between two fleet nodes with every harness RPC time-bounded — a slow node produces a test failure, never an indefinite hang
  3. An operator who removes a federation peer never sees it reappear in the peer list after later sync cycles; a tombstone-write failure is surfaced as an error instead of silently swallowed
  4. The on-air mesh suite passes between two radio-equipped nodes over real RF

Plans: TBD

Phase 4: Lifecycle Perfection & Quadlet Default

Goal: An insanely-reliable container environment — every app installs, runs, restarts, uninstalls, and reinstalls cleanly with honest progress, no ghosts, and automatic recovery Depends on: Phase 3 (Quadlet default-flip is gated on the second-node gate reporting clean) Requirements: LIFE-01, LIFE-02, LIFE-03, LIFE-04, LIFE-05 Success Criteria (what must be TRUE):

  1. Restarting archipelago.service on a fleet node leaves every app container running — no SIGKILL-the-world, no multi-minute reconciler rebuild
  2. An app whose Quadlet unit enters failed state (and was not user-stopped) comes back automatically within a bounded window, with backoff on persistent failure — no operator intervention
  3. An operator can see per-app restart counts in status output, and a flapping app (>N restarts in M minutes) is flagged in logs instead of being invisible
  4. Uninstalling then reinstalling any gated app — including multi-container stacks like immich/btcpay — leaves no ghost My-Apps entries or orphan containers, preserves data per policy, and returns the app healthy, verified by the cascade gate tier
  5. Install and uninstall progress bars move monotonically from real backend progress events and always land on a terminal success/failure state — asserted in the gate, and the single-node gate stays green after all orchestrator changes

Plans: TBD UI hint: yes

Phase 5: Registry-Distributed Manifests

Goal: Manifests ship via the signed registry, not OTA disk files — bumping or adding an app becomes a signed catalog change Depends on: Phase 4 (fleet lifecycle stable under Quadlet default before changing the distribution channel) Requirements: REG-01, REG-02 Success Criteria (what must be TRUE):

  1. A fleet node installs and updates an image-only app from the full manifest embedded in the signed catalog, verified against the pinned release-root key, with no corresponding OTA disk file present (disk remains the fallback for build-source apps)
  2. A tampered or unsigned catalog manifest is rejected and the node falls back safely — it never installs from an unverified manifest
  3. Bumping an app version fleet-wide requires only regenerating, re-signing, and publishing the catalog — no binary OTA, no disk rsync — proven live on the fleet

Plans: TBD

Phase 6: Manifest Security Enforcement

Goal: A third-party manifest cannot weaken node security — declared security policy is fully validated and actually enforced at runtime Depends on: Phase 5 (enforcement guards the registry channel third-party manifests will arrive through) Requirements: SEC-01, SEC-02 Success Criteria (what must be TRUE):

  1. A manifest violating ADR-009 mandates (root user, unpinned latest tag, capability outside the allow-list, disabled seccomp) is rejected at validation with a clear error naming the violation
  2. Security overrides (readonly_root: false, extra capabilities) work only when explicitly listed in the manifest and leave an audit trail
  3. Generated AppArmor/seccomp profiles are applied to containers at creation and verifiably effective on a running app — not just generated and ignored
  4. The single-node lifecycle gate stays green with enforcement on — existing catalog apps all pass the strengthened validation (or carry documented overrides)

Plans: TBD

Phase 7: Developer Tooling CLI

Goal: A third-party developer can build, validate, and test an Archipelago app locally without reading platform internals Depends on: Phase 6 (CLI validation must mirror the final enforced rule set) Requirements: DEV-01, DEV-02, DEV-03, DEV-04 Success Criteria (what must be TRUE):

  1. A developer runs archy app validate on a manifest directory and gets the same pass/fail verdict — including security rules — that a node would enforce at install
  2. A developer runs archy app render and sees the exact Quadlet/podman configuration their manifest produces before ever touching a node
  3. A developer can install their app onto a dev node and run its lifecycle test (install/UI/stop/start/restart/uninstall) from the CLI
  4. A new developer following only the developer guide goes from an empty directory to a running app on a node — no tribal knowledge required

Plans: TBD

Phase 8: Decentralized Marketplace

Goal: The north star — third-party developers publish apps via the decentralized registry and users install them on their nodes Depends on: Phase 7 (publish rides the CLI; installs ride registry distribution from Phase 5 and enforcement from Phase 6) Requirements: MKT-01, MKT-02, MKT-03, MKT-04 Success Criteria (what must be TRUE):

  1. A third-party developer publishes a DID-signed app manifest to public Nostr relays (NIP-78, kind 30078) using the tooling
  2. A node discovers the published app from multiple relays and the app store UI shows its trust tier (Verified / Community / Unverified) per ADR-006 scoring
  3. The node verifies the manifest signature before installation; a tampered or invalid marketplace manifest cannot be installed
  4. A user installs the third-party marketplace-published app on their node and it runs healthy under the standard lifecycle guarantees — the user-chosen success metric, demonstrated end-to-end

Plans: TBD UI hint: yes

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 (Phases 1 and 2 are independent and may be worked in parallel.)

Phase Plans Complete Status Completed
1. Federation & Mesh Hardening 0/10 Planned -
2. UI Performance 5/8 In Progress
3. Multinode Verification Pass 0/TBD Not started -
4. Lifecycle Perfection & Quadlet Default 0/TBD Not started -
5. Registry-Distributed Manifests 0/TBD Not started -
6. Manifest Security Enforcement 0/TBD Not started -
7. Developer Tooling CLI 0/TBD Not started -
8. Decentralized Marketplace 0/TBD Not started -