# BulkMailer Pro

A premium corporate SaaS bulk email platform with user authentication, license gating, admin panel, Telegram alerts, and multi-provider email delivery with automatic failover.

## Run & Operate

- `pnpm --filter @workspace/api-server run dev` — run the API server (port 8080 → proxied at /api)
- `pnpm --filter @workspace/bulkmailer-pro run dev` — run the frontend (proxied at /)
- `pnpm run typecheck` — full typecheck across all packages
- `pnpm --filter @workspace/api-spec run codegen` — regenerate API hooks and Zod schemas from the OpenAPI spec
- `pnpm --filter @workspace/db run push` — push DB schema changes (dev only)
- Required env: `DATABASE_URL` — Postgres connection string
- Required env: `SESSION_SECRET` — Secret for cookie encryption

## Stack

- pnpm workspaces, Node.js 24, TypeScript 5.9
- API: Express 5 (artifacts/api-server)
- Frontend: React 19 + Vite + Tailwind CSS v4 + shadcn/ui (artifacts/bulkmailer-pro)
- DB: PostgreSQL + Drizzle ORM
- Validation: Zod (zod/v4), drizzle-zod
- API codegen: Orval (from OpenAPI spec)
- Build: esbuild (CJS bundle)
- Email: Resend / SendGrid / Mailgun REST APIs with auto-failover

## Where things live

- `lib/api-spec/openapi.yaml` — single source of truth for all API contracts
- `lib/db/src/schema/` — DB schema tables (users, sessions, credentials, payments, email_logs, settings, reset_tokens)
- `artifacts/api-server/src/routes/` — Express route handlers (auth, admin, user, mailer, payments, settings)
- `artifacts/api-server/src/lib/` — Server libs: auth (session cookies), crypto (AES-256 key encryption), mailer (Resend/SendGrid/Mailgun), telegram (bot alerts), settings (DB-backed config)
- `artifacts/bulkmailer-pro/src/pages/` — All frontend pages (user + admin)
- `artifacts/bulkmailer-pro/src/contexts/AuthContext.tsx` — User and admin auth state

## Architecture decisions

- Session tokens: 96-char hex via `crypto.randomBytes(48)` stored in httpOnly cookies — no JWTs
- API keys are encrypted with AES-256-CBC before DB storage using SESSION_SECRET-derived key
- Admin auth uses a separate `admin_token` cookie and separate session rows (`isAdmin = "true"`)
- Auto-failover: if primary email provider fails, the backend retries with the user's secondary credentials
- Batch throttling: 1–2 second random delays between email sends to reduce spam scoring
- Settings stored as key-value rows in `settings` table with DB-backed defaults

## Product

- **User flow**: Register → Dashboard (see license status) → Billing (submit USDT payment) → Admin approves → License activates → Use email composer
- **Admin flow**: `/admin` → password `ValidAdmin2026!` → manage users, approve payments, configure wallet/pricing/Telegram
- **Mailer**: 3-column compose UI — fields + recipients textarea + body + live delivery log
- **Telegram alerts**: Fired on payment submissions and password reset requests to admin chat

## User preferences

_Populate as you build — explicit user instructions worth remembering across sessions._

## Gotchas

- Provider values must be lowercase (`resend`, `sendgrid`, `mailgun`) — frontend select values match this
- Admin password defaults to `ValidAdmin2026!` — override with `ADMIN_PASSWORD` env var
- `SESSION_SECRET` is required for API key encryption — fails hard if missing
- Run `pnpm run typecheck:libs` after any `lib/*` schema change before checking artifact packages

## Pointers

- See the `pnpm-workspace` skill for workspace structure, TypeScript setup, and package details