aetherfield

Aetherfield is a B2B sustainability-intelligence platform that helps companies track, model, report, and act on emissions data. It addresses the gap between scattered, manual ESG data and operational insight by turning sustainability from an annual reporting exercise into a continuous practice. The repository contains both a prerendered marketing site and the authenticated platform in a single Next.js App Router application with no separate backend service. Key features include: - **Marketing site**: Seven public routes (homepage, journal, articles, careers, job listings, about, design system) with content as typed constants. Public write paths for demo requests, double opt-in newsletter signup, and job applications with private CV upload, all rate-limited and bot-protected. - **Platform**: Multi-tenant organisations with membership and invitations, CSV activity import with staged rows, published and customer-supplied emission factor sets (DEFRA 2025/2026 seeded), date-effective factor selection, scope 1/2/3 calculation engine (location-based and market-based scope 2), target tracking with projections, generated ESG reports, and three nightly cron jobs for recalculation, threshold alerts, and retention purges. - **AI integration**: One module drafts narrative prose for ESG reports via the Vercel AI Gateway. The LLM never produces numbers; all arithmetic is deterministic in pure functions. Generated narratives are checked token-by-token against a closed allowlist of computed figures, and drafts failing the check are discarded. Only rendered, rounded report sections are sent to the provider. **Tech stack**: Next.js 16.2.12 (App Router, Turbopack), React 19.2.4, TypeScript 5, Tailwind CSS 4 (config-less), Neon Postgres with node-postgres, Drizzle ORM, Better Auth (self-hosted), Resend + React Email, Upstash Redis rate limiting, Vercel Blob (private), BotID bot protection, Zod validation, GSAP and Motion for animations, AI SDK, Vitest and Playwright for testing. **Architecture**: Layered with UI, Server Actions (only mutation path), Route Handlers (external callers only), Data layer (lib/db), and Domain layer (pure functions). The UI never mutates through Route Handlers; every mutation authorises and validates server-side. Public forms follow a consistent path: client validation, BotID check, rate limiting, server-side Zod validation, authorisation, database write, and email notification (failure never fails the write). **Getting started**: Requires Node.js 20+, a Neon Postgres database (pooled and direct connection strings), and optionally the Vercel CLI. Setup involves copying .env.example, running migrations, and seeding conversion factors. There is no local-database mode. **Testing**: Vitest is scoped to lib/domain (pure functions only). Playwright covers Chromium, Firefox, and WebKit against a production build, with WebKit in a rootless Podman container for reproducibility. **Personal data handling**: CVs stored in private blob storage with signed URLs, double opt-in newsletter, no logging of request bodies/emails/CVs, finite retention with nightly purge, and real organisation deletion. **Deployment**: Vercel Fluid Compute with Node.js runtime. Three nightly crons declared in vercel.json. Neon scale-to-zero cold starts are expected. **Documentation**: AGENTS.md is the contributor contract; docs/ contains per-surface build records; prompts/ holds the numbered implementation prompts that built the repository.