# Code Documentation

This file is the practical code map for Claw3D contributors.

Use it alongside `README.md` for setup and `ARCHITECTURE.md` for system boundaries. This document is intentionally more hands-on: where code lives, which files matter first, and how to extend the main systems without fighting the current structure.

## Repo Mental Model

Claw3D is the UI and local Studio/proxy layer around an existing OpenClaw Gateway.

- OpenClaw owns agent execution, sessions, tools, config, and runtime events.
- Claw3D owns visualization, local Studio settings, UI workflows, office rendering, and the same-origin WebSocket/API bridge.
- When a feature needs authoritative runtime state, prefer Gateway data over local UI state.
- When a feature is only a local preference, it usually belongs in Studio settings.
- Before publishing new bundled assets or vendored code, also update `THIRD_PARTY_ASSETS.md` or `THIRD_PARTY_CODE.md`.

## Top-Level Code Map

### `src/app`

Next.js App Router entry points and API routes.

- Route pages such as `src/app/office/page.tsx` and `src/app/office/builder/page.tsx` are composition roots.
- `src/app/api/*` contains server-side boundaries for Studio settings, gateway-backed helpers, office flows, and path suggestions.
- Keep heavy feature logic out of route files when possible. Route files should mostly compose feature modules and server boundaries.

### `src/features`

Vertical slices for UI and feature-specific state.

- `src/features/agents`: fleet UI, chat, approvals, runtime event workflows, hydration, history sync, and settings-related operations.
- `src/features/office`: office screens, panels, builder surfaces, standup/GitHub/voice flows, and office-facing hooks.
- `src/features/retro-office`: the immersive React Three Fiber office runtime, including 3D objects, navigation, persistence, scene systems, and actor behavior.

When you are changing a user-facing workflow, start in `src/features` before reaching for `src/lib`.

### `src/lib`

Shared domain logic, adapters, and pure helpers.

- `src/lib/gateway`: the browser gateway client and session-key helpers.
- `src/lib/office`: office intent parsing, animation trigger derivation, desk monitor helpers, janitor reset logic, builder schema, and related office domain code.
- `src/lib/studio`: local Studio settings persistence and the client coordinator.
- Other areas such as `text`, `cron`, `skills`, `ssh`, and `avatars` hold reusable cross-feature logic.

If a module is reused by more than one feature or represents a stable domain contract, it probably belongs in `src/lib`.

### `server`

Custom Studio server and WebSocket proxy.

- `server/index.js` boots the app.
- `server/gateway-proxy.js` bridges browser WebSocket traffic to the upstream OpenClaw Gateway.
- `server/studio-settings.js` loads the local Studio gateway settings on the server side.

This layer exists so gateway credentials stay server-side and browser traffic can always target the same-origin Studio server.

### `tests`

Automated coverage.

- `tests/unit`: the main source of regression coverage.
- Playwright covers end-to-end behavior from the app boundary.

For architecture-sensitive changes, read the nearest unit tests before editing the implementation.

### `scripts`

Repository utilities and generated-asset workflows.

- `scripts/sync-openclaw-gateway-client.ts` updates the vendored gateway client helpers.
- `scripts/studio-setup.js` prepares common local Studio prerequisites.

## Read These First

If you are new to the codebase, this order gives the fastest payoff:

1. `README.md`.
2. `ARCHITECTURE.md`.
3. `src/app/office/page.tsx`.
4. `src/features/office/screens/OfficeScreen.tsx`.
5. `src/features/agents/state/gatewayRuntimeEventHandler.ts`.
6. `src/features/agents/state/runtimeEventCoordinatorWorkflow.ts`.
7. `src/lib/office/eventTriggers.ts`.
8. `src/lib/office/deskDirectives.ts`.
9. `src/features/retro-office/RetroOffice3D.tsx`.
10. `src/features/retro-office/core/navigation.ts`.

## Main Runtime Flow

At a high level:

1. The browser connects to Studio at `/api/gateway/ws`.
2. Studio proxies that connection to the upstream OpenClaw Gateway.
3. `GatewayClient` receives runtime events.
4. `src/app/office/page.tsx` installs the main runtime subscription.
5. `gatewayRuntimeEventHandler.ts` classifies and routes runtime events.
6. Runtime workflow modules plan state updates and effect commands.
7. History sync pulls canonical `chat.history` when live streams are incomplete or transport-specific.
8. Agent UI and office UI both consume the resulting agent/session state.

Important runtime files:

- `src/lib/gateway/GatewayClient.ts`: transport contract and session-key helpers.
- `src/features/agents/state/gatewayRuntimeEventHandler.ts`: runtime event orchestrator.
- `src/features/agents/state/runtimeChatEventWorkflow.ts`: chat stream planning.
- `src/features/agents/state/runtimeAgentEventWorkflow.ts`: agent/lifecycle stream planning.
- `src/features/agents/state/runtimeTerminalWorkflow.ts`: terminal and closed-run handling.
- `src/features/agents/state/runtimeEventCoordinatorWorkflow.ts`: reducer/effect bridge for runtime commands.
- `src/features/agents/operations/historySyncOperation.ts`: canonical history reconciliation.
- `src/features/agents/state/transcript.ts`: transcript entry model and history merge logic.

