Authoritative runtime, module, ingestion, inference, and device-architecture specification for the current enterprise baseline.
This document defines how Aevum is architected at system level today and what the target enterprise runtime model is intended to be. It captures the real module topology, canonical ingestion boundary, local storage model, local inference path, and the release-critical differences between package stability and actual application readiness.
This architecture is written to support disciplined execution by engineering teams, QA, security, compliance, and future external delivery partners.
flowchart TD
A["UI Layer\nApp / Widgets / Sheets / Views"] --> B["UnifiedIngestionService\nCanonical Ingestion Boundary"]
A --> C["BehaviourIntelligenceLayer\nCompanion Orchestration"]
B --> D["CoreMemory / SwiftData\nRoot MemoryEntry + Event Persistence"]
B --> E["IntelligencePipeline\nDeferred Enrichment / Background Processing"]
C --> F["ContextRetriever + PromptAssembler"]
F --> G["PhiEngine / Local Inference"]
G --> C
E --> D
D --> H["Memory Graph / Relationships / Session / Persona State"]
I["Cloudflare R2\nModel Artifact Delivery"] --> G
| Layer | Responsibility | Current State |
|---|---|---|
| UI Layer | User input, onboarding, dashboards, capture sheets, import surfaces, settings, legal/privacy views, widgets. | Real and active. Multiple surfaces now route more consistently, but release truth still depends on app-level build and metadata cleanup. |
| Canonical Ingestion Layer | Single gateway for first-party input to become visible root memory/log entries. | Implemented via UnifiedIngestionService. Core architectural improvement over prior fragmented paths. |
| Companion Orchestration Layer | Turn user input into contextual response behavior using persona, session, and retrieved memory context. | Implemented in BehaviourIntelligenceLayer and supporting helpers, but response quality and release truthfulness remain separate concerns. |
| Deferred Processing Layer | Post-save enrichment, event handling, deduplication, and system processing after root persistence. | Implemented via IntelligencePipeline and EventQueueActor. Must never replace direct root write for user-driven actions. |
| Persistence Layer | SwiftData / local store for memory entries, events, session state, persona state, logs, and graph-related entities. | Real and central. Strongest current architectural truth of the system. |
| Inference Layer | Local model orchestration, prompt assembly, context retrieval, and response generation. | Real, but still operationally constrained by app packaging, entitlements, and model-delivery strategy. |
| Module / Package | Role | Architectural Notes |
|---|---|---|
CoreMemory | Canonical local data models and store foundation. | Contains primary persistence entities and store setup. Must remain storage/domain focused, not orchestration-heavy. |
IntelligenceEngine | Ingestion, orchestration, event processing, companion logic, runtime intelligence coordination. | Owns the canonical ingestion service and most behavior control logic. |
PhiInferenceEngine | Local model and inference-related runtime components. | Also contains external model artifact download logic, which is a release/compliance disclosure concern. |
UIComponents | Shared UI surfaces and product-facing flows. | Should remain thin in business logic; major control logic belongs in ingestion/orchestration layers. |
MemoryGraphEngine | Graph and relationship-oriented engine logic. | Supports higher-order relation and graph behavior. |
SecurityLayer | Security-related helpers and device-local protections. | Not yet sufficient alone to claim enterprise security readiness. |
ShortcutsIntegration | App Intents / Shortcuts entry surfaces. | Must respect the same ingestion contract as first-party app surfaces. |
CloudSyncEngine | Integration-facing logic. | Current enterprise truth requires strict scrutiny of what is real versus placeholder or local-only behavior. |
MemoryEntry immediately.UnifiedIngestionService is now the intended single ingress boundary.| Surface | Expected Behavior | Architectural Rule |
|---|---|---|
| Dashboard text / voice | Immediate visible root entry, then contextual response and optional enrichment. | Must not create duplicate root nodes. |
| CaptureSheet text / voice | Immediate visible root entry with correct provenance. | Voice remains .voice, text remains .text. |
| Import route | Must open true import surface and create visible imported logs immediately. | Import must not route to unrelated legacy UI. |
| Habit actions | Immediate visible system/habit log entry. | No queue-only behavior for user-triggered habit actions. |
| Legacy initialization | Immediate visible root event followed by optional enrichment. | Must remain auditable and not hidden inside pipeline-only work. |
| Shortcuts / App Intents | Respect same local persistence truth where the action is user-originated. | No hidden alternate persistence rules. |
ContextRetriever and PromptAssembler are present and improve grounding.
sequenceDiagram
participant U as User
participant UI as UI Surface
participant UIS as UnifiedIngestionService
participant DB as SwiftData Store
participant BIL as BehaviourIntelligenceLayer
participant RET as ContextRetriever
participant INF as PhiEngine
participant PIPE as IntelligencePipeline
U->>UI: Type / Speak / Import / Act
UI->>UIS: captureImmediate / ingestImportedItem / ingestImportedBatch
UIS->>DB: Create root MemoryEntry
UIS->>PIPE: Append deferred enrichment event
UI->>BIL: Request companion response
BIL->>RET: Fetch persona / session / recent context
RET->>DB: Retrieve local state
BIL->>INF: Invoke grounded local inference
INF-->>BIL: Structured output
BIL-->>UI: Companion response
PIPE->>DB: Post-save enrichment / graph updates
| Surface | Current State | Architectural Implication |
|---|---|---|
| iPhone | Primary product surface. | All baseline release decisions should be anchored here first. |
| iPad | Shared iOS app surface, not a deeply separate runtime architecture. | Needs validation, but not a distinct architectural stack. |
| Widgets | Present and integrated into project topology. | Need the same product-truth and metadata discipline as the main app. |
| macOS / cross-platform package support | Package compilation is increasingly portable, but release truth remains iOS-first. | Do not confuse package portability with product-platform readiness. |
| Risk | Description | Impact |
|---|---|---|
| Package success misread as app readiness | Package builds/tests are green, but app-level build still fails. | False release confidence. |
| Identity drift | MindTwin and Aevum coexist in active release metadata. | Brand, legal, App Review, and UX inconsistency. |
| Entitlement risk | High-risk memory entitlements remain unresolved. | App Store rejection or review escalation risk. |
| Privacy truth gap | Runtime/legal copy overstates what is proven today. | Compliance and trust risk. |
| Manifest/disclosure gap | Missing app-owned privacy manifest and incomplete external-boundary disclosure. | Submission and policy risk. |
| Criterion | Success Condition |
|---|---|
| Architecture clarity | Teams can identify ingestion, persistence, deferred enrichment, inference, and external boundaries without ambiguity. |
| Input discipline | All first-party inputs use the canonical ingestion model. |
| Release truth | Architecture docs no longer imply package stability equals deployment readiness. |
| Compliance alignment | Architecture docs clearly distinguish local processing, external model delivery, and evidence gaps. |