Runtime Architecture — Marvia Execution Layer

Marvia-10

One execution layer, one ownership chain

The runtime binds every Marvia system into a single execution layer. Ownership is strict, coupling is loose, and nothing reaches sideways.

UWO version

1.0

Ownership levels

Runtime events

Registry kinds

Ownership flow

workspace→project→website→snapshot→knowledge→uwo→extension→report→dashboard

Isolation

Projects and websites execute independently; one failure never leaks into another.

Context-driven

Every operation receives its workspace, project and website context explicitly.

Event-based

Runtime work announces itself through standardized events, never through polling.

Extensible

Every runtime component is a registry entry, so extensions plug in without core edits.

Runtimes

Workspace, project, website

Three runtimes, each with an explicit boundary. A project never reads workspace internals; a website is a first-class entity, not a snapshot attribute.

Workspace runtime

· Projects and members
· Credits and billing
· Extensions and services
· Settings and notifications
· Activity tracking

Provides context for every nested operation; performs no website work itself.

Project runtime

· Websites and snapshots
· Reports and knowledge
· Extensions and files (future)
· Comments and tasks (future)

No knowledge of the workspace implementation — it operates only through the provided context.

Website runtime

· Primary and normalized URLs
· Hostname and status
· Snapshots and knowledge
· Technology stack and history
· Reports and future crawl data

A first-class entity: a website exists independently of any single snapshot.

Flow

From URL to dashboard

Every analysis walks the same three stages. Extensions join at stage two, and only through the UWO.

Website analysis

· Normalize the URL
· Select workspace, then project
· Create the project or website when missing
· Generate snapshot → knowledge graph → UWO

Extension processing

· Extensions consume the UWO — never raw snapshots, never HTML
· Each stage emits its standardized runtime event

Reporting and dashboard

· Extensions produce reports
· Dashboard and history update from events

UWO

The Universal Website Object

The immutable public contract. Extensions read this and nothing else — never a raw snapshot, never HTML.

{
  "version": "1.0",
  "website":     { "url", "hostname", "status" },
  "metadata":    { "title", "description", "language" },
  "content":     { "headings", "links", "images", "assets" },
  "performance": { "metrics", "lighthouse_scores" },
  "security":    { "headers", "vulnerabilities" },
  "technology":  { "stack", "frameworks" },
  "entities":    { "relationships", "summary" },
  "history":     { "timeline", "snapshots" }
}

Rules

· Strongly typed: every field is declared in the schema, nothing is free-form.
· Versioned: consumers pin a version and older objects stay readable.
· Immutable: a UWO is generated once per snapshot and never mutated.
· Public: this is the only website contract an extension is allowed to read.

Knowledge adapter

· Decoupling: extensions never see a snapshot field, only the UWO.
· Schema evolution: a new snapshot version is absorbed by the adapter, not by consumers.
· Integrity: a missing source field becomes an explicit null, never an invented value.
· Determinism: the same snapshot always produces the same UWO for a given adapter version.

Section	Fields	Purpose
website	url, hostname, status	Identity of the analyzed site.
metadata	title, description, language	Descriptive surface for SEO and AI.
content	headings, links, images, assets	Structure and content graph.
performance	metrics, lighthouse_scores	Speed and delivery posture.
security	headers, vulnerabilities	Security posture.
technology	stack, frameworks	Detected technology.
entities	relationships, summary	Knowledge-graph projection.
history	timeline, snapshots	Change over time.

Events & registry

Standardized events, dynamic registration

Runtime work announces itself; every addressable thing registers itself. No polling, no hardcoded references.

Event	Trigger	Payload
website.created	New website registration	Website metadata
snapshot.completed	Snapshot generation finished	Snapshot id, metrics
knowledge.generated	Knowledge graph creation	Graph summary
uwo.generated	UWO production	UWO structure
extension.executed	Extension processing	Extension results
report.generated	Report completion	Report data

Registry kinds

projectwebsitesnapshotextensionwidgetreportcommandquick-action

Why

· No hardcoded references anywhere in the kernel.
· Capabilities are discovered at runtime, not at build time.
· Extensions add projects, widgets, reports and commands through the same door.

Interfaces

Sidebar, overviews, history and onboarding

The runtime drives the UI: navigation, overview pages, the automatic timeline and the Marvia 101 checklist are all data, never markup decisions.

Sidebar runtime

1. Current workspace (Workspace runtime context)
2. Projects (Runtime registry (project))
3. Recent reports (Runtime registry (report))
4. Pinned items (Personalization store)
5. Extensions (Extension registry)
6. Credits and settings (Workspace runtime)

Workspace overview

· Mission statement
· Recent projects
· Recent activity
· Service connections
· Health metrics

Project overview

· Website details
· Latest snapshot
· Latest reports
· Extension inventory
· History
· Quick actions

Marvia 101

1. Create a workspace
2. Create a project
3. Analyze a website
4. Install an extension
5. Connect Google Search Consoleoptional
6. Complete the starter lessons

· Progress is derived from runtime events, never stored by hand.
· Optional steps never block completion.
· On completion the card is replaced by the workspace mission statement.

Automatic history

workspaceprojectwebsitesnapshotextensionmarketplacelearning

· History is written by the runtime, not by feature code.
· Entries are append-only and workspace-scoped.
· Sensitive operations also write an immutable audit-log row.

Commands & API

One registry powers palette, quick actions and agents

Every executable operation registers a command. The runtime API gives contextual access to everything else.

Core commands

website.analyzeAnalyze websitesnapshot.create
project.createCreate projectproject.create
snapshot.generateGenerate snapshotsnapshot.create
extension.installInstall extensionextension.install

Command paletteQuick actions on the dashboardFuture AI agent tool calls

Runtime API

workspace — Current workspace runtime and its context.
project — Current project runtime, or null outside a project.
website — Current website runtime, or null outside a website.
getUwo(snapshotId) — The immutable website contract for a snapshot.
registry — Runtime discovery of projects, widgets, reports and commands.
commands — Register and execute runtime commands.
history — Read and append timeline events.
getCredits() — Balance and reservations for the current workspace.
listExtensions() — Installed extensions for the current context.

Non-functional

Performance and security

The runtime's guarantees are as binding as its contracts.

Performance

· Runtime components load lazily; nothing unused is instantiated.
· Context is memoized across repeated operations in one request.
· Long-running work goes to background queues, never to the request path.
· No polling — the UI updates from runtime events.

Security & compliance

· Data is isolated between workspaces and between projects.
· Sensitive operations write immutable audit logs.
· Extensions run sandboxed and read the UWO only.
· Runtime events are authenticated and authorized before dispatch.