## Office Architecture

There are two office-related stacks in this repository:

- The immersive live office at `/office`, powered by React Three Fiber and `src/features/retro-office`.
- The builder/editor stack at `/office/builder`, powered by Phaser and `src/features/office`.

These systems are related, but they are not the same runtime.

### Immersive Office Stack

Key files:

- `src/features/office/screens/OfficeScreen.tsx`: office composition root. It connects gateway state, debug/export tools, standup state, desk assignment persistence, and the 3D scene.
- `src/lib/office/eventTriggers.ts`: derives office animation/interaction holds from runtime events and agent transcript state.
- `src/lib/office/deskDirectives.ts`: parses user text into a unified office intent snapshot.
- `src/features/retro-office/RetroOffice3D.tsx`: renders the 3D world and consumes the derived animation state.
- `src/features/retro-office/core/navigation.ts`: builds nav grids, resolves destinations, and exports specialized route helpers.
- `src/features/retro-office/core/furnitureDefaults.ts`: default room/object layout plus migration-style ensure helpers.

### Builder Stack

Key files:

- `src/features/office/components/OfficeBuilderPanel.tsx`.
- `src/features/office/components/OfficePhaserCanvas.tsx`.
- `src/features/office/phaser/OfficeBuilderScene.ts`.
- `src/features/office/phaser/OfficeViewerScene.ts`.
- `src/lib/office/schema.ts`.

The builder uses the `OfficeMap` schema. The immersive retro office still has its own furniture/defaults/persistence pipeline. When touching office code, confirm which stack you are actually changing.

## Office Intent Layer

`src/lib/office/deskDirectives.ts` is the single entry point for natural-language office directives.

This is one of the most important conventions in the repo:

- New room or behavior triggers should be parsed here first.
- Runtime events from Telegram, WhatsApp, UI chat, or other transport-specific sessions should not require separate directive parsers.
- Consumers should prefer `resolveOfficeIntentSnapshot()` over adding one-off regex checks elsewhere.

Current intent categories include:

- Desk holds and releases.
- GitHub or server-room review holds.
- Gym commands and skill-building gym intents.
- QA lab holds and releases.
- Standup meeting requests.

If you add another room or action, first ask: can it be expressed as another field in `OfficeIntentSnapshot`?

## How Office Motion Works

Office motion is derived, not pushed directly into the scene.

1. Runtime events arrive from the gateway.
2. `reduceOfficeAnimationTriggerEvent()` records immediate latches such as working, streaming, thinking, and fresh user directives.
3. `reconcileOfficeAnimationTriggerState()` re-derives durable holds from current agent state and transcript history.
4. `buildOfficeAnimationState()` collapses the trigger state into the smaller shape consumed by the scene.
5. `RetroOffice3D` turns that state into concrete destinations, paths, overlays, and temporary actors.

This separation is important because it keeps transport-specific runtime details out of the 3D scene.

## How To Add A New 3D Object

For a new static or interactive object:

1. Add geometry and footprint rules in `src/features/retro-office/core/geometry.ts` if the object needs sizing, bounds, snapping, or rotation support.
2. Add default placement in `src/features/retro-office/core/furnitureDefaults.ts` if the object should exist in the default office.
3. Add rendering support in one of:
   - `src/features/retro-office/objects/furniture.tsx`.
   - `src/features/retro-office/objects/primitives.tsx`.
   - `src/features/retro-office/objects/machines.tsx`.
   - Another focused object file if the object family deserves its own module.
4. Wire the item type into the `RetroOffice3D.tsx` render switch if needed.
5. If the object affects navigation, add its type to the blocking/target logic in `src/features/retro-office/core/navigation.ts`.

Good examples:

- Server-room objects in `src/features/retro-office/objects/machines.tsx`.
- Environment primitives in `src/features/retro-office/objects/primitives.tsx`.

## How To Add A New Room Or Activity

For a new room that agents can intentionally visit:

1. Add room objects and defaults in `src/features/retro-office/core/furnitureDefaults.ts`.
2. Add navigation targets in `src/features/retro-office/core/navigation.ts`.
3. If the room needs staged entry behavior, add a dedicated helper under `src/features/retro-office/core/navigation/`.
4. Extend `OfficeIntentSnapshot` in `src/lib/office/deskDirectives.ts`.
5. Update `src/lib/office/eventTriggers.ts` so the new intent becomes a derived hold or request.
6. Update `RetroOffice3D.tsx` so `useAgentTick()` maps that hold to a real target and interaction state.
7. Add or update unit tests around the new intent and trigger behavior.

Current examples to follow:

- `navigation/gymRoute.ts`.
- `navigation/serverRoomRoute.ts`.
- `navigation/qaLabRoute.ts`.
- `tests/unit/deskDirectives.test.ts`.
- `tests/unit/officeEventTriggers.test.ts`.

