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

# Development

> Learn how to develop and contribute to hans.ai

## Project Structure

hans.ai is built as a monorepo using Turborepo, with the following structure:

```
notify-me/
├── apps/
│   ├── web/          # Next.js web application
│   └── docs/         # Mintlify documentation
├── packages/         # Shared packages (future)
├── turbo.json        # Turborepo configuration
└── package.json      # Root workspace configuration
```

## Technology Stack

### Frontend

* **Next.js 15** - React framework with App Router
* **TypeScript** - Type-safe development
* **Tailwind CSS** - Utility-first CSS framework
* **Zustand** - State management
* **Radix UI** - Accessible component primitives

### Backend

* **Next.js API Routes** - API endpoints
* **Prisma** - Database ORM
* **PostgreSQL** - Primary database
* **Better Auth** - Authentication system
* **Resend** - Email service
* **OpenAI** - AI-powered features

### Infrastructure

* **Turborepo** - Monorepo management
* **Vercel** - Deployment platform
* **Stagehand** - Browser automation

## Development Commands

### Root Commands (Monorepo)

```bash theme={null}
# Install dependencies
yarn install

# Run all apps in development
yarn dev

# Build all apps
yarn build

# Run linting
yarn lint

# Format code
yarn format
```

### Web App Commands

Navigate to `apps/web` or use turbo from root:

```bash theme={null}
# Database commands
yarn db:migrate    # Run migrations
yarn db:generate   # Generate Prisma client
yarn db:push      # Push schema changes
yarn db:studio    # Open Prisma Studio
yarn db:seed      # Seed database

# Development
yarn dev          # Start dev server with cron
yarn dev:server   # Start only Next.js server
yarn dev:cron     # Start only cron jobs
```

## Environment Variables

Create a `.env.local` file in `apps/web`:

```env theme={null}
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/notify_me"

# Authentication
BETTER_AUTH_SECRET="generate-a-secure-random-string"
BETTER_AUTH_URL="http://localhost:3010"

# Email Service
RESEND_API_KEY="re_xxxxxxxxxxxxx"
EMAIL_FROM="notifications@yourdomain.com"

# OpenAI
OPENAI_API_KEY="sk-xxxxxxxxxxxxx"

# Polar (Payments)
POLAR_API_KEY="polar_xxxxxxxxxxxxx"
NEXT_PUBLIC_POLAR_CHECKOUT_LINK="https://buy.polar.sh/..."

# Stagehand (Browser Automation)
STAGEHAND_API_KEY="optional-api-key"
```

## Database Schema

The application uses Prisma with PostgreSQL. Key models include:

* **User** - User accounts and authentication
* **NotificationTask** - Monitoring configurations
* **Action** - Notification actions (email, webhook)
* **TaskExecution** - Execution history
* **EvaluationResult** - Evaluation outcomes

## Testing

### Running Tests

```bash theme={null}
# Run all tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run E2E tests
yarn test:e2e
```

### Writing Tests

Place test files next to the code they test:

```
src/
├── components/
│   ├── Button.tsx
│   └── Button.test.tsx
└── lib/
    ├── utils.ts
    └── utils.test.ts
```

## Code Style

The project uses:

* **ESLint** for linting
* **Prettier** for formatting
* **TypeScript** strict mode

### Git Hooks

Pre-commit hooks ensure code quality:

* Format with Prettier
* Lint with ESLint
* Type check with TypeScript

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure all tests pass
6. Submit a pull request

## Debugging

### VS Code Configuration

`.vscode/launch.json`:

```json theme={null}
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev:server"],
      "cwd": "${workspaceFolder}/apps/web",
      "env": {
        "NODE_OPTIONS": "--inspect"
      }
    }
  ]
}
```

### Common Issues

<AccordionGroup>
  <Accordion title="Database connection errors">
    Ensure PostgreSQL is running and `DATABASE_URL` is correct:

    ```bash theme={null}
    # Check PostgreSQL status
    pg_isready

    # Test connection
    psql $DATABASE_URL
    ```
  </Accordion>

  <Accordion title="Prisma client not generated">
    Regenerate the Prisma client: `bash yarn db:generate `
  </Accordion>

  <Accordion title="Port already in use">
    The dev server runs on port 3010. Kill the process:

    ```bash theme={null}
    lsof -i :3010
    kill -9 <PID>
    ```
  </Accordion>
</AccordionGroup>