From 7bb8b904697caff4dc8cdec18ae7371081ee3ef2 Mon Sep 17 00:00:00 2001 From: Aly Raffauf Date: Sun, 2 Aug 2026 21:23:36 -0400 Subject: [PATCH] document application architecture boundaries --- ARCHITECTURE.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..0c8ce93 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,34 @@ +# Appa architecture + +Appa is one binary, but it is deliberately layered so a future library or GUI can reuse its synchronization behavior without importing CLI code. + +```text +cli and service commands + | + v +application (AppaService use cases and sync orchestration) + | | | + v v v +domain storage Iroh transport + \ + local filesystem +``` + +## Rules + +- `cli` parses input, confirms destructive actions, and renders results. It does not contain sync policy. +- `app` is the only coordinator. It owns use cases such as joining a folder, running watchers, and synchronizing a peer. +- `domain` contains durable data structures and deterministic reconciliation rules. It must not perform I/O. +- `storage` owns Appa's local state and SQLite access. It does not make network requests. +- `iroh` owns endpoint lifecycle, authenticated control streams, blob transfers, and LAN route discovery. It does not know about SQLite or CLI concepts. +- `filesystem` owns safe local-path operations and change notifications. It does not make reconciliation decisions. + +## Application modules + +- `app.rs` is the public `AppaService` facade and small local use cases. +- `app/run.rs` owns watcher lifecycle, interruption, and retry scheduling. +- `app/sync.rs` owns peer discovery, folder hosting, and synchronization passes. +- `app/manifest.rs` turns local filesystem state into a manifest. +- `app/materialize.rs` applies remote manifests, writes blobs atomically, and restores revisions. + +Keep modules focused on one workflow. Prefer an explicit data type at a boundary over reaching across layers for an implementation detail. -- 2.51.2