v3.1

TO-FIX

As is in the image, besides user setting an title for the note, it ramains untitled. (tested in dreamflow env.) Search, in filter, does not search for folders

BUTTON 1

order from A to Z, heavy files to low, from date of creation, and vice-versa.

BUTTON 2 (EYE BUTTON)

hide files from view or hide folders from view

FUNCTIONALITY

pin folders or files

---

Memoria — Local‑First Notes & Files (Legal‑Ready)

This repository is governed by an immutable architectural contract (UML) and a strict execution process.

1) UML INPUT CONTRACT (IMMUTABLE)

UML BLOCK (VERBATIM)

@startuml
!theme flat
title Notes & Files - Global, Local-First & Legal Ready

package "Presentation (Flutter)" {
  [Screens] <<UI>>
  [Widgets] <<Adaptive UI>> 
  [Riverpod Providers] <<State>>
  
  note top of [Widgets]
    **i18n & UX Compliance:**
    - Flexible/FittedBox (No Overflows)
    - LTR/RTL Support
    - Regional Formats (intl)
  end note
}

package "Domain (Logic)" {
  [Note/File Models]
  [Repository Interfaces]
  [Legal Context] <<Contract & Consent>>
  
  note bottom of [Legal Context]
    **User Terms (Local Focus):**
    - Responsibility of Device Safety
    - No Cloud Backup (Explicit)
    - Export & Wipe (Right to be Forgotten)
  end note
}

package "Data (Infrastructure)" {
  [SQLite Implementation] <<Secure DB>>
  [File System Service] <<App Sandbox>>
  
  package "Security & Perf" {
    [Isolate Worker] <<flutter_isolate>>
    [Encryption Engine] <<SQLCipher / AES>>
  }
}

' Relacionamentos
[Screens] --> [Riverpod Providers]
[Riverpod Providers] --> [Repository Interfaces]
[Repository Interfaces] <|.. [SQLite Implementation]

' Segurança local para conformidade
[SQLite Implementation] --> [Encryption Engine] : Proteção At-Rest
[Isolate Worker] --> [Encryption Engine] : Encrypt heavy files

' Manejo de arquivos no sandbox do sistema
[SQLite Implementation] --> [File System Service] : Reference paths
[File System Service] <.. [Isolate Worker] : Process Large Files (Off-thread)

note right of [File System Service]
  **App Sandbox:**
  Usa caminhos privados do OS 
  para isolar dados de outros apps.
end note

note right of [Isolate Worker]
  **Performance & UX:**
  - Thumbnail generation
  - Compression
  - Transparent Encrypt/Decrypt
end note

@enduml 

2) Translation of UML → Strict Execution Phases (with Checklists)

Phase 0 — Specification & Deterministic Scaffolding (THIS CHECKPOINT)

Goal: Establish contract, folder map, dependency lock, typed-file rules, and isolate strategy. No feature implementation.

Checklist (must all be true):

• README.md contains UML block verbatim (done by this document).
• Folder structure is mapped 1:1 to UML components (see §3).
• pubspec.yaml dependency list is locked and validated (see §4).
• Isolate strategy is defined and respects platform constraints (see §6).
• Typed-file handling is specified in Domain (see §2.1).
• Execution rules + checkpoint criteria are explicit (see §7).

Checkpoint validation criteria (Phase 0 is valid only if):

• Project compiles successfully.
• No runtime crash on startup.
• No architectural boundary violations introduced.
• No incomplete implementations exist (docs-only changes are OK).

---

Phase 1 — Domain Layer (Pure Dart)

Goal: Define models, repository interfaces, legal context, and typed-file primitives as pure Dart.

Checklist:

• Create Note/File models with explicit serialization.
• Introduce explicit file type handling (see §2.1):
  • Supported types and extensibility rules are encoded in Domain.
  • Repositories and filesystem abstractions operate on typed files (not raw extensions).
• Define repository interfaces (no Flutter imports, no SQLite imports).
• Define Legal Context primitives:
  • Terms text (local focus)
  • Consent acceptance record
  • Export + wipe policy declarations

Validation:

• Analyzer passes.
• Domain layer has zero Flutter/persistence dependencies.

---

Phase 2 — Data Layer (Infrastructure, Encapsulated)

Goal: Implement SQLite + sandbox file system behind domain interfaces.

Checklist:

• SQLite implementation class implements repository interfaces.
• File System Service provides only sandboxed paths + file operations.
• No SQLite/file system details leak outside data layer.
• Typed-file handling is preserved end-to-end:
  • Storage maps Domain FileType ↔ persistence representation safely.

Validation:

• All database operations are callable via repository interfaces only.

---

Phase 3 — Security & Performance Layer (Isolate Worker + Encryption)

Goal: Ensure at-rest protection and off-thread compute/file work (not database work) without violating platform constraints.

Checklist:

• Encryption Engine (AES building blocks) implemented and used by storage.
• Isolate Worker (flutter_isolate / compute) executes ONLY:
  • Encryption/Decryption (byte arrays / streams)
  • Compression/Decompression (API surface only; wiring comes with feature needs)
  • Thumbnail generation (API surface only; wiring comes with feature needs)
  • Heavy file processing (e.g., hashing, chunking, parsing large payloads)
