Project Structure

This template uses a monorepo structure powered by Turborepo, with clear separation between frontend, backend, and agent code.

Overview

just-use-convex/
├── apps/
│   └── web/                    # TanStack Start frontend (React 19)
├── packages/
│   ├── agent/                  # Cloudflare Workers AI agent
│   │   └── src/
│   │       ├── agent/          # AgentWorker, ConvexAdapter, prompts
│   │       └── tools/          # Sandbox tools, web search, ask-user
│   ├── backend/
│   │   └── convex/             # Convex backend
│   ├── config/                 # Shared TypeScript config
│   └── env/                    # T3 Env type-safe env vars
├── turbo.json                  # Turborepo configuration
└── package.json                # Root workspace config

Frontend (`apps/web`)

The frontend is built with TanStack Start and React 19:

apps/web/src/
├── routes/                     # File-based TanStack Router
│   ├── (protected)/            # Auth-required routes
│   │   ├── chats/              # Chat list + detail views
│   │   ├── dashboard.tsx       # Org dashboard
│   │   └── settings/           # Org/team management
│   ├── (public)/               # Public routes
│   │   ├── auth.tsx            # Auth page
│   │   └── docs/               # Documentation routes
│   └── api/                    # API routes (auth handlers)
├── components/                 # React components
│   ├── ui/                     # shadcn/ui components
│   ├── chat/                   # ChatInput, MessageList, MessageItems, ModelSelector
│   ├── sandboxes/              # Sandbox UI, file explorer, terminal
│   ├── todos/                  # Todo components
│   ├── dashboard/              # Dashboard components
│   ├── auth/                   # Auth components
│   └── ai-elements/            # AI-specific visual components
├── hooks/                      # Custom React hooks
│   ├── use-chat.ts             # Agent chat instance management
│   ├── use-chats.ts            # Chat CRUD + pagination
│   ├── use-sandbox.ts          # Sandbox PTY, file explorer, SSH
│   ├── use-sandboxes.ts        # Sandbox CRUD + pagination
│   ├── use-todos.ts            # Todo CRUD + assignment
│   ├── use-attachments.ts      # File upload with progress
│   ├── use-openrouter-models.ts # Model listing + caching
│   ├── use-model-filtering.ts  # Fuzzy search + favorites
│   ├── use-paginated-query.ts  # Pagination type helpers
│   └── auth/                   # Auth/org/user hooks
├── providers/                  # Context providers
│   └── agent.tsx               # Isolated React roots per chat connection
├── store/                      # Jotai atoms
│   ├── chat-settings.ts        # Model, reasoning effort, modalities
│   └── favorite-models.ts      # Persisted model favorites
└── lib/                        # Utilities, motion presets

Backend (`packages/backend/convex`)

The Convex backend contains all server-side logic:

packages/backend/convex/
├── schema.ts                   # Ent schema (6 tables)
├── functions.ts                # zQuery/zMutation/zExternal* factories + triggers
├── tables/                     # Entity definitions
│   ├── chats.ts                # Chat entity + indexes
│   ├── sandboxes.ts            # Sandbox entity + Daytona trigger
│   ├── todos.ts                # Todo entity
│   ├── todoAssignedMembers.ts  # Junction table
│   ├── globalAttachments.ts    # Org-wide attachments
│   └── orgMemberAttachments.ts # Per-member attachments
├── chats/                      # Chat module (CRUD, search, stats)
├── sandboxes/                  # Sandbox module (CRUD, Daytona lifecycle)
├── todos/                      # Todo module (CRUD, assignment)
├── lib/                        # ConvexAdapter, auth helpers
├── betterAuth/                 # Better Auth integration
└── shared/                     # Shared utilities

Agent (`packages/agent`)

The Cloudflare Workers AI agent handles chat interactions, tool use, and sandbox orchestration:

packages/agent/
├── alchemy.run.ts              # Alchemy IaC (DurableObject, Vectorize, secrets)
└── src/
    ├── index.ts                # Worker entry point + CORS
    ├── agent/
    │   ├── worker.ts           # AgentWorker (AIChatAgent + PlanAgent)
    │   ├── convexAdapter.ts    # Convex HTTP client for agent
    │   └── prompts/            # System + task prompts
    └── tools/
        ├── sandbox/            # File ops, PTY terminal, code interpreter
        ├── web-search.ts       # Exa neural search
        └── ask-user.ts         # Structured user questions

Shared Packages

`packages/config`

Shared TypeScript configuration for the monorepo.

`packages/env`

Centralized environment variable management with T3 Env type-safe validation.

Module Pattern

Each backend feature follows a consistent pattern:

feature/
├── index.ts        # Exported queries/mutations (public API)
├── functions.ts    # Business logic implementation
├── types.ts        # Zod schemas for args
├── aggregates.ts   # TableAggregate definitions
└── stats.ts        # Statistics queries using aggregates

This separation keeps code organized and makes it easy to find related functionality.

Key Files Explained

`schema.ts`

Defines the database schema using Convex Ents with 6 tables and their relationships (chats, sandboxes, todos, assigned members, and two attachment tables).

`functions.ts`

Creates typed query/mutation factories with automatic auth injection and trigger registration:

zQuery / zMutation - Standard authenticated queries and mutations
zExternalQuery / zExternalMutation - For external service calls (e.g., agent)
zInternalQuery / zInternalMutation - Internal-only operations

Each factory injects the authenticated user context and Ent table access.

`alchemy.run.ts`

Defines the Cloudflare infrastructure using Alchemy IaC:

DurableObject - AgentWorker for persistent WebSocket chat state
Vectorize index - RAG-ready message embeddings
Secrets - API keys and connection strings

Project Structure

On this page