Skip to content

🚀 Getting Started

This guide will help you get your local development environment set up and running.

🛠️ Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js: v24 or higher (LTS recommended)
  • pnpm: v10 or higher
  • Git: For version control
  • Docker: Optional (required for "Production Mirror" mode)

📥 Installation

  1. Clone the repository:
git clone https://github.com/chitrank2050/zerotoone-assignment.git
cd audience-builder
  1. Run the Setup Script: This project features a one-click bootstrap command that installs dependencies, generates Prisma clients, and applies database migrations.
pnpm run setup

⚙️ Environment Configuration

You must configure the environment variables for the backend to function correctly.

  1. Navigate to the backend directory:
cd apps/backend
  1. Create a .env file (you can copy .env.example if it exists):
DATABASE_URL="postgresql://user:password@neon-host.neon.tech/audience_builder?sslmode=require"
JWT_SECRET="your-high-entropy-secret"
GROQ_API_KEY="your-groq-console-api-key"
PORT=3000

🏃 Running the Application

Local Development Mode

This mode provides the fastest feedback loop with Instant HMR (Hot Module Replacement).

# From the project root
pnpm dev

Production Mirror Mode (Docker)

To verify how the application behaves in a containerized environment:

# Build and start containers
pnpm docker:build

# Stop containers
pnpm docker:down

🗄️ Database Management

We use PostgreSQL (Neon) and Prisma. For local development, you can either use a local PostgreSQL instance or a free tier project on Neon.tech.

[!TIP] Neon Setup: When using Neon, ensure your DATABASE_URL includes ?sslmode=require.

  • View Data: Use Prisma Studio to inspect your database visually.
cd apps/backend
pnpm dlx prisma studio
  • Seeding: To populate the database with initial taxonomy data:
pnpm run db:seed

🧪 Testing

Run the full test suite across the monorepo:

pnpm test

For interactive testing in watch mode:

pnpm test:watch

📖 Documentation

The project documentation is managed with MkDocs.

# Install mkdocs-material
pip install mkdocs-material

# Start local server
mkdocs serve

The documentation will be available at http://localhost:8000.