Repo map

OpenDot keeps the current product surfaces close together while preserving clear internal boundaries. Start with the smallest area that matches your change, then follow the linked docs when your work crosses into runtime, database, or device contracts. Use Contribution areas to choose the track and maturity level first. Use this page after that when you need files, boundaries, and verification commands.

Top-level layout

Path	What lives there	Contributor notes
`docs/`	Mintlify docs, docs navigation, logos, diagrams	Keep setup docs practical and cross-link changed behavior
`platform/`	React console, Fastify API, voice runtime, Drizzle schema	Main app surface for agents, pipeline config, browser tests, devices, settings
`dot-device/firmware/`	ESP-IDF firmware for the Dot device prototype	Use firmware build guidance before changing device behavior
`containers/`	Dockerfiles and Nginx config for local/deployed platform services	Keep service env contracts aligned with `.env.example` and docs
`.agents/`	Shared agent instructions and reusable workflows	Update only for durable repo-wide agent guidance
`assets/`	Brand and README assets	Preserve the existing OpenDot mark
Root docs	`README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `ROADMAP.md`	Keep project framing and contribution guidance consistent

Platform internals

Surface	Key files	What to check
UI shell and navigation	`platform/src/App.tsx`, `platform/src/pages/**`	Page state, selected identity/device behavior, loading/error states
API client and cache	`platform/src/lib/platformApi.ts`, `platform/src/lib/queryClient.ts`	Request shape, auth token behavior, TanStack Query invalidation
Pipeline defaults	`platform/src/lib/pipeline.ts`, `platform/src/types.ts`	VAD/STT/LLM/TTS stage settings and normalization
Control API	`platform/src/server/api.ts`	Auth, agents, devices, settings, deployments, runtime token verification
Database	`platform/src/server/db/schema.ts`, `platform/drizzle/`	Schema, migrations, indexes, versioned agent/pipeline data
Runtime	`platform/src/server/runtime.js`	Browser `/voice`, device `/ws`, OTA proxy, Sandwich orchestration, Realtime bridge

The platform architecture direction is captured in platform/platform-architecture.md. The docs architecture summary is at Platform architecture.

Runtime and device contracts

The runtime exposes:

GET  /health
POST /ota/
POST /ota/activate
POST /realtime/client-secret
WS   /voice
WS   /ws

The platform API owns:

/api/auth/*
/api/platform-state
/api/agents
/api/dot-devices
/api/device-activations/claim
/api/runtime/voice-sessions
/api/settings
/api/api-keys
/api/internal/*

Treat /api/internal/* as runtime-to-platform trust boundaries. They depend on OPENDOT_RUNTIME_INTERNAL_SECRET and should not become browser-facing APIs.

Verification by change type

Change	Run
Docs only	`pnpm run format:check -- docs` and `mint broken-links` from `docs/`
Platform UI/API/runtime	`pnpm run lint && pnpm run test && pnpm run build`
Database contract	Platform checks plus migration review and Drizzle Studio inspection when useful
Firmware	`idf.py build` from `dot-device/firmware/` when ESP-IDF is available
Root docs	spelling/link review plus `git diff --check`

Use Contributing for the first-time contributor workflow, Roadmap for sequencing, and Runtime configuration when service URLs or environment variables change.

Getting started

Understand OpenDot

Console workflow

Operate and deploy

Contributing

Top-level layout

Platform internals

Runtime and device contracts

Verification by change type

​Top-level layout

​Platform internals

​Runtime and device contracts

​Verification by change type

Top-level layout

Platform internals

Runtime and device contracts

Verification by change type