Helix — Technical & Architecture Guide
Helix is a multi-agent AI workspace organized around a Bench-themed Next.js web application, background run workers, isolated Daytona sandboxes, a PostgreSQL/Supabase data and authentication layer, and a self-hosted Posta transactional mail stack.
1. Repository & Code Architecture
| Layer | Directory | Responsibility |
|---|---|---|
| App Router & API | src/app/ | Next.js App Router pages for marketing (src/app/(marketing)/), authenticated Helix workspace (src/app/(v2)/helix/), legacy dashboard compatibility (src/app/dashboard/), status views (src/app/status/), embeds (src/app/embed/), and HTTP handlers (src/app/api/). |
| Request Proxy | src/proxy.ts | Session cookie relay, route protection, and host-scoped request forwarding. |
| Client Workspace UI | frontend/helix/ | Bench UI kit (ui2/kit.tsx, ui2/bench-kit.tsx, ui2/bench-board.tsx), interactive AgentFace avatar system (ui2/agent-face.tsx), colleague collaboration regions (ui2/colleague-features.tsx), staff platform controls (ui2/staff-platform-panel.tsx), and streaming hooks. |
| Marketing & Docs UI | marketing/ | Public landing components (marketing/components/marketing/), marketing AgentFace (marketing/components/marketing/agent-face.tsx), MDX documentation loader, and changelog data. |
| Backend Domain Layer | backend/ | Auth & Supabase SSR helpers (backend/lib/supabase/), transactional mailer (backend/lib/mailer.ts), Paystack billing, status probes (backend/lib/status/), channel adapters (backend/helix/channels.ts), and webhook verification. |
| Agent Engine & Runtime | agent/ | Mission execution loop (agent/core/run-loop.ts), crew catalog (agent/core/crew-shared.ts), colleague collaboration persistence & runtime (agent/core/colleague-runtime.ts), presence & mood logic (agent/core/agent-presence.ts), Daytona integration (agent/daytona/), standalone agent server (agent/engine/agent/server.ts), and background worker (agent/worker-main.ts). |
| Shared Utilities | shared/ | Cross-boundary primitives: branding (shared/brand.ts), structured logging (shared/log.ts), API errors (shared/errors.ts), secret scrubbing (shared/secret-scrub.ts), pricing, and rate limits. |
| Database Migrations | supabase/migrations/ | PostgreSQL schemas, RLS policies, signup triggers, and colleague collaboration tables (public.helix_* and helix_v2.*). |
| Archive | archive/ | Retired legacy implementation files (archive/legacy/) and archived deployment artifacts (archive/cloud-deployment/). The live application does not import from archive/. |
2. Runtime Processes
-
Web Application (
next start/ standaloneserver.js)- Serves the marketing site,
/helix/*workspace routes, authentication callbacks, OpenGraph generators (src/app/opengraph-image.tsx), and/api/*endpoints. - Connects to Supabase Auth/PostgREST/Storage and self-hosted Posta.
- Serves the marketing site,
-
Background Worker (
npm run worker/npm run v2-worker)- Runs
agent/worker-main.tsto claim queued tasks with PostgreSQL leases and execute runs againstHELIX_V2_BASE_URL.
- Runs
-
Standalone Agent Server (
npm run agent-server)- Runs
agent/engine/agent/server.tsfor dedicated HTTP/WebSocket agent orchestration when enabled.
- Runs
-
Status Server (
npm run status-server)- Runs
backend/lib/status/status-server.tsas an independent process so platform status remains available even if the primary web process restarts.
- Runs
3. Data & Authentication Model
Authentication & Cookie Isolation
- Browser and SSR clients (
src/utils/supabase/client.ts,src/utils/supabase/server.ts) use@supabase/ssrwith shared auth cookie logic inbackend/lib/supabase/cookies.ts. getSharedCookieDomain()scopes cookies dynamically to.launchverse.appin production domains while staying host-scoped (localhost/127.0.0.1) during local testing sonext startornext devcookie jars never fail cross-domain checks.- Signup triggers (
handle_new_user_signup()) are conflict-safe (ON CONFLICT DO NOTHING/ membership-guarded) so re-created or migrated users keep their existing team workspace rather than receiving a shadow empty team.
Core Schemas (public and helix_v2)
- Workspace & Runs:
teams,team_members,public.helix_threads,public.helix_runs,public.helix_missions,public.helix_approvals,public.helix_artifacts, andhelix_v2.*equivalents. - Colleague Collaboration Tables (
supabase/migrations/20261117190000_helix_colleague_features.sql):public.helix_out_of_office_windows— Out-of-Office delegation windows, covered/parked items, and compiled Return Briefings.public.helix_colleague_desks— Open Door live supervision state (colleague|shoulder_tap_paused|human_takeover), cursor location labels, and paused checkpoints.public.helix_concern_cards— Principled Disagreement (Stop & Push Back) concern records, alternatives, reversibility risks, shadow predictions, and human resolutions (proceed_as_asked|use_suggestion).public.helix_teach_playbooks— Teach-by-Showing captured UI/browser step traces with parameter extraction and automatic secret scrubbing (masked_fields_count).public.helix_source_consents— Per-user explicit consent flags (inbox,calendar,chat,files), WhatsApp compliance state (whatsapp_enabled,meta_ai_terms_verified), and dismissed hire suggestions.public.helix_mobile_approvals_queue— Idempotent mobile biometric approval queue decisions synced across channels.
- Security: All six
helix_*collaboration tables have Row Level Security (RLS) enabled with access revoked fromanonandauthenticated, restricting read/write access to server-sideservice_rolecalls guarded byauthedOrg().
4. Transactional Mail & Notifications
Outbound transactional mail and alerts are handled by backend/lib/mailer.ts with reply-to threading and opt-out enforcement. Internal self-hosted Posta SMTP/Postfix MTA topology and DNS setup are documented in the internal operations runbook: docs/operations/self-hosting-and-mail.md.
5. UI Design System, AgentFace & Link Previews
Expressive AgentFace Avatar System
Implemented in frontend/helix/ui2/agent-face.tsx, marketing/components/marketing/agent-face.tsx, and src/app/(v2)/helix/design.css:
- Supports 12 distinct states across both doing and emotional axes:
idle,working,waiting,done,error,observing,happy,angry,excited,sad,bored,sleeping. - Two-axis Eye Hierarchy:
.hx-face-lidowns involuntary blinking (scaleY), while.hx-face-pupilwraps both the dark pupil circle and.hx-face-glintcatchlight to drive state-specific eye tracking (hx-face-glance,hx-face-track,hx-face-peek,hx-face-scan,hx-face-happy,hx-face-glare,hx-face-drift,hx-face-dream) or pointer tracking (data-gaze). - Performance & Accessibility Guarantees:
- Every
@keyframes hx-face-*animates only GPU compositor properties (transformandopacity). @media (prefers-reduced-motion: reduce)stops all animations explicitly (animation: none !important).- Tested against source-level invariants in
tests/v2/agent-face-states.test.ts,tests/v2/agent-faces-and-workspace-image.test.ts, andtests/v2/class-coverage.test.ts.
- Every
Social / OpenGraph Preview Pipeline
shared/brand.tsdefines canonicalBRAND.tagline,BRAND.description,BRAND.ogImage, andBRAND.ogImageAlt.scripts/marketing/build-og.mjsrenderspublic/og.png(1200x630) andpublic/og@2x.png(2400x1260) via Playwright using real Bench display/text fonts, crew avatar states, and framed workspace screenshot.src/app/opengraph-image.tsxandsrc/app/twitter-image.tsxmirror the Bench theme dynamically for Next.js metadata image endpoints.