Skip to main content
These notes target contributors working inside the sevvo monorepo. If you are just deploying the agent in your environment, see Deploying the agent instead.

​
Stack

  • Package manager: pnpm 9.15.9 (pinned in package.json).
  • Task runner: turbo.
  • Node: 20+.
  • Workspaces: apps/* and packages/* (see pnpm-workspace.yaml).

​
Layout

PathWhat 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

pnpm install
The agent’s Prisma client is generated automatically in a postinstall hook.

​
Running everything

From the repo root: 
pnpm dev
This starts the web app, the agent, and Convex in parallel via turbo. The docs site is not in the default dev pipeline — run it explicitly when editing docs: 
pnpm --filter @sevvo/docs preview

​
Running a single app

pnpm --filter web dev
pnpm --filter agent dev
pnpm --filter @sevvo/docs preview

​
Agent prerequisites

See Deploying the agent → Environment variables for the full list. For local dev, provision a SEVVO_AGENT_TOKEN, point SEVVO_INTERNAL_CONTROL_PLANE_URL at the local Convex/control-plane endpoint, and set SEVVO_AGENT_DATABASE_URL to a local Postgres database.

​
Shared checks

pnpm typecheck
pnpm lint
pnpm format
Each runs across all workspaces via turbo.

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