Elonn Docs Platform Documentation

Current State

Status: Implementation reality. This page is not the active plan and is not the target architecture.

This page records what the platform currently does. When older progress notes, service READMEs, or migration history disagree with this page, treat this page as the current implementation state and use the service code as the final source of implementation truth. When this page disagrees with PLAN.md or the Runtime Contract about future direction, treat this page as migration evidence only.

Last reviewed: 2026-06-25. Cardboard runtime state added same date.

Current architecture

The current runtime architecture is:

Service truth -> Surface runtime state -> World composition -> Runtime rendering
  • Services own domain truth and actions.
  • Surface persists stack, surface, focus, placement, and surface session state.
  • World composes services plus Surface state into platform-neutral runtime contract v2 primitives.
  • Runtimes (web, android, ipad, cardboard) consume the world contract and render the experience. Additional runtimes will follow the same contract.

Social surface flow

Social data becomes visible through this path:

api.elonn.local
  -> runtime
  -> world.elonn.local/world/session
  -> social.elonn.local/social/objects
  -> surface.elonn.local/runtime
  -> runtime SurfaceStack

Detailed flow:

  1. The member signs in through elonn.local; api.elonn.local issues the elonn_api_token credential.
  2. The runtime validates the token through API and requests world.elonn.local/world/session.
  3. World fetches member directory data from API, field data from Maps, Social objects and Social DMs from Social, open message threads from Messages, and stack state from Surface using trusted member context.
  4. World returns layout, services, and surface_runtime.
  5. The runtime renders the primary carry SurfaceStack from surface_runtime.
  6. Service-backed surfaces fetch World panel URLs such as /world/panels/social, /world/panels/social?view=events, /world/panels/messages, or /world/panels/time.
  7. World relays to Social, Messages, and Time runtime payload endpoints, rewrites actions back through /world/..., and returns JSON for the runtime to render into durable center-stack surfaces with right-rail service navigation.
  8. Mutations go runtime → World → Social. Social remains authoritative and may push event mirrors to Time.

Runtime layout

All runtimes implement five explicit regions:

--------------------------------------------------+
|                    Upper Dock                    |
+---------+----------------------------+-----------+
| Left    |       Surface Stack        | Right     |
| Rail    |       Primary Workspace    | Inspector |
+---------+----------------------------+-----------+
|                    Lower Dock                    |
+--------------------------------------------------+
  • Upper dock is reserved for future global runtime signals and should stay minimal.
  • Lower dock is a service launcher and locator. Selecting a service focuses an existing surface when possible and later creates a new surface when creation is implemented. The dock does not own or manage surfaces.
  • Center stack is the primary durable SurfaceStack. It owns focus switching, neighboring surface visibility, drag threshold, momentum, snap behavior, reorder, detach/share hooks, and persistence through Surface.
  • Left rail is a stable runtime/member stack: profile, account, settings, docs, status, diagnostics, connected services, and help.
  • Right rail is a service navigation stack for the focused center surface in normal mode. When Field is selected from the lower dock, the right rail becomes a vertical flip stack of Field control cards starting with Places. It should not become global navigation or a duplicate lower dock.

Keep the siderails as stacks. The important distinction is content: the left rail is stable runtime/user panels, and the right rail is service navigation in normal mode or the Field control stack when the lower dock switches to Field.

Ownership map

Service Current responsibility
api.elonn.local Identity, auth tokens, member directory
social.elonn.local Profiles, conversations, replies, communities, relationships, derived circles, presence, social events, activity, notifications, media, Social DMs
messages.elonn.local Open one-to-one member Messages outside Social context
surface.elonn.local Durable surfaces, stacks, stack items, focus, placement, surface sessions
world.elonn.local Runtime contract composition, service aggregation, route relay/rewrite, carry and field composition
web.elonn.local Browser runtime — SurfaceStack rendering, docks, rails, field controls, field layer
android.elonn.app Android runtime — native SurfaceStack, transient loading bridge, field layer via ARCore
ipad.elonn iPad runtime — SurfaceStack, transient loading bridge, field layer via device heading
cardboard.elonn.app Google Cardboard runtime — stereoscopic CameraX passthrough, World-driven shell surfaces, Field markers, Bluetooth mouse pointer
maps.elonn.local Canonical field and POI dataset
time.elonn.local Calendars and time-owned calendar events; mirrors Social events when Social syncs them
find.elonn.local Discovery and findings

Current development position

