# Contributing to Plunk

Thank you for your interest in contributing to Plunk! This guide will help you get started with development.

## Architecture

Plunk V2 is built as a modern Turborepo monorepo with the following structure:

### Applications (`apps/`)

- **api**: Express.js API server with background worker process (BullMQ)
- **web**: Next.js dashboard application (app.useplunk.com)
- **landing**: Next.js marketing site (www.useplunk.com)
- **wiki**: Next.js documentation site (docs.useplunk.com)

### Shared Packages (`packages/`)

- **@plunk/db**: Prisma database schema and client
- **@plunk/ui**: Shared UI components (ShadCN + Radix UI)
- **@plunk/shared**: Common utilities and business logic
- **@plunk/types**: TypeScript type definitions
- **@plunk/email**: React Email templates

### Technology Stack

- **Frontend**: React 19, Next.js 15, Tailwind CSS, Framer Motion
- **Backend**: Express.js, TypeScript (ESM), Prisma ORM
- **Database**: PostgreSQL with connection pooling
- **Cache/Queue**: Redis, BullMQ for background jobs
- **Email Delivery**: AWS SES with bounce/complaint handling
- **Storage**: S3-compatible (MinIO, AWS S3)
- **Payments**: Stripe with usage-based billing

## Development Setup

For local development without Docker:

### Prerequisites

- Node.js 20+
- Yarn 4.9+
- Docker & Docker Compose (for services)

### Quick Start

```bash
# Clone and install
git clone <repo-url>
cd app
yarn install

# Start infrastructure services (PostgreSQL, Redis, MinIO)
yarn services:up

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
yarn workspace @plunk/db migrate:dev

# Start all development servers
yarn dev
```

**Note**: The `dev` command starts the API server, worker process, and web apps. For production-like setup or debugging,
you can run components separately:

```bash
# Terminal 1: API Server
yarn workspace api dev:server

# Terminal 2: Background Worker (required for emails)
yarn workspace api dev:worker

# Terminal 3: Web Dashboard
yarn workspace web dev
```

## Development Commands

### Environment Setup

- **Start services**: `yarn services:up` - Starts PostgreSQL, Redis, MinIO via Docker Compose
- **Stop services**: `yarn services:down` - Stops all infrastructure services

### Development

- **Start all apps**: `yarn dev` - Starts all apps including API server and worker process
- **Start specific app**: `yarn dev --filter="<app-name>"` (e.g., `yarn dev --filter="web"`)
- **Start API only (server)**: `yarn workspace api dev:server` - API server without worker
- **Start API only (worker)**: `yarn workspace api dev:worker` - Worker process only
- **Build all**: `yarn build`
- **Lint all**: `yarn lint`
- **Clean all**: `yarn clean` - Removes node_modules, .turbo, and build artifacts

### Database (Prisma)

- **Generate client**: `yarn workspace @plunk/db db:generate`
- **Run migrations (dev)**: `yarn workspace @plunk/db migrate:dev`

## Code Standards

### Import Organization

ESLint enforces import order: builtin → external → internal → parent → sibling with alphabetical sorting and newlines
between groups.

### TypeScript

- Use TypeScript for all new code
- Prefer type imports: `import type { ... }`
- Enable strict type checking

### Component Structure

- UI components go in `packages/ui/src/components/`
- App-specific components in `apps/<app>/src/components/`
- Follow atomic design pattern where applicable

## Making Changes

1. **Fork the repository** and create a new branch from `main`
2. **Make your changes** following the code standards above
3. **Test your changes** thoroughly
4. **Commit your changes** with clear, descriptive commit messages
5. **Push to your fork** and submit a pull request

## Pull Request Guidelines

- Provide a clear description of the changes
- Reference any related issues
- Ensure all tests pass and linting is clean
- Keep PRs focused on a single feature or fix

## Need Help?

- Check the [documentation](https://docs.useplunk.com)
- Open an issue for bugs or feature requests
- Join our community discussions

## License

By contributing to Plunk, you agree that your contributions will be licensed under the AGPL-3.0 License.