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

# Development

> Running sevvo locally.

These notes target contributors working inside the sevvo monorepo. If you
are just deploying the agent in your environment, see
[Deploying the agent](/deploying-the-agent) instead.

## Stack

* **Package manager:** `pnpm` 9.15.9 (pinned in `package.json`).
* **Development orchestrator:** [Tilt](https://tilt.dev/).
* **Node:** 20+.
* **Workspaces:** `apps/*` and `packages/*` (see `pnpm-workspace.yaml`).

## Layout

| Path           | What it is                                                  |
| -------------- | ----------------------------------------------------------- |
| `apps/web/`    | Control-plane UI. TanStack Start + Vite SPA.                |
| `apps/agent/`  | Data-plane agent. NestJS + Temporal worker + Prisma.        |
| `apps/docs/`   | This Mintlify site.                                         |
| `packages/db/` | Convex control-plane backend (queries, mutations, actions). |
| `packages/ui/` | Shared shadcn component library.                            |

## Setup

```bash theme={null}
pnpm install
```

The agent's Prisma client is generated automatically in a postinstall hook.
Install [Tilt](https://docs.tilt.dev/install.html), the
[Temporal CLI](https://docs.temporal.io/cli), and PostgreSQL 17 before starting
the full development environment. Tilt stores the local Postgres cluster and
Temporal database under the ignored `.tilt/` directory.

## Running everything

From the repo root:

```bash theme={null}
pnpm dev
```

This opens Tilt and starts the web app, Convex, the agent, and the agent's local
Postgres and Temporal dependencies as separate resources. Tilt initializes the
databases, applies Prisma migrations, shows each service's logs, and reports
readiness for the long-running services. The docs site is available as a manual
Tilt resource, or can be run directly when editing docs:

```bash theme={null}
pnpm --filter @sevvo/docs preview
```

## Running a single app

```bash theme={null}
pnpm --filter web dev
pnpm --filter agent dev
pnpm --filter @sevvo/docs preview
```

## Agent credentials

See [Deploying the agent → Environment variables](/deploying-the-agent#environment-variables)
for the full list. For local dev, provision a `SEVVO_AGENT_TOKEN` and configure
`SEVVO_INTERNAL_CONTROL_PLANE_URL` and `SEVVO_INTERNAL_AUTH_BASE_URL` in
`apps/agent/.env.local`. Tilt supplies Postgres on port `55432` and Temporal on
port `7233`; use these local values:

```dotenv theme={null}
SEVVO_AGENT_DATABASE_URL=postgresql://postgres@127.0.0.1:55432/postgres?sslmode=disable
SEVVO_TEMPORAL_ADDRESS=localhost:7233
SEVVO_TEMPORAL_NAMESPACE=default
```

## Shared checks

```bash theme={null}
pnpm typecheck
pnpm lint
pnpm format
```

Each runs across all workspaces via pnpm's recursive workspace runner.

## Adding shadcn components

**Never hand-author shadcn primitives.** Use the CLI so files pick up the
repo's customized `base-luma` style, Tailwind v4 tokens, Hugeicons, and
menu color conventions:

```bash theme={null}
# Shared primitives (most cases)
cd packages/ui && pnpm dlx shadcn@latest add <component>

# App-only components
cd apps/web && pnpm dlx shadcn@latest add <component>
```

## Adding a docs page

1. Create `<slug>.mdx` in `apps/docs/` with frontmatter:
   ```mdx theme={null}
   ---
   title: "Page title"
   description: "One-line description for SEO and sidebar."
   ---
   ```
2. Add the slug (no extension) to the appropriate `pages` array in
   `apps/docs/docs.json`.
3. Preview with `pnpm --filter @sevvo/docs preview`.
4. Run `pnpm --filter @sevvo/docs check` to catch broken links.