title: Yuu architecture decisions status: canonical audience:
- humans
- AI agents last_reviewed: 2026-08-22 ---
Architecture decisions
This page records durable decisions and prevents implementation plans from
quietly contradicting each other. Accepted decisions guide new work.
Proposed decisions may change after a prototype produces evidence.
| ID | Status | Decision |
|---|---|---|
| YUU-001 | Accepted | Keep a retained entity scene with immediate Raylib drawing |
| YUU-002 | Accepted | Derive default AI context from the camera-visible world |
| YUU-003 | Accepted | Use stable entity IDs for external resources and persisted relationships |
| YUU-004 | Accepted | Keep semantic membership separate from geometry |
| YUU-005 | Partially accepted | Make SQLite the local workspace source of truth |
| YUU-006 | Accepted | Use SQLite R-tree as a lookup index, not as the entity store |
| YUU-007 | Proposed | Hydrate entities through type-specific adapters |
| YUU-008 | Proposed | Keep .zmap as snapshot compatibility during migration |
| YUU-009 | Proposed | Upload validated SQLite backup copies, never live database files |
| YUU-010 | Proposed | Preserve a backend-neutral store contract for PostgreSQL/PostGIS |
YUU-001: retained scene, immediate drawing
Canvas_Scene owns durable runtime interaction state while each frame rebuilds
draw commands. This gives components stable identity and animation without
introducing a second retained UI framework.
YUU-002: camera-visible context by default
The camera is the user's active attention boundary. Visible entities are the default candidates for orchestration context. Explicit references, selected regions, and agent-requested retrieval may add off-screen entities.
Visibility is a candidate policy, not permission to concatenate unlimited payloads. The context planner applies semantic and token budgets.
YUU-003: stable IDs
Process-local array indexes and numeric handles are not durable identities. Persisted relationships use an opaque stable entity ID or typed domain ID. Runtime rendering may map that identity to a compact local handle.
YUU-004: semantics are not geometry
Moving a card near a conversation must not silently rewrite ownership. Geometry powers viewport lookup and proximity suggestions. Explicit region and relationship tables power conversation membership and agent routing.
YUU-005: SQLite local source of truth
SQLite is favored for personal, offline-capable workspaces because it provides transactions, indexes, schema migration, portability, and one-file backup artifacts. The database contains workspace/domain state, not runtime caches or credentials.
The catalog, bounds, transactional movement update, overlap query, and camera
checkpoint slice is implemented and tested. This remains partially accepted
until the application starts from the database, migrates existing .zmap
workspaces, and demonstrates recovery behavior.
YUU-006: R-tree is only an index
The R-tree stores integer row IDs and world bounds. Entity type, title, summary, relationships, payload descriptors, and stable IDs live in normal tables. This allows bounds to change frequently without coupling all metadata to a spatial data structure.
A fixed grid and quadtree are not selected as the durable catalog. They may still be useful as transient in-memory acceleration if measurements justify them.
The initial canvas_store_sqlite implementation validates this shape with a
normal entity table joined to an R-tree containing only entity_pk and bounds.
YUU-007: entity-specific hydration
Primitive shapes, conversations, images, browsers, and generated components do not have the same cost or loading mechanism. A hydrator registry owns summary, full payload, active resource, release, and context behavior per type.
The database row describes how to hydrate; it does not directly instantiate CEF, textures, SDK sessions, or network requests.
YUU-008: .zmap migration compatibility
The explicit binary snapshot remains supported while SQLite becomes authoritative. It is a validated import/export and test format, not the final viewport query mechanism. Removal requires demonstrated database parity and a migration path for existing snapshots.
YUU-009: consistent database exports
Object storage receives a standalone copy produced through SQLite's backup API, followed by integrity and checksum validation. Uploading a live main database without its WAL can produce incomplete state and is forbidden.
Initial uploads are immutable single-writer revisions. Conflict-free multi-writer synchronization is explicitly deferred.
YUU-010: backend-neutral storage contract
Canvas rendering and interaction depend on workspace operations, not SQL: viewport query, payload load, mutation persistence, camera checkpoint, and export. SQLite implements local workspaces. PostgreSQL/PostGIS may implement a hosted backend later using GiST spatial indexes without changing entity or camera behavior.
Updating decisions
When implementation evidence changes a decision:
- Update its status and rationale here.
- Update the detailed owning wiki page.
- Update affected interfaces and tests in the same change.
- Preserve migration or compatibility implications.