Sendable is an AI-assisted outbound sales platform: campaigns, prospect research, and personalized email sequences, delivered through a real-time web app.
This repository is a Turborepo monorepo managed with pnpm workspaces.
Status: Early-stage.
apps/webis the only implemented application.apps/apiis planned and currently an empty scaffold — see Repository Layout.
sendable-monorepo/
├── apps/
│ ├── web/ # Next.js 16 (App Router) + Convex — implemented
│ └── api/ # FastAPI (Python) — planned, not yet implemented
├── docs/ # Canonical architecture & feature reference
├── CLAUDE.md # Guidance for AI coding agents working in this repo
├── AGENTS.md # Agent-facing task graph / conventions
├── DESIGN.md # Design system spec (colors, type, layout)
├── turbo.json # Turborepo task pipeline
└── pnpm-workspace.yaml # Workspace package globs (apps/*, packages/*)
| App | Role | Database | Status |
|---|---|---|---|
apps/web |
Next.js frontend + Convex backend (product UI, auth, realtime data) | Convex | ✅ Implemented |
apps/api |
FastAPI service for AI agents, prospect research, long-running jobs | Neon PostgreSQL | 🚧 Planned |
Architectural rule: Next.js never talks to Neon directly. Neon is only accessed by the FastAPI service, which writes results back into Convex via HTTP actions. See docs/architecture.md for the full system design.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), React, Tailwind CSS v4, shadcn/ui, Framer Motion |
| Backend / DB | Convex (serverless functions + realtime DB) |
| Auth | Better Auth (running inside Convex), optional GitHub/Google/Slack OAuth |
| Resend (production) or Nodemailer/SMTP (local dev, e.g. Mailpit) | |
| Forms & Validation | React Hook Form + Zod |
| Agent backend (planned) | FastAPI (Python 3.12) + Neon PostgreSQL |
| Monorepo tooling | Turborepo, pnpm workspaces |
- Node.js v20+
- pnpm v10.17.1 (pinned via the
packageManagerfield — use Corepack to match it automatically) - A Convex account (convex.dev) — free tier is sufficient for development
- (Optional) A Resend account for production email, or a local SMTP server such as Mailpit for dev
corepack enable
corepack prepare pnpm@10.17.1 --activate# 1. Install dependencies for all workspaces
pnpm install
# 2. Configure environment variables
cp apps/web/.env.example apps/web/.env.local
# fill in the values — see apps/web/.env.example for full documentation of each variable
# 3. Start development (Next.js + Convex + build watcher)
pnpm devThe first run of pnpm dev triggers Convex's predev hook, which provisions your Convex deployment via npx convex dev --skip-push. Follow the CLI prompts to log in / create a project, then set the remaining environment variables on the Convex dashboard (Settings → Environment Variables) in addition to apps/web/.env.local — Convex actions don't read .env.local.
The app runs at https://localhost:3000 (HTTPS is enabled in dev via --experimental-https).
Run from the repo root — Turborepo filters each task to the workspaces that define it:
pnpm dev # Start Next.js + Convex (+ build watcher) in parallel
pnpm build # Production build
pnpm typecheck # Type-check src/ and convex/
pnpm lint # ESLint over src/ and convex/
pnpm format # Prettier — write
pnpm format:check # Prettier — check (used in CI)There is currently no automated test suite. pnpm typecheck and pnpm lint are the primary correctness gates, both enforced in CI.
To run a command against a single workspace, use Turborepo's filter flag, e.g. pnpm turbo run build --filter=@sendable/web.
Environment variables must be set in two places for apps/web:
apps/web/.env.local— read by Next.js at build/runtime- Convex dashboard (Settings → Environment Variables) — read by Convex actions/mutations (auth, email, OAuth)
See apps/web/.env.example for the complete, documented list. Key variables:
| Variable | Where | Purpose |
|---|---|---|
CONVEX_DEPLOYMENT |
.env.local |
Set automatically by npx convex dev |
NEXT_PUBLIC_CONVEX_URL |
Both | Convex cloud deployment URL |
NEXT_PUBLIC_CONVEX_SITE_URL |
Both | Convex HTTP Actions URL (used by Better Auth, OAuth callbacks) |
SITE_URL / NEXT_PUBLIC_SITE_URL |
Both | Must match your deployment URL — affects auth origins and email links |
BETTER_AUTH_SECRET |
Convex | openssl rand -base64 32 |
EMAIL_PROVIDER |
.env.local |
resend (default) or smtp |
RESEND_API_KEY |
Convex | Required if EMAIL_PROVIDER=resend |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
Convex | Only if Google OAuth is enabled |
The docs/ directory is the canonical reference for architecture and planned features — read it before making significant changes:
docs/architecture.md— full system design, the Convex/FastAPI split, agent architecture, ADRsdocs/features.md— every feature by page, with Convex/FastAPI ownership called outdocs/api-contracts.md— HTTP contract betweenapps/weband the plannedapps/apidocs/db-structure.md— Convex schema (product state) and Neon PostgreSQL schema (agent data)
Other root-level docs:
CLAUDE.md/AGENTS.md— instructions for AI coding agents working in this repoDESIGN.md— design system specification (color palette, typography, layout principles)apps/web/README.md— detailed setup and project structure for the Next.js/Convex appCONTRIBUTING.md— branching model, commit conventions, PR process, coding standards
See CONTRIBUTING.md for the branching model (main → develop → feature/*), commit message conventions (Conventional Commits), and PR process. In short:
- Branch from
developusingfeature/,fix/,docs/,refactor/,test/, orchore/prefixes - Run
pnpm lint,pnpm typecheck, andpnpm format:checkbefore opening a PR - Open the PR against
develop— CI runs lint, typecheck, build, and format checks
GitHub Actions (.github/workflows/ci.yml) runs on every push/PR:
- Lint & Type Check — ESLint +
tsc - Build — full production build (requires Convex secrets configured as repo secrets)
- Format Check — Prettier
CodeQL security scanning and dependency review also run automatically (see .github/workflows/).