Implemented:

  • Social has persisted objects for conversations, communities, social events, presence, activity, notifications, media, and discovery/circle traversal. Circle traversal is currently derived from private community co-membership.
  • Social owns Social DMs. Messages owns open one-to-one member Messages outside Social context.
  • Surface runtime persistence and runtime APIs exist.
  • World composes surface_runtime into /world/session.
  • Web, Android, and iPad render the carry SurfaceStack, rail regions, dock launcher, and transient notice panels from the world contract.
  • Cardboard now consumes the World runtime v2 contract as a standalone Google Cardboard runtime. It renders CameraX passthrough into left/right eye viewports, uses Cardboard SDK head tracking and device heading for Field projection, builds center/left/right stack surfaces plus a lower dock from World data, parses full session metadata, service descriptors, action ids/labels, Field object presentation, actions, and attribution, and supports a Bluetooth mouse pointer for dock, panel navigation, Field controls, back to carry, and stack flipping. It preserves the lower dock across partial World responses as the recovery path.
  • Web field layer renders live Maps-authored nearby places over a synthetic horizon panorama.
  • Android field layer renders live Maps-authored nearby places over the camera using ARCore and screen-rotation-aware sensor remapping.
  • iPad field layer renders live Maps-authored nearby places using device heading.
  • Social event changes can sync calendar mirrors to Time.
  • Time stores canonical mixed VEVENT/VTODO objects shared by native APIs and CalDAV. Its Web workspace renders day, week, month, agenda, and task views with appointment/task and calendar CRUD, recurrence, reminders, timezone handling, and Social mirror edit authority enforced through Time, DAV, and World.
  • External CalDAV uses services.elonn.com/caldav/, backed by Time through a shared cPanel document root. Members authenticate with their normal Elonn email or username and account password. The Account page publishes static connection settings; no device-specific DAV credentials exist. Production DNS discovery and the well-known redirect are active. Thunderbird and Web both create, modify, and persist appointments and tasks against the canonical Time store.
  • World handles credentialed browser preflight for runtime mutations, including Time appointment/task PATCH requests. This fixed Web task saves that previously failed at the browser CORS boundary.
  • Runtime contract and behavioral specification are documented in Runtime Contract. The target runtime contract is now the canonical elonn.runtime.dataset v1 dataset from GET /world/runtime; /world/session remains a compatibility shell for existing runtimes. World composes /world/runtime from service object sources and no-surface composed state for Field, Social, Messages, Find, Time, and Maps-backed field objects. The runtime dataset publishes objects, contexts, actions, workspace, field, findings, fallbacks, and source status without surface, panel, rail, stack, or dock terminology. Web has the first migration slice toward a thin runtime adapter: it loads a dedicated runtime dataset parser, declares elonn.runtime.dataset v1 capabilities when fetching /world/runtime, and resolves Messages objects, contexts, action commands, and Field scene objects from the parsed canonical dataset. Live nearby Field refreshes now call /world/runtime with the geographic query and project field.objects joined against canonical runtime objects. Field controls now come from field.controls in the canonical dataset, including radius selection and the complete standard place category filters. The current Web DOM renderer still maps runtime objects into existing containers, and Web still uses /world/session for most shell rendering. A subsequent attempt to drive the existing Web workspace and lower dock directly from /world/runtime was reverted after breaking visible Web behavior. Web remains compatibility implementation and migration evidence, not design authority. Web now also has /runtime-dataset, an isolated clean runtime proof beside the compatibility shell. That route uses separate template, CSS, and JavaScript assets, requests /world/runtime only, builds runtime state from the canonical dataset, constructs a generic Web scene, renders workspace objects, contexts, field state, findings, and fallbacks, and dispatches only World-published action commands. It is a proof path, not yet the primary Web runtime. Android and iPad remain older non-authoritative implementations. Cardboard is an active standalone runtime proof for headset-specific rendering, but it is not fully conforming until it consumes the shared behavioral scenario corpus and completes interaction acceptance tests.
  • Web resolves service surface opening, panel navigation, payload rendering, and navigation profiles through World service descriptors. Optional specialized renderers are registry entries with a generic fallback rather than route-prefix or service-id branches.
  • Find and Surface publish ordered semantic action descriptors for findings and Surface Objects. Web normalizes these objects into generic cards and renders producer-owned labels; unknown object and action types fall back safely.
  • Runtime v2 fixtures now live in the contract-owned conformance corpus rather than Web. Web consumes the shared files directly. The field adapter no longer fabricates a Dawson City location when device location is unavailable.
  • The corpus now includes command, stack mutation, panel, authentication, and unavailable-state transitions. Web has a pure transition interpreter for these scenarios and no longer synthesizes missing Surface command routes.
  • The corpus also covers panel form submission, action-triggered refresh, and inline validation failures, with separate Web, Android, and iPad conformance checklists.
  • Android now consumes the shared corpus for contract normalization and behavioral state, renders its dock and Field controls from World data, and persists focus and placement only through World-published commands. Android also normalizes panel collections without service-kind branches and refreshes filtered Field controls and objects together through /world/session. World now publishes producer-described panel forms; Android renders those controls generically and declares its capabilities on session requests. Android remains non-authoritative until its interaction acceptance tests and remaining specialized-renderer review are complete.
  • Messages has been completed as an contract proof slice at the runtime boundary. Open Messages now belong to messages.elonn.local; Social DMs remain inside Social.
  • The Social contract is now target-state documentation: dashboard-first, circle-filtered, and independent of current implementation quirks.
  • Fresh world.elonn.local has a fixture-backed elonn.world.action_result v1 response model for POST /world/actions/{action_id}. Fixture actions now cover accepted, rejected, validation failure, persistent-state changed, no-op, and refreshed-dataset outcomes, and the contract runtime harness renders those outcomes from the response without service-specific logic.
  • Fresh world.elonn.local validates the clean runtime request boundary with elonn.world.session_request v1 and normalized elonn.world.error v1 responses. Request-body member identity is ignored; World uses trusted member context when supplied and records a development fallback explicitly in the identity section. Runtime state continuity is now part of the dataset through context, layout, and metadata fields for selected object, selected collection, pagination cursor, prior runtime session, and reconciliation facts.

