zeref

Zeref is a research and approval platform designed to investigate, draft, review, and publish data with a strict human-in-the-loop workflow. Every outbound action is gated behind an approval step, ensuring controlled automation. The project is structured as a TypeScript monorepo using npm workspaces, featuring a Next.js control room UI, background Node job runners, and PostgreSQL with pgvector for data storage. It leverages Playwright for browser automation to snapshot data from configured sources, followed by a typed pipeline for normalization and embedding. The architecture emphasizes snapshot immutability, contracts-first design with shared JSON shapes, and a BFF pattern where the browser communicates with Next.js API routes rather than raw workers. AI components are mockable via environment flags for CI testing without live keys. The repository includes phase-gated verification scripts, Docker Compose for local development, and a demo mode using fixtures for college presentations or testing without live Instagram or LLM credentials. Key components include the cockpit UI for live status and calendar management, a studio for content creation, and a research intel module. The project supports remote agents and cloud tracks, with comprehensive documentation for setup and demo execution.