Lumen

An AI-first universal email client — Gmail, Office 365, and IMAP (Yahoo, AOL) in one mobile-ready PWA. Built with Next.js on Vercel.

For developers: the source of truth is CLAUDE.md. Read it first.

---

What you're looking at

A scaffolded project ready for Claude Code to build out against an already-written set of 8 specs. Every architectural rule is documented, every boundary is enforced by a hook, and every feature is broken into a reviewable slice.

CLAUDE.md                 the constitution — read this first
/docs/                    architecture, workflow, coding standards, git workflow
/specs/                   the 8 feature slices (your work queue)
/.claude/                 agents, skills, rules, slash commands, settings.json
/lib/providers/           EmailProvider interface (the architectural spine)
/lib/ai/                  Claude integration — only file importing the SDK
/lib/unified/             unified inbox merge (pure, tested)
/lib/auth/                AES-256-GCM credential encryption
/app/                     Next.js App Router (routes + pages)
/components/              React components
/tests/                   unit, integration, E2E
/prisma/schema.prisma     User, Account, Credential, MessageCache, AiResult

---

System: Agents, Skills, Hooks & Plugins

Product Agents

• TriageAgent: Runs prioritize surface, uses fast model (Haiku), classifies incoming mail.
• DraftingAgent: Runs draft surface, uses capable model (Sonnet), pre-generates 3 tone options on thread open.
• SummaryAgent: Runs summarize surface, uses capable model (Sonnet), per-thread or inbox digest.

Developer Agents / Claude Code

• architect: Owns /specs and /docs/architecture.md. Keeps slices coherent.
• provider-integration: Builds/maintains /lib/providers adapters only.
• ui-component: Builds React components per the design system.
• ai-features: Owns /lib/ai and /api/ai routes.
• test-writer: Writes/maintains unit, integration, E2E tests.
• code-quality: Enforces /docs/coding-standards.md on every diff.
• reviewer: Reviews diffs against architecture/security docs; blocks on violations.

Skills

• provider-adapter: Integration guidelines for adding new EmailProviders.
• spec-authoring: Rules for writing comprehensive markdown feature specs.
• ai-prompt: Best practices for writing robust LLM prompts as pure functions.
• api-route: Guardrails for securing App Router Next.js endpoints.
• pwa-audit: Requirements for offline shell and manifest validity.
• typescript-conventions: Enforcement for strict typing and interface design.
• react-patterns: Patterns for pure components and custom hooks.
• code-review-checklist: Standard checklist enforced before PR merge.

Hooks

• format-and-typecheck: Automatically format code and catch TS errors.
• provider-boundary: Fails build if provider SDKs leak out of /lib/providers.
• unit-tests: Prevents changes that break the core logic suite.
• secret-scan: Strictly scans bundle exports for env leakages.
• full-suite-and-build: Validates full production build pass.
• reviewer-approval-hash: Ensures Claude agent explicit approval is granted.

Plugins

• @ducanh2912/next-pwa
• Vercel
• GitHub
• Playwright

---

How This Was Built

I configured CLAUDE.md not as a style guide but as a behavioral constraint system. Specs-Driven Development is enforced at the instruction level — Claude refuses to write code before a spec exists. Each agent has a narrow, written remit it cannot cross. Mechanical hooks (format, typecheck, secret scan, provider boundary) fire on every file write, so violations are caught before review. I acted as architect and product manager; Claude Code built against the specs I wrote.

---

Quick start

1. Prerequisites

• Node.js ≥ 20
• A Vercel account (free tier is fine)
• Google Cloud project with the Gmail API enabled (for spec 01)
• Microsoft Entra ID app registration (for spec 01)
• A Postgres database — Vercel Postgres / Neon is easiest

2. Install

npm install

3. Configure

cp .env.example .env

Fill in every value in .env.local. The file documents each one. Generate the two secrets like this:

# AUTH_SECRET
openssl rand -base64 32

# TOKEN_ENCRYPTION_KEY (must decode to exactly 32 bytes)
openssl rand -base64 32

4. Database

npx prisma generate
npx prisma migrate dev --name init

5. Run

npm run dev        # http://localhost:3000
npm test           # unit + integration
npm run test:e2e   # Playwright (requires dev server)
npm run typecheck
npm run lint
npm run build

---

Building with Claude Code

The workflow is specs-driven and multi-agent. You drive it with five slash commands:

/project-setup       once, at the start
/spec-list           see all specs and the next recommended one
/spec-execute 01     implement spec 01 end-to-end, open a draft PR
/slice-finish        run code-quality + reviewer, mark PR ready
/spec-status         check progress across the whole project

/bug-report <name>   capture a bug before touching code
/bug-fix <name>      investigate root cause, fix, write regression test
/bug-verify <name>   confirm fix works, check regressions, open PR

Per-slice cycle:

/spec-execute NN  →  draft PR opens
/slice-finish     →  agents review, PR marked ready
gh pr merge --squash  →  you approve and merge

Vercel auto-deploys a preview per PR and production from main. Full rules in /docs/git-workflow.md.

---

Deploying to Vercel

1. vercel link (one time).
2. Add every variable from .env.example to Vercel Project Settings → Environment Variables. Set APP_URL to your Vercel production URL.
3. Add the production callback URLs to your Google + Microsoft OAuth apps: ${APP_URL}/api/accounts/connect/callback/google and ${APP_URL}/api/accounts/connect/callback/microsoft.
4. vercel deploy --prod (or push to main — it auto-deploys).

The pre-deploy hook in .claude/settings.json runs the full test suite and next build before allowing deploy.

---

The 10 specs — all merged ✅

#	Spec	Status	PR
01	Account connection & switching (Gmail, O365, IMAP)	merged	#1
02	Unified inbox (merge, pagination, partial errors)	merged	#2
03	Thread & message view (HTML sanitization, attachments)	merged	#3
04	Compose, reply, reply-all, forward	merged	#4
05	Message actions (labels, archive, delete, bulk)	merged	#5
06	Search (two-tier: cache-first + provider fan-out)	merged	#6
07	AI features (summaries, drafts, prioritization)	merged	#7
08	PWA shell (manifest, service worker, offline queue)	merged	#8
09	UI polish (dark theme, account switcher, starred)	merged	#9
10	File attachments (compose/reply/forward, drag-drop)	merged	#10

Live at YOUR_VERCEL_URL

---

Architecture in one diagram

PWA (Next.js client)
  ↓ same-origin fetch
API routes (server-only — holds all secrets)
  ├── Provider Abstraction (/lib/providers)
  │     EmailProvider interface
  │     ├── GmailProvider
  │     ├── GraphProvider (Office 365)
  │     └── ImapProvider (Yahoo, AOL)
  │           ↓
  │     Gmail API / MS Graph / IMAP+SMTP
  └── AI Layer (/lib/ai)
        prompt builders → callClaude → Anthropic API
        ↓
Postgres (accounts, encrypted creds, MessageCache, AiResult)

Full diagram and rationale in /docs/architecture.md.

---

License

TBD.