Current cleanup focus:

  • keep the messages.elonn.local service and Social DM routes aligned with their separate ownership boundaries
  • finish aligning the Social panel and Web rendering with the target contract
  • tighten Find and Maps boundaries so discovery and field rendering remain separate concerns

Still incomplete or known gaps:

  • Web calendar presentation needs a separate visual polish pass; this does not block Time or CalDAV functionality.
  • Social service completeness against the world panel contract requires a dedicated review. The service has many endpoints but panel contract coverage is still broader than current implementation proof.
  • Notifications are partial; event and community invitation flows are not confirmed complete.
  • Find is the unified discovery layer. It fans out to all configured providers per query and merges results: first-party Elonn results (members, conversations, communities, social events, message threads) rank first, OSM place results second, Brave web results third. The X-Elonn-Member-Id header carries trusted member context from World through Find's controller to all providers; visibility filtering in Social and Messages queries uses this context. First-party providers query the authoritative service databases directly on the same server. Brave is wired and activates when BRAVE_SEARCH_ENABLED=true.
  • Find query scope is explicit: Nearby bounds OSM place results to a Find-owned 5 km radius; first-party and web results are not geo-filtered. Everywhere is global for all providers. term near place is a named-location override. Web visibly reports the active and applied scope.
  • Location findings remain free-floating surfaces in finding_overlay. Their Open control calls open_finding, which creates or focuses the durable center-stack map_surface for the place.
  • Surface now implements multi-surface translation for html_resource findings. When a member triggers the translate_surface command, a MultiSurfaceTranslator runs type-specific extractors (Business → Article → Hours → Menu → Events → Gallery → Contact) against the page's Schema.org JSON-LD. Each extractor that finds sufficient data creates a typed web_*_surface record; the finding surface's slot in the finding_overlay stack is replaced with the N new typed surfaces. Pages without structured data fall back to the existing single-object html_translator path. Runtimes receive the updated surface_runtime and render each typed surface independently; the page itself is never injected into the runtime. See surface-contract.md for the complete type list and payload shapes.
  • Find remains the active contract proof slice; native Surface Manifests, publisher markup assistance, and additional web providers are incomplete.
  • The Runtime Contract still needs generic panel rendering, durable-surface separation, and cross-service panel examples that do not depend on Web implementation details.

Separation rules

  • Services own domain data and business logic.
  • Surface owns durable surface identity, metadata, placement, persistence, synchronization, shareability, and saved layouts.
  • World aggregates services and Surface state into runtime-ready contracts; it does not become source of truth for services or surfaces.
  • Runtime owns rendering, layout, animation, gestures, and interaction.
  • Panels are UI inside rail stacks or surface bodies. Panels are not primary workspace surfaces unless they need durable identity, movement, sharing, persistence, and placement.
  • Messages, Social, Time, Find, and Maps should be treated as separate bounded contexts. Social DMs are part of Social; open Messages are part of Messages.