> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osschat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Workflows

> Day-to-day contributor workflows for OpenChat.

# 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

<Steps>
  <Step title="UI change">
    Update components/hooks in `apps/web/src/components` and `apps/web/src/hooks`.
  </Step>

  <Step title="Backend change">
    Add or update Convex functions in `apps/server/convex`.
  </Step>

  <Step title="Schema change">
    Update `apps/server/convex/schema.ts`, then run:

    ```bash theme={null}
    bun x convex codegen
    ```
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    bun check
    bun check-types
    bun test
    ```
  </Step>
</Steps>

## 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.

## Related Docs

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run OpenChat locally from scratch
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/introduction">
    Validate endpoint-level contracts
  </Card>

  <Card title="Environment variables" icon="gear" href="/self-hosting/environment">
    Confirm deployment prerequisites
  </Card>
</CardGroup>