58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
|
# 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.
|