> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feedback-ai.futureflow-tech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Guide

> Local development setup and best practices for FeedbackAI

<Info>
  **Prerequisites**:

  * Node.js version 18 or higher
  * npm or yarn package manager
  * MongoDB database
  * ngrok for webhook development
</Info>

Complete guide for setting up FeedbackAI development environment and workflow.

## Development Workflow

<Steps>
  <Step title="Clone and Setup">
    ```bash theme={null}
    git clone https://github.com/your-org/feedback-ai.git
    cd feedback-ai
    npm install
    ```
  </Step>

  <Step title="Environment Configuration">
    Create a `.env` file with required environment variables:

    ```bash theme={null}
    # 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"
    ```
  </Step>

  <Step title="Database Setup">
    Initialize your database with Prisma:

    ```bash theme={null}
    npx prisma generate
    npx prisma db push
    ```

    Optionally seed with test data:

    ```bash theme={null}
    npx prisma db seed  # if seed script exists
    ```
  </Step>

  <Step title="Start Development">
    Start the development server:

    ```bash theme={null}
    npm run dev
    ```

    The application will be available at `http://localhost:3000`.
  </Step>
</Steps>

## Webhook Development

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

### Setting up ngrok

```bash theme={null}
# 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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Database Connection Issues">
    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
  </Accordion>

  <Accordion title="Authentication Not Working">
    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
  </Accordion>

  <Accordion title="AI Features Not Working">
    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
  </Accordion>

  <Accordion title="Code Editor Issues">
    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
  </Accordion>
</AccordionGroup>

## Environment Variables Reference

Complete list of environment variables needed for development:

```bash theme={null}
# 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"
```