Fix: Subscriber Growth (#50)

Author: dcodesdev

CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+LetterSpace is an open source, self-hosted newsletter platform. It's a pnpm monorepo with Turbo for task orchestration.
+
+## Commands
+
+### Development
+
+```bash
+pnpm dev                    # Run all dev servers (Turbo)
+pnpm build                  # Build all projects
+pnpm lint                   # Lint all projects
+pnpm format                 # Format with Prettier
+```
+
+### Backend-specific
+
+```bash
+pnpm --filter backend dev           # Run backend only
+pnpm --filter backend test          # Run tests (Vitest)
+pnpm --filter backend generate      # Prisma codegen
+pnpm --filter backend migrate:dev   # Dev migrations
+```
+
+### Database
+
+```bash
+pnpm --filter backend prisma db seed              # Seed database
+cd apps/backend && pnpm prisma migrate reset --force  # Reset and reseed
+```
+
+### Release Process
+
+```bash
+./scripts/release.sh          # Bumps patch version (default)
+./scripts/release.sh minor    # Bumps minor version
+./scripts/release.sh major    # Bumps major version
+```
+
+The script bumps version in `package.json`, creates a git tag, and pushes it. GitHub Actions builds Docker images and creates a release from `RELEASE_NOTES.md`.
+
+## Architecture
+
+### Monorepo Structure
+
+- `apps/backend` - Express + TRPC backend (Bun/Node.js)
+- `apps/web` - Vite + React dashboard (PWA)
+- `apps/landing-page` - Next.js marketing site
+- `apps/docs` - Nextra documentation
+- `packages/ui` - Shared Shadcn UI components
+- `packages/shared` - Shared TypeScript types
+- `packages/eslint-config` - Shared ESLint config
+
+### Backend Architecture
+
+TRPC routers in `apps/backend/src/router/`:
+- Each domain (user, campaign, subscriber, etc.) has its own directory
+- Pattern: `router.ts` (definition), `mutation.ts` (writes), `query.ts` (reads)
+
+Key entry points:
+- `apps/backend/src/app.ts` - Express app setup, middleware, routes
+- `apps/backend/src/trpc.ts` - TRPC context and auth
+- `apps/backend/src/cron/` - Scheduled jobs (email sending, maintenance)
+
+Endpoints:
+- `/trpc/*` - TRPC RPC endpoints
+- `/api/*` - REST API (Swagger documented)
+- `/t/:id` - Link tracking redirect
+- `/img/:id/img.png` - Email open tracking pixel
+
+### Frontend Architecture
+
+React Router app in `apps/web/src/`:
+- `app.tsx` - Route definitions
+- `pages/` - Page components matching routes
+- TRPC client with React Query for data fetching
+- Token auth via cookies
+
+### Database
+
+Prisma ORM with PostgreSQL. Schema at `apps/backend/prisma/schema.prisma`.
+
+Key models: User, Organization (multi-tenancy), Subscriber, List, Campaign, Template, Webhook.
+
+## Tech Stack
+
+- **Backend**: Express, TRPC, Prisma, PostgreSQL, Bun/Node.js 22+
+- **Frontend**: React 19, Vite, React Router, Shadcn UI, TailwindCSS
+- **Shared**: TypeScript (strict), Zod, React Hook Form
+
+## Code Style
+
+- Adhere to existing code patterns in the codebase
+- Minimal comments
+- Component files: kebab-case (e.g., `user-profile.tsx`)
+- Component exports: PascalCase (e.g., `export const UserProfile`)
+- Colocate types/data with components when only used by that component
+
+## Development Notes
+
+- Email sending is disabled in development (`NODE_ENV=development`) - cron jobs skip and mailer returns mock responses
+- Backend tests use `.env.test` for configuration
+- Webhook transformers run in QuickJS sandbox with configurable memory limits

Dockerfile

@@ -1,7 +1,7 @@
 FROM oven/bun:1
 
 RUN apt-get update -y && apt-get install -y openssl
-RUN bun i -g pnpm@10.10.0
+RUN bun i -g pnpm@10.26.2
 
 WORKDIR /app
 

Dockerfile.node

@@ -1,7 +1,7 @@
 FROM node:22-slim
 
 RUN apt-get update -y && apt-get install -y openssl
-RUN npm install -g pnpm@10.10.0
+RUN npm install -g pnpm@10.26.2
 
 WORKDIR /app
 

RELEASE_NOTES.md

@@ -1,18 +1,9 @@
 ### ✨ Features
 
-- **Webhooks Support** - Receive real-time notifications for email events (delivered, opened, clicked, bounced, complained)
-  - Custom webhook endpoints with authentication and transformation code support
-  - Process email status updates from external email service providers
-  - **Webhook Request Logging** - View detailed logs of all webhook requests with status codes, payloads, responses, and timing information
-- **Complained Message Status** - Track when recipients mark emails as spam
-- **Monaco Code Editor** - Enhanced code editing experience for webhook configuration
-- **Awaiting Webhook Status** - Track when messages are awaiting webhook processing
+- **Migration Scripts** - Added `migrate:dev` and `migrate:deploy` scripts for easier database migration management
+- **Release Script** - Added automated release script (`scripts/release.sh`) for version bumping and tag creation
 
 ### 🐛 Bug Fixes
 
-- Fixed unsubscribe functionality
-
-### 📚 Docs
-
-- Added comprehensive webhook documentation and event reference
-- See the latest documentation at [docs.letterspace.app](https://docs.letterspace.app).
+- Fixed dashboard subscriber growth calculation to properly handle baseline subscriber count
+- Improved seed data distribution - subscribers now distributed over 2 years instead of 12 days for better testing

apps/backend/CLAUDE.md

@@ -0,0 +1,100 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+pnpm dev            # Dev server with watchexec
+pnpm start          # Production server (Bun)
+pnpm build          # Compile TypeScript
+pnpm test           # Run tests (Vitest with .env.test)
+pnpm lint           # ESLint
+pnpm lint:fix       # ESLint with auto-fix
+pnpm generate       # Prisma codegen
+pnpm migrate:dev    # Create/apply dev migrations
+pnpm migrate:deploy # Apply production migrations
+```
+
+### Database
+
+```bash
+pnpm prisma db seed                    # Seed database
+pnpm prisma migrate reset --force      # Reset and reseed
+```
+
+## Architecture
+
+Express + TRPC backend with Prisma ORM. Runs on Bun (or Node.js 22+).
+
+### Key Files
+
+- `src/app.ts` - Express app setup, routes, TRPC middleware
+- `src/trpc.ts` - TRPC context, auth middleware, procedure definitions
+- `src/index.ts` - Server entry point, starts cron jobs
+- `src/shared.ts` - Exports for frontend type sharing
+- `prisma/schema.prisma` - Database schema
+
+### TRPC Router Pattern
+
+Each domain has its own directory with consistent structure:
+
+```
+src/user/
+  router.ts    - Router definition combining queries and mutations
+  query.ts     - Read procedures (authProcedure or publicProcedure)
+  mutation.ts  - Write procedures
+```
+
+Available routers: user, organization, list, subscriber, campaign, template, message, settings, webhook, dashboard, stats
+
+### Procedures
+
+- `publicProcedure` - No auth required
+- `authProcedure` - Requires valid JWT, provides `ctx.user`
+
+### HTTP Endpoints
+
+- `/trpc/*` - TRPC RPC endpoints
+- `/api/*` - REST API (Swagger docs at `/docs`)
+- `/t/:id` - Link tracking redirect (updates click stats)
+- `/img/:id/img.png` - Email open tracking pixel
+- `/webhook/:webhookId` - Webhook handler for external integrations
+- `/*` - Serves frontend SPA static files
+
+### Cron Jobs
+
+Defined in `src/cron/`:
+
+- `sendMessages.ts` - Process queued emails
+- `processQueuedCampaigns.ts` - Handle scheduled campaigns
+- `dailyMaintenance.ts` - Database cleanup
+- `cleanupWebhookLogs.ts` - Remove old webhook logs
+
+Cron jobs are disabled when `NODE_ENV=development`.
+
+### Authentication
+
+JWT-based auth with password versioning:
+
+- Token in `Authorization: Bearer <token>` header
+- `verifyToken()` in `src/utils/auth.ts`
+- Password version (`pwdVersion`) forces re-auth on password change
+
+### Webhook Transformer
+
+Custom JavaScript transformers run in QuickJS sandbox (`src/webhook/transformer.ts`). Memory limits configurable via env vars.
+
+### Email Sending
+
+Nodemailer integration in `src/lib/Mailer.ts`. Returns mock success in development.
+
+### Testing
+
+Vitest with Supertest for API tests. Uses `.env.test` for test database.
+
+```bash
+pnpm test                    # Run all tests
+pnpm test -- --watch         # Watch mode
+pnpm test -- path/to/file    # Single file
+```

apps/backend/package.json

@@ -11,7 +11,9 @@
     "lint:fix": "eslint . --fix",
     "generate": "prisma generate",
     "generate:sql": "prisma generate --sql",
-    "test": "dotenv -e .env.test -- vitest"
+    "test": "dotenv -e .env.test -- vitest",
+    "migrate:dev": "prisma migrate dev",
+    "migrate:deploy": "prisma migrate deploy"
   },
   "exports": {
     ".": "./src/index.ts",

apps/backend/prisma/seed.ts

@@ -57,23 +57,38 @@ async function seed() {
     })
   }
 
-  // Create 5000 subscribers
-  const subscribers = Array.from({ length: 5000 }, (_, i) => ({
-    name: `Subscriber ${i + 1}`,
-    email: `subscriber${i + 1}@example.com`,
-    organizationId: orgId,
-    createdAt: dayjs().subtract(12, "days").toDate(),
-  }))
+  // Create 5000 subscribers distributed over 2 years (from 2 years ago to today)
+  const twoYearsAgo = dayjs().subtract(2, "years")
+  const now = dayjs()
+  const daysInTwoYears = now.diff(twoYearsAgo, "days")
+  const subscribers = Array.from({ length: 5000 }, (_, i) => {
+    const progress = i / (5000 - 1)
+    const createdAt =
+      i === 4999
+        ? now.toDate()
+        : twoYearsAgo
+            .add(Math.floor(progress * daysInTwoYears), "days")
+            .toDate()
+    return {
+      name: `Subscriber ${i + 1}`,
+      email: `subscriber${i + 1}@example.com`,
+      organizationId: orgId,
+      createdAt,
+    }
+  })
   await prisma.subscriber.createMany({
     data: subscribers,
     skipDuplicates: true,
   })
-  // Then 10 more for each day for 10 days
-  const now = new Date()
+  // Then 10 more for each day for 10 days, distributed over 2 years
   for (let d = 0; d < 10; d++) {
-    const day = dayjs(now)
-      .subtract(d + 1, "day")
-      .toDate()
+    const progress = d / 9
+    const day =
+      d === 9
+        ? now.toDate()
+        : twoYearsAgo
+            .add(Math.floor(progress * daysInTwoYears), "days")
+            .toDate()
 
     const dailySubs = Array.from({ length: 10 }, (_, i) => ({
       name: `DailySub ${d + 1}-${i + 1}`,