Architecture

System Architecture

The Agent App platform is organized into distinct layers, each with clear responsibilities.

Database Layer

All data lives in Supabase PostgreSQL with Row-Level Security (RLS) policies:

Table	Purpose
`apps`	App registry — metadata, agent config, status, ratings
`app_versions`	Version history — bundle URLs, hashes, review status
`user_installed_apps`	Per-user installations — position, pinning, preferences
`app_ratings`	User ratings and reviews
`app_reviews`	Internal review records (reviewer decisions, security/UX checks)
`agent_apps`	Junction table — links agents to apps (agent-to-app assignment)

Note: The agent_apps table is a junction table that links agents to apps, separate from the main apps table.

The apps table contains both app metadata and agent configuration in a single row:

-- Core fields
id, slug, name, description, long_description,
icon_url, color, developer_id, category, status,
is_builtin, sort_order, tags, required_permissions,
install_count, average_rating, rating_count,

-- Agent configuration
system_prompt, model, temperature, max_tokens,
tools, welcome_message, suggested_prompts,
memory_enabled, max_context_messages

Edge Functions Layer

Four Supabase Edge Functions (Deno) handle the server-side logic:

Function	Method	Purpose
`agent-app-register`	POST	Register a new app (creates `apps` row in `draft` status)
`agent-app-publish`	POST	Submit a new version for review (creates `app_versions` row)
`agent-app-review`	POST	Internal review — approve or reject a version (admin/reviewer only)
`agent-app-list`	GET	List published apps with category filter, search, and pagination

SDK Layer

The @assistme/agent-app-sdk package provides:

Type definitions — MicroApp, MicroAppVersion, UserInstalledApp, MicroAppBridge, etc.
Registration API — registerMicroApp() for statically bundled apps
React Context — MicroAppContext + useMicroApp() hook for accessing bridge and host context
Bridge types — The contract between host and agent app

Runtime Layer

The runtime lives in mobile-app/src/agent-runtime/ and handles the resolution and rendering of Agent Apps.

Engine (engine.ts):

Resolves how to load an app: static registry or dynamic bundle
Returns a LoadResult indicating the rendering path

Container (container.tsx):

Receives a LoadResult and renders accordingly
Static apps: renders the registered React component directly, wrapping it in MicroAppContext.Provider
Dynamic apps: delegates to DynamicContainer which renders in a WebView

Bundle Manager (bundle-manager.ts):

Downloads, caches, and manages JS bundles on disk
Bundles stored at agent-app-bundles/{slug}/{version}/
SHA256 integrity verification
Semver-aware version sorting

Bridge Implementation (bridge-impl.ts):

Creates the concrete MicroAppBridge for each app instance
Sandboxed storage: keys namespaced as agentapp_{slug}_{key}
Platform-aware toast (Android ToastAndroid, iOS Alert)
Permission prompts with 60-second timeout
Haptic feedback via expo-haptics

Agent Apps are routed via expo-router:

/agent-app/[appSlug]    →  MicroAppContainer resolves and renders the app
/app-detail/[slug]      →  App detail page (store listing, ratings, install)
/developer              →  Developer dashboard
/developer/register     →  Register new app form
/developer/[slug]       →  Manage a specific app
/developer/[slug]/publish → Publish a new version

System Architecture

Database Layer

Edge Functions Layer

SDK Layer

Runtime Layer

Navigation

On this page