platform/CLAUDE.md

CLAUDE.md

Project Overview

Officer is a self-hosted personal platform for one person: the server owner. It bundles an AI agent, a terminal, a file browser, a code editor, email, chat channels, a remote desktop and customisable dashboards behind a single web app.

Single-user is a hard invariant, not a stage. There is exactly one account, created once by POST /auth/bootstrap while the user table is empty. There are no roles, no invitations, no sandboxing of one user from another, and no per-user isolation anywhere in the codebase. If a change seems to need "which user is this", the answer is always the owner.

Architecture

One Bun process (src/server.tsx) serves everything:

• the React SPA, via Bun's HTML import of src/apps/officer-web/index.html (HMR in dev)
• the REST API, a Hono app mounted at /api (src/servers/hono.ts)
• eight WebSocket providers — terminal, chat, task-runner, pipeline, dev-server proxy, cliamp, cliamp-audio, desktop — plus a sidecar registration socket
• a browser relay on its own port (BROWSER_RELAY_PORT, default 18792)

Long-running and privileged work lives in sidecars: separate processes that dial back in over /api/sidecar/register and are tracked in src/servers/sidecar-registry.ts. PM2 runs them (ecosystem.config.cjs): officer (the server), officer-claude, officer-opencode, officer-email, officer-pty, officer-vnc.

Agents run unsandboxed as the server owner, with --dangerously-skip-permissions. This is deliberate — it is the owner's own machine. Do not add a jail without being asked.

Repository Layout

src/
├── server.tsx              # the single entrypoint: routes, WS upgrades, static files
├── apps/
│   ├── officer-web/        # the SPA shell — Screens/Authentication + Screens/Dashboard
│   └── landing/            # marketing landing page
├── servers/
│   ├── hono.ts             # router composition; everything under /api
│   ├── _middlewares/       # auth, body parsing, origin validation, rate limiting
│   ├── api/<feature>/      # one folder per feature, each exporting a router
│   ├── channels/           # Telegram / WhatsApp / Discord bridges
│   ├── queue/              # background job engine
│   └── sidecar/            # sidecar implementations + the wire protocol
├── databases/officer_db/   # the only database (Postgres + Drizzle)
├── extensions/browser-relay/
└── workspaces/             # shared packages, each a bun workspace

src/workspaces/officerdev is the biggest of these: the windowed "apps" (FileBrowser, Chat, Terminal, CodeEditor, Desktop, Projects, Dashboards…) that the shell hosts, behind an AppRegistry. src/apps/officer-web is only the shell — screens, routing and settings.

