A high-performance, principal-grade monorepo for AI-driven advertising segmentation.
For detailed guides and API references, please see the docs/ directory:
- System Architecture: High-level overview and tech stack.
- Getting Started: Installation and setup guide.
- Deployment Guide: Instructions for Render & Vercel.
- Development Workflow: Standards, hygiene, and testing.
- API Documentation: RESTful API reference and endpoints.
┌────────────────────────────────────────────────────────────────────────────┐
│ AI Audience Builder Production Engine │
│ │
│ Dashboard: https://zerotoone-assignment-frontend.vercel.app │
│ API Root: https://zerotoone-assignment.onrender.com/api/v1 │
│ Docs: https://zerotoone-assignment.onrender.com/api/v1/docs │
│ Health: https://zerotoone-assignment.onrender.com/api/v1/health │
└────────────────────────────────────────────────────────────────────────────┘
Note
Cold Start Alert: The backend is hosted on the Render Free Tier. If the service has been inactive, the first request may take 30-50 seconds to spin up. Please be patient during the initial load!
The AI Audience Builder is a high-rigor, spec-driven monorepo designed for maximum type safety and development velocity. It leverages a Modular Monolith backend and a reactive React 19 frontend, synchronized via a unified contracts package.
- Systems Grade (
apps/backend): Built to the same high-rigor standards as Meterplex. It features a modular monolith architecture, PostgreSQL persistence, and Groq-powered (LLaMA 3.3) signal extraction. - UX Grade (
apps/frontend): Real-time reactive dashboard with React Router v7 and persistent chat states. - Contract Grade (
packages/shared): The single source of truth for all cross-boundary DTOs and machine-readable error keys.
Tip
Engineering Hygiene: This project enforces strict branch and commit standards using git-hygiene, an in-house tool designed for high-performance engineering teams.
This monorepo uses an in-house "Ground Truth" package: @audience-builder/shared.
Important
Zero-Drift Enforcement: To prevent runtime errors, the Frontend and Backend do not define their own DTOs or Error Keys. They strictly import them from the shared package.
- Location:
packages/shared - Hygiene: Whenever you modify a shared interface, you must run
pnpm buildfrom the root to synchronize the workspace.
Important
The Consent Handshake: This platform implements strict AI governance. All audience segments generated by the Groq engine must be manually validated by a Planner or Admin before being committed to production targeting.
[!TIP]
Zero-Drift Architecture: Any change to the shared contracts requires a full workspace build (pnpm build). This ensures that your IDE and runtime never suffer from stale type definitions.
Built for production-grade troubleshooting:
- Correlation IDs: Every request is assigned a unique
x-correlation-id, tracing the lifecycle from frontend to backend logs. - Performance Logging: Real-time request monitoring with millisecond-precision timing and status-code color coding.
Before starting the system, ensure you have a .env file in apps/backend/ with the following configuration:
| Variable | Description | Example |
|---|---|---|
DATABASE_URL |
Neon PostgreSQL URI | postgresql://user:pass@host/db |
JWT_SECRET |
Secret key for auth tokens | your-high-entropy-secret |
GROQ_API_KEY |
Groq Console API Key | gsk_... |
ALLOWED_ORIGINS |
CORS Allowed Origins | https://zerotoone-assignment-frontend.vercel.app |
PORT |
Backend service port | 3000 |
This monorepo supports two distinct execution modes. Choose the one that fits your current task.
Best for active coding with Instant HMR and native debugging. Ensure you have a local PostgreSQL instance running.
# 1. One-click bootstrap (Install + Generate + Migrate)
pnpm run setup
# 2. Start all services in parallel watch mode
pnpm devBest for verifying deployment readiness, networking, and volume persistence in a containerized environment.
# Build and start the entire stack in Docker
pnpm docker:build
# View real-time service logs
pnpm docker:logs| Command | Scope | Description |
|---|---|---|
pnpm run setup |
Root | One-click bootstrap: Install + Generate + Deploy |
pnpm dev |
Root | Starts all apps in parallel watch mode |
pnpm build |
Root | Performs a full build of all packages |
pnpm check-types |
Root | Runs strict TypeScript validation across the workspace |
pnpm lint |
Root | Runs ESLint + Markdownlint quality gates |
pnpm format |
Root | Formats all code & documentation via Prettier |
pnpm nuke |
Root | Cleans node_modules and performs fresh install |
| Command | Scope | Description |
|---|---|---|
pnpm test |
Root | Runs all unit tests across the workspace |
pnpm test:watch |
Root | Runs tests in interactive watch mode |
pnpm test:e2e |
Backend | Runs full End-to-End integration suite |
pnpm test:cov |
Root | Generates workspace-wide coverage report |
| Command | Scope | Description |
|---|---|---|
pnpm db:generate |
Backend | Regenerates the Prisma client for all packages |
pnpm db:migrate |
Backend | Create a new migration for schema changes |
pnpm db:deploy |
Backend | Applies migrations non-interactively (used in setup) |
pnpm db:seed |
Backend | Hydrates PostgreSQL with targeting taxonomies |
pnpm db:reset |
Backend | Destructive: Wipes and recreates the database |
| Command | Scope | Description |
|---|---|---|
pnpm docker:up |
Infrastructure | Starts containerized services in background |
pnpm docker:build |
Infrastructure | Rebuilds and starts containers (Production Mirror) |
pnpm docker:down |
Infrastructure | Stops and removes all containers |
pnpm docker:logs |
Infrastructure | Follows real-time service logs |
This project uses Material for MkDocs for beautiful, searchable documentation.
We maintain high engineering standards through automated GitHub Actions:
- Docs Deploy: Automatically updates the documentation site on push to
main.
❤️ Developed by Chitrank Agnihotri