Development Workflows

This page maps common engineering tasks to the actual OpenChat architecture.

Monorepo Layout

apps/web: TanStack Start frontend and server routes.
apps/server/convex: Convex schema, queries, mutations, actions.
docs-site in source repo: upstream Mintlify docs source.

Typical Feature Flow

UI change

Update components/hooks in apps/web/src/components and apps/web/src/hooks.

Backend change

Add or update Convex functions in apps/server/convex.

Schema change

Update apps/server/convex/schema.ts, then run:

bun x convex codegen

Validate

bun check
bun check-types
bun test

Feature Ownership Map

Area	Primary files
Chat lifecycle	`use-persistent-chat.ts`, `use-chat-actions.ts`, `messages.ts`
Streaming and resume	`use-chat-streaming.ts`, `streamExecution.ts`, `backgroundStream.ts`
Model catalog	`model.ts`, `api/models.ts`
Provider credentials	`settings-providers.tsx`, `provider-credentials.ts`, `userApiKeys.ts`
Auth	`auth-client.tsx`, `server-auth.ts`, `auth.ts`
Settings	`settings.tsx`, `settings-*.tsx`

Local Debug Tips

Use Convex dashboard for function logs and table inspection.
Verify same-origin and auth token behavior when testing API routes.
For provider credential issues, confirm OPENROUTER_ENCRYPTION_KEY is valid base64 32-byte key.

Quickstart

Run OpenChat locally from scratch

API reference

Validate endpoint-level contracts

Environment variables

Confirm deployment prerequisites

Getting Started

Core Features

Guides

Self-Hosting

Development Workflows

Development Workflows

Monorepo Layout

Typical Feature Flow

Feature Ownership Map

Local Debug Tips

Quickstart

API reference

Environment variables

​Development Workflows

​Monorepo Layout

​Typical Feature Flow

​Feature Ownership Map

​Local Debug Tips

​Related Docs

Quickstart

API reference

Environment variables

Development Workflows

Monorepo Layout

Typical Feature Flow

Feature Ownership Map

Local Debug Tips

Related Docs