the-mews/SPEC.md

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.