Skip to main content
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

1

Clone and Setup

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

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"
3

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
4

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

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

​
API Development

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

​
Testing Workflow

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

​
Troubleshooting

  1. Verify your DATABASE_URL in .env
  2. Ensure MongoDB is running locally or accessible
  3. Check network connectivity for cloud databases
  4. Run npx prisma db push to sync schema
  1. Verify Clerk environment variables are set correctly
  2. Check webhook URL in Clerk dashboard matches ngrok URL
  3. Ensure HTTPS is used for webhook URLs
  4. Check Clerk webhook secret matches .env value
  1. Verify OpenAI API key is valid and has credits
  2. Check API key permissions for the models you’re using
  3. Monitor OpenAI API usage in your dashboard
  4. Check network connectivity to OpenAI services
  1. Clear browser cache and reload
  2. Check browser console for JavaScript errors
  3. Test with different browsers
  4. 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"