---
id: TASK-2
title: Wire Convex data and storage foundations
status: In Progress
assignee: []
created_date: '2026-06-03 19:12'
updated_date: '2026-06-04 07:55'
labels:
  - mvp
  - backend
  - convex
dependencies:
  - TASK-1
references:
  - PRD.md
priority: high
ordinal: 2000
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Configure Convex Cloud for the MVP and define the core persistence model for campaigns, leads, audits, outreach records, blacklist entries, run logs, and screenshot/file storage. The goal is a typed backend foundation that can support the dashboard, agent pipeline, and public audit pages.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Convex is connected to the Next.js app with generated types available
- [x] #2 Core tables exist for campaigns, leads, audits, outreach, blacklist, run logs, and settings metadata
- [x] #3 Convex File Storage is ready for desktop and mobile screenshots
- [x] #4 Run-status and error-log concepts are represented so background jobs are observable
- [x] #5 No API keys or secrets are stored in user-editable database records
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
1. Preserve existing Convex env/setup and install the Convex package if missing.
2. Use TDD for shared Convex domain constants and secret-key guards.
3. Define the Convex schema, indexes, storage metadata, and bounded functions.
4. Wire the Next.js App Router root through a Convex client provider.
5. Verify with pnpm test, pnpm lint, Convex generation, and pnpm build.
6. Check acceptance criteria after verification, but do not mark Done until user confirmation.
<!-- SECTION:PLAN:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Started implementation on branch codex-task-2-convex-foundations. Existing .env.local Convex values and generated AI guidance will be preserved.

Verified TASK-2 acceptance criteria with pnpm test, pnpm lint, pnpm exec convex codegen --dry-run --typecheck enable, pnpm dlx convex dev --once, and pnpm build. Subagent spec review found no compliance issues. Code-quality review findings were addressed for slug uniqueness, safe settings listing, structured payloads, normalized list limits, generated lint ignores, and Convex tsconfig. Residual risk: public Convex functions remain unauthenticated until TASK-3 adds Better Auth, so deployment should remain internal/non-public until auth is wired.
<!-- SECTION:NOTES:END -->