Optimus

Control panel for cloud browser automation. Users describe a task in English, Optimus drives a real browser on Browser Use Cloud, and every run is recorded with steps, screenshots, tokens, and cost. It also runs recurring SERP monitors (Bing via SerpApi) that auto-trigger a Browser Use follow-up when a tracked domain slips below a configured rank.

The system is two Railway services sharing one Supabase Postgres, plus thin clients:

apps/api — a Hono server that owns route handlers, run orchestration, the Browser Use webhook receiver, the SERP cron tick, and Drizzle migrations. Single replica.
apps/web — a Next.js 16 / React 19 dashboard. UI only — no DB, no background work; calls apps/api over HTTP via @optimus/api-client.
apps/mobile — an Expo (React Native) client with feature parity to the web app. Same Better Auth OAuth flow, session cookie persisted in expo-secure-store.
apps/tui — an Ink CLI; reaches apps/api with a personal access token.

Documentation map

Section	What’s in it
Getting started	Install, run locally, understand the moving parts.
Concepts	Runs, SERP monitors, the status machine, auth, cost, URL guard.
Apps	The `apps/api` Hono server, the `apps/web` Next.js UI, the `apps/mobile` Expo client, and the `apps/tui` Ink CLI — each app’s tech stack, routes, and conventions.
Packages	Hand-written guides for the shared workspace packages.
API reference	Auto-generated TypeScript symbol-by-symbol reference.
Operations	Deploying to Railway + Supabase, troubleshooting.
Contributing	Branch + commit conventions, coding standards, docs workflow.

Monorepo layout


apps/
  api/            Hono server — routes, RunHub, webhook, SERP cron, migrations
  web/            Next.js App Router — UI only, calls apps/api
  mobile/         Expo (React Native) — UI only, calls apps/api
  tui/            Ink TUI — thin HTTP client
  docs/           This site (Nextra + Next.js)
packages/
  core/           Pure TS domain: types, Zod schemas, URL guard, cost, status machine
  api-client/     Typed HTTP + SSE client (shared by web, mobile, TUI)
  browser-use/    Wrapper around Browser Use TS Cloud SDK
  serp/           SerpApi adapter + rank/competitor analysis (Bing)
  db/             Drizzle schema + repositories (server-only)
  auth/           Better Auth config + PAT helpers
  design-tokens/  Color / spacing / type tokens shared by web + mobile
  config/         Shared tsconfig presets
legacy/           Original Python Textual app — read-only reference until TS parity

Where things live

Source of truth for domain types: @optimus/core.
HTTP API + run orchestration: apps/api.
Database schema: @optimus/db.
Browser automation backend: @optimus/browser-use, wrapping Browser Use Cloud.
SERP monitoring: @optimus/serp and the SERP monitors concept page.
Auth (sessions + PATs): @optimus/auth, built on Better Auth. Mobile adds @better-auth/expo.
Production runbook: Operations / Deployment.