Development Guide

Prerequisites:

Node.js version 18 or higher
npm or yarn package manager
MongoDB database
ngrok for webhook development

Complete guide for setting up FeedbackAI development environment and workflow.

Development Workflow

Clone and Setup

git clone https://github.com/your-org/feedback-ai.git
cd feedback-ai
npm install

Environment Configuration

Create a .env file with required environment variables:

# Database
DATABASE_URL="mongodb://localhost:27017/feedback-ai"

# OpenAI
OPENAI_API_KEY="sk-your-key-here"

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."
CLERK_WEBHOOK_SECRET="whsec_..."

# Development
NODE_ENV="development"
NEXT_PUBLIC_API_URL="http://localhost:3000/api"

Database Setup

Initialize your database with Prisma:

npx prisma generate
npx prisma db push

Optionally seed with test data:

npx prisma db seed  # if seed script exists

Start Development

Start the development server:

npm run dev

The application will be available at http://localhost:3000.

Webhook Development

For features requiring webhooks (Clerk authentication, etc.), use ngrok:

Setting up ngrok

# Install ngrok globally
npm install -g ngrok

# Start ngrok tunnel
ngrok http 3000

Update Webhook URLs

Copy the HTTPS URL from ngrok and update:

Clerk Dashboard: Set webhook URL to https://your-ngrok-url.ngrok.io/api/webhooks/clerk
Update any other webhook endpoints in your external services

Available Scripts

FeedbackAI includes several npm scripts for development:

# Development
npm run dev          # Start development server with Turbopack
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint

# Database
npx prisma studio    # Open Prisma Studio database GUI
npx prisma db push   # Push schema changes to database
npx prisma generate  # Generate Prisma client

Project Structure

Understanding the codebase organization:

src/
├── app/                 # Next.js App Router
│   ├── api/            # API Routes
│   ├── auth/           # Authentication pages
│   ├── admin/          # Admin dashboard
│   ├── question-sets/  # Question management
│   └── test-results/   # Results viewing
├── components/         # React components
│   ├── code-exercise/  # Code editor components
│   ├── test/          # Test management UI
│   ├── shared/        # Shared components
│   └── ui/            # Base UI components
├── services/          # Business logic
│   ├── client/        # Client-side services
│   └── db/            # Database services
├── lib/               # Utilities and configuration
└── types/             # TypeScript definitions

Development Best Practices

Code Formatting

We recommend these VSCode extensions:

ESLint: For code linting and error detection
Prettier: For code formatting
Prisma: For database schema syntax highlighting
TypeScript: Built-in TypeScript support

Database Development

Schema Changes: Always use Prisma migrations for schema changes
Seeding: Create seed scripts for consistent test data
Studio: Use npx prisma studio for database inspection

API Development

Type Safety: Use TypeScript interfaces for API requests/responses
Error Handling: Implement consistent error handling patterns
Authentication: Test with different user roles (Admin, Interviewer, Candidate)

Testing Workflow

Manual Testing: Test all user roles and permissions
AI Features: Ensure OpenAI API key is working for AI evaluations
Webhooks: Test webhook integrations with ngrok
Code Editor: Test the CodeMirror integration with different programming languages

Troubleshooting

Database Connection Issues

Verify your DATABASE_URL in .env
Ensure MongoDB is running locally or accessible
Check network connectivity for cloud databases
Run npx prisma db push to sync schema

Authentication Not Working

Verify Clerk environment variables are set correctly
Check webhook URL in Clerk dashboard matches ngrok URL
Ensure HTTPS is used for webhook URLs
Check Clerk webhook secret matches .env value

AI Features Not Working

Verify OpenAI API key is valid and has credits
Check API key permissions for the models you’re using
Monitor OpenAI API usage in your dashboard
Check network connectivity to OpenAI services

Code Editor Issues

Clear browser cache and reload
Check browser console for JavaScript errors
Test with different browsers
Verify CodeMirror themes and modes are loading

Environment Variables Reference

Complete list of environment variables needed for development:

# Required
DATABASE_URL="mongodb://..."
OPENAI_API_KEY="sk-..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..."
CLERK_SECRET_KEY="sk_..."
CLERK_WEBHOOK_SECRET="whsec_..."

# Optional
NODE_ENV="development"
NEXT_PUBLIC_API_URL="http://localhost:3000/api"

Getting started

Core Features

Architecture

Development Tools

Development Workflow

Webhook Development

Setting up ngrok

Update Webhook URLs

Available Scripts

Project Structure

Development Best Practices

Code Formatting

Database Development

API Development

Testing Workflow

Troubleshooting

Environment Variables Reference

​Development Workflow

​Webhook Development

​Setting up ngrok

​Update Webhook URLs

​Available Scripts

​Project Structure

​Development Best Practices

​Code Formatting

​Database Development

​API Development

​Testing Workflow

​Troubleshooting

​Environment Variables Reference

Development Workflow

Webhook Development

Setting up ngrok

Update Webhook URLs

Available Scripts

Project Structure

Development Best Practices

Code Formatting

Database Development

API Development

Testing Workflow

Troubleshooting

Environment Variables Reference