Path aliases (tsconfig.json): @/* → src/apps/officer-web, @/components/* → src/workspaces/components, @@/* → src/servers, @/public/* → public. Workspace packages are imported by their package name (officerdev, hooks, state, types, helpers, …).

Tech Stack

• Runtime: Bun (Node 22 is enforced by a preinstall check)
• Language: TypeScript, strict. bunx tsgo is clean — keep it that way.
• Frontend: React 19, React Router 7, React Query, Tailwind 4, shadcn/ui + custom components
• Backend: Hono
• Database: one Postgres database via Drizzle
• Agents: Claude Code and opencode, driven through sidecars; tools exposed over MCP

Data

Two stores, and the split matters:

Postgres (src/databases/officer_db) holds the account, passkeys, settings, dashboards, projects, email accounts, queue and pipeline jobs. Schema in src/schema/, hand-written queries in src/queries/, types inferred from the schema in src/types.ts.

The filesystem holds everything the agent authors. OFFICER_ITEMS_DIR contains one directory per item under skills/, tools/, tasks/, processes/, extensions/ — no database rows, no scope tiers. DATA_PATH/<email>/ holds the managed home, attachments and per-account email SQLite stores. Path helpers live in src/servers/data-path.ts; note getHomeDir (the managed home under DATA_PATH) versus getOwnerHomeDir (the owner's real login home when HOME_DIR is set, which is where terminals, chats and task runs actually execute).

Schema changes use push, not migrations

This database is kept in sync with bun db:push, which diffs the schema code against the live database and alters it directly. drizzle-kit migrate has never been run here — there is no __drizzle_migrations table. Change the schema, run bun db:push, done.

bun db:gen writes files to officer_db/migrations/, but nothing applies them; the old numbered history was deleted because it had drifted from the real schema. Treat the schema code, not those files, as the source of truth.

Security Model

The perimeter is one credential, so the guards matter:

• IS_DEV_BUILD (src/servers/build-env.ts) is true only when PUBLIC_BUILD_ENV is explicitly dev/development. Everything else, including unset, is hardened. Origin validation, rate limiting and password rules all key off it — they fail closed.
• Allowed origins come from PUBLIC_URL. Officer always sits behind an HTTPS reverse proxy, so the forwarded Host must equal PUBLIC_URL's authority exactly.
• JWTs are 30-day, blacklisted on signout, and invalidated by a password change (passwordChangedAt).
• A panic lockdown (src/servers/api/auth/panic.ts) is in-memory only and refuses every authenticated request until the server restarts.

Commands

bun dev          # the whole app — SPA + API + WebSockets, watched
bun start        # production
bunx tsgo        # typecheck (not tsc)
bun test         # tests
bun format       # prettier over changed files only
bun db:push      # apply the schema to Postgres
bun setup        # guided install (writes .env, incl. PUBLIC_BUILD_ENV=production)

Sidecar control: bun run start:sidecar / stop:sidecar / restart:sidecar / logs:sidecar.

Note: build:editor* in package.json points at scripts/build/editor.ts, which does not exist.

Code Style

• Paradigm: functional — pure functions, immutability, composition
• TypeScript: strict, no any. Type-only imports are required (verbatimModuleSyntax).
• Comments: minimal, and about why. Don't narrate what the code already says.
• Async: always async/await
• Exports: named only, no defaults
• Files: PascalCase.tsx for components, kebab-case.ts for everything else
• Prettier: single quotes in JS, double in JSX, semicolons, trailing commas, 120 cols

Imports

Order: types → external → workspace → relative.

import type { User } from 'types';
import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { useClient } from 'hooks/useClient';
import { formatDate } from 'helpers/formatters';
import { useWebsites } from '../useWebsites';

In app code import types from 'types', which re-exports the database types. Only server and database code imports from officerdb/types directly.

Functions

Arrow functions for one-liners, regular functions for anything with real logic. No multiline parameter lists — extract a params type instead.

type ProcessDataParams = { body: Record<string, unknown> | undefined; query: Record<string, string> };
export function processData({ body, query }: ProcessDataParams): Result { ... }

Components and hooks

type ExperimentCardProps = { experiment: Experiment; onSelect: (id: number) => void };

export const ExperimentCard = ({ experiment, onSelect }: ExperimentCardProps) => { ... };

Complex hooks return objects; simple state hooks return as const tuples. Event parameters are always named ev, never e.

API calls

useClient() returns typed verbs — client.get<Foo>('/foo') really does return Foo, so pass the type parameter and let inference flow from it.

Working With Me

• Ask first — confirm the approach before a significant change
• Explore thoroughly — read the related files before editing
• Keep it simple — no over-engineering, no premature abstraction
• Be explicit — no magic, no implicit behaviour
• Stay focused — note unrelated problems, don't fix them uninvited
• Report honestly — say what you verified and what you didn't

Commit messages: simple lowercase, no prefixes.

Frontend route conventions (apply to EVERY new dashboard route)

Worked examples: /soulseek, /music, /chat.

• Workspace/Panel framework, always — never a standalone single screen. The screen renders <WorkspaceView workspace={ws} locked /> where ws = useDashboardState<LayoutNode>('screens/<name>', defaultLayout), guarded by a normalizeLayout that pins appTypes to an allow-list. Panels are windowed apps under src/workspaces/officerdev/src/apps/<Feature>/, each exporting appRegistryMetas ({ key, name, icon, component, availableOnPanel: false }) and registered in AppRegistry.tsx. Panels coordinate via usePanelChannel.
• Page title by route. Add a rule to RULES in src/apps/officer-web/state/usePageTitle.ts ({ match: (p) => p.startsWith('/<name>'), title: '<Name>' }, most-specific first); usePageTitleSync does the rest.

Further Reading

• CONVENTIONS.md — component organisation, state management, React patterns, with rationale
• TODO.md — current direction and deferred work; takes precedence over this file where they disagree
• src/apps/CLAUDE.md — shared frontend patterns
• src/databases/CLAUDE.md — database patterns

The other markdown files in the repo root (OFFICERDEV_*.md, MARKETING_WEBSITE.md, PHONE_APP.md, SECURITY_AUDIT.md, SETUP_*.md, …) are older design notes. Treat the code as the source of truth.