• SQLite must NOT be executed inside isolates.
• File I/O may be offloaded optionally (only when safe/beneficial), but is not mandatory.

Validation:

• UI thread has no blocking calls to heavy compute (large encrypt/decrypt is offloaded via compute).
• DB access remains correct and stable across Android/iOS/Web constraints.

---

Phase 4 — Presentation Layer (Flutter UI + Riverpod)

Goal: Build screens/widgets with i18n compliance and Riverpod state.

Checklist:

• Screens depend on Riverpod providers only.
• Providers depend on repository interfaces only.
• Widgets are overflow-safe:
  • Flexible / Expanded where needed
  • FittedBox/ellipsis for constrained text
• LTR/RTL supported.
• Regional formats use intl.

Validation:

• No overflow errors in common layouts.

---

Phase 5 — Legal UX (Local Focus) + Export/Wipe

Goal: Make app “legal ready” for local-only storage.

Checklist:

• Show local-only disclaimer, no cloud backup.
• Consent capture stored locally.
• Export feature (structured + file references).
• Wipe feature (complete deletion).

Validation:

• Export produces complete, readable data.
• Wipe leaves no residual app data.

---

§2.1 Domain Extension — Typed File Handling (Explicit, Extensible)

Hard rules:

• Domain must not treat files as “just paths with extensions”.
• File type handling must be explicit, validated, and future-extensible.

Required Domain primitives (to be implemented in Phase 1):

• FileType (enum or sealed type): represents supported types.
• FileTypeResolver: maps filename/extension/MIME hints → FileType (strict).
• TypedFileRef (value object): { id, fileName, fileType, bytes?, size, checksum?, createdAt, updatedAt } (exact fields subject to later refinement).

Supported types (initial set; extendable):

• Markdown: .md
• PDF: .pdf
• (Optional in later phases) Images: .png, .jpg, .jpeg (primarily for thumbnails)

Repository + filesystem abstractions impact:

• Repository interfaces must accept/return typed references (FileType), never raw extension strings.
• File system service must be able to:
  • validate type at boundaries
  • enforce safe naming
  • support future “type handlers” without interface breakage

3) Folder Structure (Mapped 1:1 to UML)

Target structure (to be created in later phases):

lib/
  presentation/
    screens/                # [Screens]
    widgets/                # [Widgets]
    providers/              # [Riverpod Providers]

  domain/
    models/                 # [Note/File Models] (includes FileType/TypedFileRef)
    repositories/           # [Repository Interfaces]
    legal/                  # [Legal Context]

  data/
    sqlite/                 # [SQLite Implementation]
    filesystem/             # [File System Service]

  perf_security/
    isolate/                # [Isolate Worker]
    crypto/                 # [Encryption Engine]

Boundary rules:

• presentation/* may import domain/* and presentation/* only.
• domain/* imports Dart only (no Flutter, no plugins).
• data/* may import domain/* + plugin packages.
• perf_security/* hosts isolate and crypto utilities; only accessed via data layer or explicit adapters.

4) Final Dependency List (pubspec.yaml requirements)

Locked dependencies required by UML (Phase 0):

• State: flutter_riverpod
• Navigation (already in repo): go_router
• i18n/formatting: intl
• App sandbox paths: path_provider, path
• File picking (cross-platform): file_picker
• SQLite access (implementation detail): sqlite3, sqlite3_flutter_libs
• Isolates: flutter_isolate
• Encryption (AES building blocks): cryptography
• Imaging for thumbnails (off-thread): image

Notes:

• No backend is connected; all storage is local-first by contract.

5) Execution Rules (Non-Negotiable)

• Atomic Layer Isolation:

  • Data layer is fully encapsulated; no SQLite/file APIs in UI or domain.
  • Domain is pure Dart.

• Isolate Constraints (Strict):

  • SQLite must NOT be executed in isolates.
  • Isolates are reserved for: encryption/decryption, compression, thumbnailing, and heavy file processing.
  • File I/O offload is optional, not mandatory.
  • UI thread blocking due to heavy compute is a critical failure condition.

• Anti-Patch Rule:

  • If compilation breaks or architecture is violated, do not apply incremental patches.
  • Discard affected files and regenerate cleanly from this README + UML.

• Complete Files Only:

  • No partial snippets for implementation phases; generate full files.

• Dependency Lock:

  • pubspec.yaml must remain consistent with this document.

6) Isolate Strategy (Heavy Operations)

Hard rule: UI thread blocking due to heavy compute is a critical failure condition.

Allowed isolate workload (ONLY):

• encryption/decryption
• compression/decompression
• thumbnail generation
• heavy file processing (hashing, chunked transforms, large payload parsing)

Explicit prohibitions:

• SQLite must NOT run in isolates (no open/query/write/transactions in isolate).

Optionality:

• File I/O may be performed off-thread only when it is safe and beneficial on the target platform/runtime; it is not a requirement.

UI layer will only:

• trigger async provider actions
• display progress/error states
• never do heavy compute directly

7) Checkpoint Validation Criteria

A checkpoint is valid ONLY if:

• Project compiles successfully (dart analyze clean).
• No runtime crash on startup.
• UML boundaries are strictly respected.
• No incomplete implementations exist.

If any criterion fails:

• checkpoint is invalid
• progression is blocked
• regenerate affected files cleanly