docs: expand CLAUDE.md with stack and architecture guidance

[Fusion-Data-Company]

Summary

• Replace the single-line @AGENTS.md include with a comprehensive guide for future Claude Code sessions.
• Document the stack (Next.js 16 / React 19 / Drizzle / Neon / Clerk / Tailwind v4) and the available scripts, including the absence of a test suite.
• Spell out the multi-tenant pattern (every query must scope by tenantId derived from tenantUsers), the src/proxy.ts middleware location (Next 16 rename from middleware.ts), the route-group split between (marketing) and (app), and the public-route allowlist.
• Describe the two Vercel cron jobs (daily-sends and sports-monitor), their schedules, and how scheduledSends flows between them.
• Cover the per-tenant LLM provider layer in src/lib/llm/ and the strict SUBJECT: / BODY: prompt contract.
• Capture frontend conventions: design tokens in globals.css, glass component wrappers, TanStack Query defaults, and the CSV import flow.

Keeps the existing @AGENTS.md import at the top so the "this is not the Next.js you know" warning still applies.

Test plan

• Skim CLAUDE.md and confirm the architecture descriptions match the code.
• Verify the listed env vars and commands match what's actually used in deployment.

https://claude.ai/code/session_01RWwj6MBq4avB5PZiZWXja3

---

Generated by Claude Code

Summary by Sourcery

Documentation:

• Expand CLAUDE.md into a detailed guide covering tech stack, commands, env vars, multi-tenant architecture, routing, database schema, cron jobs, LLM layer, frontend conventions, and CSV import flow while retaining the existing @AGENTS.md include.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
rapport	Ready	Preview, Comment	May 8, 2026 10:25pm

[sourcery-ai]

Reviewer's Guide

Expands CLAUDE.md from a simple @AGENTS.md include into a detailed architecture and conventions guide for Claude Code, documenting the stack, commands, env vars, multi-tenancy, routing, middleware, database, cron jobs, LLM layer, frontend patterns, and CSV import flow while keeping the original include at the top.

Sequence diagram for sports-monitor and daily-sends cron pipeline

sequenceDiagram
  participant VC as VercelCron
  participant SM as api/cron/sports-monitor
  participant DS as api/cron/daily-sends
  participant DB as NeonDB
  participant LLM as generateEmailContent
  participant RES as Resend
  participant ESPN as ESPNScoreboard

  VC->>SM: HTTP POST /api/cron/sports-monitor
  SM->>SM: Validate CRON_SECRET bearer token
  SM->>ESPN: Fetch completed games
  ESPN-->>SM: Scoreboard JSON
  SM->>DB: Upsert sportsEvents
  SM->>DB: Find fans via contactSportsTeams
  SM->>DB: Check sportsNotificationsSent (7-day window)
  SM->>DB: Insert scheduledSends for tomorrow
  SM->>DB: Insert sportsNotificationsSent rows
  SM-->>VC: 200 OK

  VC->>DS: HTTP POST /api/cron/daily-sends
  DS->>DS: Validate CRON_SECRET bearer token
  DS->>DB: Find contacts with birthdays/anniversaries today
  DS->>DB: Load scheduledSends for today
  loop For each scheduledSend
    DS->>DB: Load tenantEmailConfig, tenantLlmConfig, cardTemplates
    DS->>LLM: generateEmailContent(tenantConfig, contact, context)
    LLM-->>DS: SUBJECT: ... BODY: ...
    DS->>RES: Send email(subject, body, template)
    RES-->>DS: Delivery response
    DS->>DB: Update scheduledSends.status (sent/failed)
  end
  DS-->>VC: 200 OK

Loading

File-Level Changes

Change	Details	Files
Expand CLAUDE.md into a comprehensive repo and architecture guide for Claude Code sessions while preserving the existing @AGENTS.md include.	Keep the existing @AGENTS.md include at the top of the file so the preexisting warning still applies. Add a high-level description of CLAUDE.md’s purpose as guidance for Claude Code when working in this repository. Document the application stack, including framework versions, libraries, and notable integrations used across the codebase.	CLAUDE.md
Document development commands, Drizzle workflows, and the absence of tests.	List core npm scripts for dev, build, start, and lint, with notes on eslint configuration. Describe how to run Drizzle migrations and studio directly via drizzle-kit commands without npm wrappers. Explicitly state that there is no test suite and that npm test commands should not be invented.	CLAUDE.md
Capture configuration requirements and environment variables used in runtime and deployment.	List required env vars for database, Clerk, cron auth, LLM fallback, Resend fallback, and optional ElevenLabs integration. Clarify how Clerk routes and redirects are wired (sign-in, sign-up, onboarding). Note that env-based fallbacks are used when per-tenant configuration rows are missing.	CLAUDE.md
Describe the multi-tenant data-access pattern and routing layout, including route groups and auth behavior.	Explain the tenantUsers mapping from Clerk userId to tenantId and the standard pattern to resolve tenantId in server code. Emphasize that all queries and mutations must be manually scoped by tenantId, since there is no database-level RLS. Outline the App Router route groups for marketing vs app, the onboarding and auth routes, and the behavior of API routes including cron endpoints.	CLAUDE.md
Clarify middleware placement and public-route handling under Next.js 16’s proxy file convention.	Explain that middleware lives in src/proxy.ts instead of middleware.ts due to Next 16 changes. Describe how Clerk middleware defines the public route allowlist and protects all other routes. Specify redirect behavior for authenticated users hitting marketing pages and the need to update isPublicRoute when adding public endpoints.	CLAUDE.md
Summarize the database schema organization and key domain tables relevant to core features.	Describe how schema.ts and drizzle.config.ts define the single source of truth and how db and tables are imported. Highlight the contacts domain model, including Harvey Mackay 66 fields and related child tables. Document the roles of cardTemplates, scheduledSends, and tenant-specific configuration tables, including the current non-encrypted storage of API keys.	CLAUDE.md
Detail the two Vercel cron jobs and how scheduledSends flows between them.	Describe the daily-sends cron schedule, how it finds relevant contacts and scheduledSends, generates email content, and sends via Resend. Describe the sports-monitor cron schedule, how it ingests ESPN data, identifies fans, rate-limits notifications, and queues scheduledSends rows. Provide guidance for adding new cron jobs, including route placement, vercel.json registration, and CRON_SECRET gating.	CLAUDE.md
Explain the per-tenant LLM abstraction and strict SUBJECT/BODY prompt contract.	Document generateEmailContent’s role as the single entry point for generated email copy and its provider/model resolution behavior. Note the use of OpenAI SDK with configurable baseURL to support multiple LLM providers. Emphasize the strict SUBJECT: / BODY: output format and parsing behavior, and advise keeping prompt edits minimal while preserving this contract.	CLAUDE.md
Capture frontend conventions for styling, components, data fetching, and the Paige/CSV flows.	Describe design tokens in globals.css, Tailwind color mirroring, and preferred use of CSS variables and named colors over ad-hoc hex values. List key utility classes and glass UI components, typography choices, and motion conventions, encouraging reuse over reimplementation. Explain TanStack Query defaults, contacts table/slide-out interaction patterns, the ElevenLabs Paige widget integration, and the CSV import pipeline from client-side parsing to bulk API ingestion.	CLAUDE.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.