OpenAlice Embed — codebase recon + engineering brief

Phase 2 deliverable: map the 23-feature MVP scope of OpenAlice Embed (Persona Lite tier, web embed surface) to existing OpenAlice ecosystem components. Identify reuse-vs-new, sequence integration, brief Norbert with concrete starting points + dependencies.

TL;DR — engineering reality

• ~65-75 % of MVP backend already exists in openalice-persona + openalice-app + openalice-auth + openalice-ui + openalice-mollie + openalice-ml-gateway. Most «new code» is INTEGRATION + thin customer-facing surface, not greenfield.
• Honest revised engineering estimate: 6-10 weeks integration for full 23-feature MVP, with Norbert + Tycho co-coordination. (Earlier estimate was 5-8 wk; reality of 23 features is closer to 6-10.)
• Critical NEW build: customer-facing JS embed snippet (~2-5 k LOC), RAG ingestion pipeline, conversion attribution analytics, browser-render snapshot pipeline, anime UI rework of openalice-ui (parallel project).
• Critical wiring: openalice-mollie is library-only (experimental status, not yet wired into openalice-tenants). Billing integration = highest-risk new wiring path.

What we have — reuse inventory

openalice-persona (Avatar + voice + persona + memory backend)

(Repo features list exceeded token budget — sampled from `openalice-app`'s API client surface to map persona endpoints.)

Surfaces already shipped:

• /v1/me/agents — list / get / settings / overrides (voice + avatar + BGM)
• /v1/me/agents/:id/idle-config — idle behaviour config
• /v1/me/vrms — VRM library per-tenant
• /v1/me/audio — audio asset CRUD + upload + public URL (Lyria 3 generation)
• /v1/me/fonts — custom font upload
• /v1/me/sounds — soundboard CRUD + test-fire
• /v1/me/redemption-triggers — viewer-action triggers
• /v1/me/polls — engagement polls
• /v1/me/youtube — OAuth + audit + mod policy + actions
• AI moderation REST + static-mod rules
• ElevenLabs voice catalog + browser-native TTS preview

MVP feature ↔ persona reuse mapping:

openalice-app (Next.js Hub — admin surface)

Reuse for customer dashboard:

• /account/agents list + /account/agents/[id]/settings (per-agent voice/avatar/BGM editor) — repurpose as customer's persona editor
• /account/streams/_components/ThemePicker — 7 stream-theme presets + custom-override editor = direct base for our Sakura/Midnight/Cloud/Brand brand templates
• /api/persona/[...path] BFF proxy pattern — direct reuse
• /api/youtube/oauth/* OAuth flow → template for any future OAuth integration
• Auth flows (/login, /forgot-password, /reset-password, /verify) — direct reuse
• Confirm dialog primitive (ConfirmProvider, useConfirm) — direct reuse
• Voice picker UI + ElevenLabs preview — direct reuse
• VRM picker UI — direct reuse
• apiFetch shared HTTP helper — direct reuse

MVP feature ↔ app reuse mapping:

openalice-auth (Auth + service-to-service plumbing)

Direct reuse — no rebuild:

• JWT auth (access + refresh + Argon2id passwords)
• Email verification + password reset
• MFA (TOTP)
• WebSocket /auth/ws for cross-product real-time events
• /internal/broadcast for service-to-service notifications (Mollie webhooks → Auth → fan-out to UI)
• /internal/chat for chat events (persona uses to feed agent context)
• /internal/chat-feed for aggregated chat ticks (n-gram + mood + highlights) — interesting: this is brand-safety-adjacent, may reuse for widget customer-conversation tagging
• auth_config + chat_sources + stream_destinations — pattern for customer config storage (encrypted secrets) — direct reuse for any «customer needs to store API tokens» case

MVP feature ↔ auth reuse:

openalice-mollie (Billing SDK — NOT YET WIRED)

⚠️ Status: library crate, experimental, NOT wired into openalice-tenants (canonical wiring target) per repo feature description.

SDK has:

• MollieClient (Bearer auth, REST over reqwest)
• Customers (create + get)
• Subscriptions (create + cancel + get + list)
• Payments (create + get + list)
• Typed structs (Customer / Subscription / Payment / Amount)
• Typed error enum

MVP feature ↔ mollie reuse:

Risk: Mollie is the highest-risk new wiring because it ties money flow. Test with sandbox first, real money second.

openalice-ml-gateway (ML routing + rate limit)

Direct reuse:

• API key system with per-key rate limits + monthly token caps
• /v1/embed proxy → direct reuse for RAG ingestion vectorisation
• /v1/rerank proxy → reuse for RAG retrieval reranking
• /v1/ner proxy → optional for content classification
• Per-key usage report + Prometheus metrics
• Crash-safe persistence (background-saver pattern)

MVP feature ↔ ml-gateway reuse:

openalice-ui (Atelier UI components)

Direct reuse — substantial:

• 30+ primitives (Button, Input, Modal, Dialog, Dropdown, Combobox, Select, Switch, Slider, Checkbox, Radio, Textarea, Tooltip, Tabs, Skeleton, Spinner, Banner, Badge, Avatar, Pagination, Progress, ScrollArea, EmptyState, KbdKey, CopyButton, FormField, Separator, etc.)
• Composites (AuthShell, BrandMark, DashboardGrid, LiveIndicator, PageHeader, SectionHeader, SettingsShell, ThemeProvider, CommandPalette, EcosystemShell)
• Auth provider + AuthGate + useAuthWs
• API hooks (useMe, useAuthGuard, useBilling, useKeys, useUsage, useLoginAction, useLogoutAction, useRegisterAction)

⚠️ NOT anime-styled — current «Atelier» aesthetic is warm/editorial. Per NAO directive 2026-05-27:

Parallel project: anime-rework of `openalice-ui` into Sakura aesthetic.

• Re-skin existing 30+ primitives with Sakura design tokens (pastel palette + serif headlines + sparkle micro-animations)
• Maintain backward compatibility (theme switcher: «atelier» vs «sakura») so internal tools keep current look
• Sakura becomes default for OpenAlice Embed widget + customer dashboard + landing pages
• Effort: 2-3 weeks of design + frontend rework (parallel to MVP, not blocking)
• Mandatory: invoke `/frontend-design:frontend-design` skill per memory directive

What we need to NEW BUILD

1. JavaScript embed snippet (NEW, ~2-5 k LOC)

• Customer copy-pastes <script src="..."> into their HTML
• Loads VRM avatar via Three.js (browser-side render, zero our-side GPU)
• Connects to persona backend via WebSocket
• Renders Sakura-themed chat bubble (collapsed) + expanded modal
• Mode-aware behaviour (Sales / Support / Brand presets)
• Upsell modal spawning capability
• Image fallback for low-end devices (via snapshot pipeline ↓)
• Brand template applied via CSS variables

2. Browser-render snapshot pipeline (NEW, ~500-1 k LOC)

• First visitor's browser renders VRM in canvas → captures snapshots (idle / talking / waving / thinking poses) → POSTs to our CDN
• Subsequent low-end devices get cached image swap instead of WebGL
• Per-character + per-template snapshots cached aggressively
• Solves «no server GPU» constraint elegantly

3. RAG ingestion pipeline (NEW, ~1-2 k LOC)

• Customer pastes site URL during onboarding
• Auto-scrape FAQs + product pages (respecting robots.txt + sitemap)
• Chunk + vectorise via ml-gateway /v1/embed
• Store vectors in Qdrant or pgvector
• Retrieval at conversation time + rerank via ml-gateway /v1/rerank

4. Conversion attribution analytics (NEW, ~1-2 k LOC)

• Conversation events emitted to customer dashboard
• Map conversation → customer's downstream conversion (via JS pixel customer adds)
• Lead-capture form integration
• ROI calculator («Alice attributed $X to your business this month»)

5. Mollie billing wiring (NEW integration ~1-2 k LOC)

• Signup flow → create Mollie customer + subscription
• Webhook handler for status updates (paid / failed / canceled)
• Cancellation flow
• Annual «2 months free» logic via metadata
• Per-tier feature gating

6. LLM adapter layer (NEW, ~500-1 k LOC)

• Abstract LLMProvider interface
• Adapters for Mistral / Aleph Alpha / Claude / GPT / Gemini / Llama (via OpenRouter SDK)
• Customer-picker config persistence
• Consent dialog flow for US-cloud LLMs
• Cost tracking per customer / per conversation

7. Customer dashboard (NEW pages on top of openalice-app, ~2-3 k LOC)

• Customer signup / onboarding wizard (60-90 sec character creation game)
• Persona editor (repurpose existing /account/agents/[id]/settings)
• Brand template picker (repurpose ThemePicker)
• Knowledge base manager (upload + delete + re-ingest)
• Conversation log viewer
• Conversion analytics view
• Webhooks config
• Billing / subscription management
• Snippet copy + install verification

8. Onboarding wizard — game-like (NEW, ~1-2 k LOC)

• 7-step character-creation flow with live preview
• Avatar carousel (NAO's NPC catalog)
• Vibe picker (Professional / Friendly / Playful)
• Voice carousel (3-5 ElevenLabs voices, hover-preview)
• Mode picker (Sales / Support / Brand visual cards)
• Site-URL paste + auto-RAG (triggers ingestion async)
• Tone slider + sample-line preview
• Snippet copy + confetti

9. Webhook delivery subsystem (NEW, ~500 LOC)

• Customer registers webhook URL
• On key events (lead captured / escalation / conversation ended) → POST to URL
• Retry policy (exponential backoff)
• Signed payloads (HMAC)

10. A/B testing harness (NEW, ~500 LOC)

• Config-flag system on persona-server
• Two variants per persona, route N % to each
• Stat-significance reporter

11. Demo showcase workflows (NEW, ~500 LOC)

• Canned demo personas (per-industry templates)
• Alice walks visitor through her capabilities on landing
• Embeddable «See it in action» element on customer's site

12. Human handoff escalation (NEW, ~300 LOC)

• Triggers: user requests human, AI confidence low, brand-safety violation
• Notification: email + Slack webhook + customer's webhook URL

13. Live preview during config (NEW, ~500 LOC)

• iframe sandbox on customer dashboard showing widget with current settings
• WebSocket push from persona on config changes
• Settings save → real widget reflects immediately

14. AI installer chatbot (NEW, ~500 LOC)

• Alice variant that helps customer install Alice
• Auto-detects customer's stack (Shopify / WP / Wix / React / etc.) from URL
• Provides exact snippet placement instructions
• Debugs install errors

15. Customer data export (NEW, ~300 LOC)

• One-click export of all customer's data (conversations + persona configs + RAG corpora)
• GDPR-required
• Async job + download link

16. Credit-capped demo on landing (NEW, ~500 LOC)

• Anonymous visitor session with ~$0.50-1.00 worth of credits
• Real-time accounting against shared bucket
• Hard-cap → «sign up» CTA
• Cloudflare Turnstile + IP rate limit

17. Slack workspace (config-only, no engineering)

• NAO creates Slack workspace alongside Discord
• Both linked in dashboard + landing

18. Promo code system (NEW, ~300 LOC)

• Generate / list / redeem promo codes
• Locked launch-price tier
• Founder Discord invite trigger on redemption

19. Anime rework of openalice-ui (PARALLEL, 2-3 wk)

• Sakura design tokens
• Restyle 30+ primitives
• Backwards-compat with «atelier» theme
• Mandatory /frontend-design:frontend-design skill

20-23. Smaller features

• Multi-lang UI (i18n layer, ~500 LOC)
• 3 mode presets (config templates, ~200 LOC)
• Voice clone setup flow (ElevenLabs Pro API, ~200 LOC, Pro tier only)
• Customer-facing legal docs hosting (static page, ~minor)

Integration sequence (milestone-ordered, no months)

Honest effort estimate

• Backend integration (Persona Lite mode + RAG + Mollie + LLM router + analytics + webhooks + handoff): 3-4 weeks Norbert-focus.
• Customer-facing frontend (dashboard + onboarding wizard + brand templates + live preview): 2-3 weeks frontend work.
• JS embed snippet + browser-render snapshot pipeline: 1-2 weeks specialist frontend / WebGL.
• Anime UI rework (parallel project): 2-3 weeks design + frontend (mandatory /frontend-design:frontend-design skill).
• Integration testing + bug fixing + dogfood polish: 1-2 weeks.

Total: 6-10 weeks integration with Norbert + Tycho co-coordination + parallel UI rework. Plus 1-2 weeks legal/docs/setup work that NAO + I (Hormozi) handle alongside.

Critical risks + dependencies

• Mollie integration risk — money flow is hardest to test. Sandbox first, real money second.
• VRM browser render performance on mobile — Three.js + VRM is heavy. Image fallback is essential.
• RAG hallucination quality — if Alice gives wrong answers from poorly-ingested KB, brand damage. Need confidence-gated escalation.
• LLM cost runaway — single chatty visitor could burn $5+ in tokens. Per-customer token cap + alerting required from day 1.
• GDPR compliance for EU customers — DPA + privacy policy + data export must be in place before first EU paying customer.

Hand-off to Norbert

Engineering brief deliverables for Norbert kickoff:

1. This recon document (current memo).
2. The Grand Slam Offer doc (Alex Hormozi agent memory, project-grand-slam-offer-1-saas-landing-rep, 2026-05-26).
3. The three-tier agent architecture doc (Alex Hormozi agent memory, project-three-tier-agent-architecture, 2026-05-26).
4. The sovereignty stack doc (Alex Hormozi agent memory, reference-sovereignty-stack, 2026-05-26).
5. The widget architecture insights (Alex Hormozi agent memory, project-widget-architecture-insights, 2026-05-25).
6. A concrete starting-point file checklist (the «what to touch first»).

Recommended Norbert first 3 actions:

1. Wire openalice-mollie into openalice-tenants (the canonical billing wiring target) with sandbox account test (subscription create + webhook receive + status update). Highest-risk, most-isolated, easiest to validate. 2-3 days.
2. Scaffold openalice-llm-router crate with Mistral + Claude + OpenAI adapters behind one trait. Customer picks via config. 2-3 days.
3. Extend openalice-persona with «embed-mode» agent type (stateless / per-conversation memory / no streaming features). 3-5 days.

After those 3 are done, frontend (JS embed snippet + customer dashboard) can start in parallel.

Errata

• 2026-05-27: All references to platform-api as the Mollie billing wiring target replaced with openalice-tenants. The platform-api service was never built; openalice-tenants is the canonical wiring target (it already lists mollie in its consumers in .atlas-deps.yml).