## How Desk Assignment Works

Desk ownership is explicit now.

- Desk assignments are stored in Studio settings, not inferred sequentially.
- `OfficeScreen.tsx` loads and persists `deskAssignmentByDeskUid`.
- `RetroOffice3D.tsx` resolves assigned desk indexes from those persisted mappings.
- Unassigned agents are intentionally safe and should not wander to random desks.

If you change desk semantics, make sure the Studio settings contract and the retro-office consumer stay aligned.

## API Route Inventory

Current `src/app/api` routes:

- `studio/route.ts`: load and patch local Studio settings.
- `path-suggestions/route.ts`: local filesystem path suggestions.
- `office/route.ts`: office layout/builder persistence.
- `office/publish/route.ts`: publish office maps.
- `office/github/route.ts`: GitHub-related office flow helpers.
- `office/browser-preview/route.ts`: browser preview helpers for office experiences.
- `office/presence/route.ts`: office presence/state helpers.
- `office/voice/transcribe/route.ts`: voice transcription.
- `office/voice/reply/route.ts`: voice reply generation.
- `office/standup/config/route.ts`: standup config persistence.
- `office/standup/meeting/route.ts`: standup meeting state helpers.
- `office/standup/run/route.ts`: standup run execution.
- `gateway/media/route.ts`: gateway-backed media access.
- `gateway/agent-state/route.ts`: gateway-backed agent state operations.
- `gateway/skills/remove/route.ts`: gateway-backed skill removal flow.

When adding a new API route, keep it narrow and put shared business logic in `src/lib` or a feature operation module instead of the route handler itself.

## Scripts Worth Knowing

- `npm run dev`: starts the Studio dev server.
- `npm run build`: production build.
- `npm run start`: production server.
- `npm run lint`: ESLint.
- `npm run typecheck`: TypeScript without emit.
- `npm run test`: Vitest.
- `npm run e2e`: Playwright.
- `npm run studio:setup`: local Studio prerequisites.
- `npm run sync:gateway-client`: sync the vendored gateway browser client.
- `npm run smoke:dev-server`: basic dev-server smoke check.

## Testing Map

Start with the tests closest to the subsystem you are touching.

Useful examples:

- `tests/unit/deskDirectives.test.ts`: office intent parsing.
- `tests/unit/officeEventTriggers.test.ts`: office trigger derivation.
- `tests/unit/janitorActors.test.ts` and `tests/unit/janitorReset.test.ts`: janitor and reset cues.
- `tests/unit/gatewayRuntimeEventHandler.chat.test.ts`.
- `tests/unit/gatewayRuntimeEventHandler.agent.test.ts`.
- `tests/unit/runtimeEventCoordinatorWorkflow.test.ts`.
- `tests/unit/runtimeTerminalWorkflow.test.ts`.
- `tests/unit/historySyncOperation.test.ts`.
- `tests/unit/transcript.test.ts`.
- `tests/unit/studioDeskAssignments.test.ts`.

If you introduce a new intent, route, or runtime reduction rule, add unit coverage in the same area before relying on manual testing.

## Folder Structure Conventions

A few patterns are used repeatedly in the repo:

- Route files in `src/app/*` compose feature modules but should not become the main home for business logic.
- `src/features/<area>/operations` usually contains orchestration logic with side effects.
- `src/features/<area>/state` usually contains reducers, workflow planners, and state models.
- `src/lib/<domain>` usually contains pure helpers, adapters, contracts, and persistence helpers shared across features.
- In `src/features/retro-office/core/navigation/`, each route helper gets its own file when the path logic becomes room-specific.

## Contributor Footguns

- The immersive retro office and the Phaser builder are separate systems. Verify which one you need before editing.
- The Gateway is the source of truth for runtime state. Avoid inventing local parallel state for sessions, runs, or transcripts.
- Studio settings are local and per-workspace/gateway. Use them for UI preferences, desk assignments, and connection details only.
- Transport-specific session keys such as Telegram sessions still need to map back to the correct agent. Reuse session-key helpers instead of writing ad-hoc parsing.
- The immersive retro office now uses procedural furniture geometry instead of bundled third-party model assets.
- This repo is not the OpenClaw runtime. Do not modify upstream OpenClaw source code from here.

## When You Need Upstream OpenClaw Context

Sometimes Claw3D behavior depends on the upstream event contract or session behavior. In those cases:

1. Inspect the relevant client or gateway contract in `src/lib/gateway`.
2. If the answer is not in this repo, inspect your separate local OpenClaw checkout.
3. Apply changes in Claw3D unless the user explicitly asked for upstream OpenClaw work.

## Documentation Philosophy

Keep these docs useful by preferring:

- File paths over vague descriptions.
- Extension points over exhaustive inventories of every component.
- Stable contracts over temporary implementation details.
- Focused inline comments in hard-to-read architecture hotspots instead of comment-heavy code everywhere.