Skip to main content

​
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

1

UI change

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

Backend change

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

Schema change

Update apps/server/convex/schema.ts, then run:
bun x convex codegen
4

Validate

bun check
bun check-types
bun test

​
Feature Ownership Map

AreaPrimary files
Chat lifecycleuse-persistent-chat.ts, use-chat-actions.ts, messages.ts
Streaming and resumeuse-chat-streaming.ts, streamExecution.ts, backgroundStream.ts
Model catalogmodel.ts, api/models.ts
Provider credentialssettings-providers.tsx, provider-credentials.ts, userApiKeys.ts
Authauth-client.tsx, server-auth.ts, auth.ts
Settingssettings.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