init

SPEC.md

@@ -0,0 +1,58 @@
+# xfay
+
+## Project layout
+
+- `app/` — Flutter application (main codebase)
+- `mews-spec/` — Mews Profile definition files
+- `nix-android-sdk/` — Nix flake providing the Android SDK for devbox
+
+Flutter version: `3.41.9-sdk-links` (keep in sync with devbox.json).
+
+---
+
+# Product spec
+
+## What it is
+
+A Flutter browser/client for Mews Pages (see mews-spec).
+
+## Approach
+
+Local-first: all data is stored locally in a Drift database. Network operations (Nostr publishing, image upload) are secondary and never block local functionality.
+
+# Architecture directives
+
+Keep files small and focused.
+
+## Layer separation
+
+- `presentation/` — rendering, input, gestures, navigation.
+- `application/actors/` — isolate-backed actors for CPU/IO work (image processing, export, file I/O).
+- `application/controllers/` — plain coordinators that own signals and handle synchronous UI commands.
+- `database/` — Drift tables, DAOs, queries.
+- Signals expose UI-consumable state derived from the application layer.
+- No business logic in widgets.
+
+## State management — Signals
+
+- Use the `signals` package for reactive UI state.
+- Widgets observe signals and dispatch actions to the application layer.
+- Derived UI state should be computed, not manually synchronized.
+- Do not duplicate state across multiple signals.
+
+## Business logic — Actor Model (`actors` package)
+
+Use the `actors` package only where Dart Isolate isolation is genuinely useful: CPU-heavy work, blocking I/O, or tasks that must not block the UI thread. Do not use it for pure UI state or simple synchronous coordination.
+
+**Rules for all actors and coordinators:**
+- Model interactions as explicit sealed command types.
+- No business logic in widgets — dispatch commands to the application layer.
+- Keep classes small and focused; avoid large catch-all actors.
+- Pass references explicitly when communication is needed.
+
+**Isolate constraint:** The `actors` package runs handlers in separate Dart Isolates. Handlers cannot directly update signals on the main isolate. Isolate-backed actors must return results via message passing; the calling code applies results to signals.
+
+## Persistence — Drift
+
+- Use `drift` for all tables, DAOs, and queries.
+- Keep database definitions in `database/` separate from UI code.