Codev.md - Context as Infrastructure

# Codev.md - Development Environment Setup
<!-- Complete setup guide: prerequisites, installation, configuration, troubleshooting -->
<!-- Get a new developer from zero to running the application in under 30 minutes -->
<!-- Last updated: YYYY-MM-DD -->

## Prerequisites

### System Requirements
- **OS**: macOS 13+ (Ventura), Ubuntu 22.04+, or Windows 11 with WSL2
- **RAM**: 16GB minimum (services + IDE + browser consume ~10GB during development)
- **Disk**: 20GB free space (node_modules, Docker images, database data)
- **Network**: VPN access required for staging/production databases (request from IT)

### Required Software

Install these in order. Each step assumes the previous one is complete.

#### 1. Node.js (via nvm)
```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Restart terminal, then:
nvm install 20.11.0
nvm alias default 20.11.0
node --version  # Should print v20.11.0
```

#### 2. Package Manager
```bash
# We use pnpm for faster installs and strict dependency resolution
npm install -g [email protected]
pnpm --version  # Should print 9.1.0
```

#### 3. Docker and Docker Compose
```bash
# macOS: Install Docker Desktop from https://docker.com/products/docker-desktop
# Linux:
sudo apt-get update
sudo apt-get install docker.io docker-compose-v2
sudo usermod -aG docker $USER  # Log out and back in after this

docker --version          # Should be 24.x+
docker compose version    # Should be 2.x+
```

#### 4. Git
```bash
git --version  # Should be 2.40+

# Configure git (use your work email)
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
git config --global pull.rebase true
git config --global init.defaultBranch main
```

#### 5. PostgreSQL Client (for debugging, not the server)
```bash
# macOS:
brew install libpq
brew link --force libpq

# Ubuntu:
sudo apt-get install postgresql-client-16

psql --version  # Should be 16.x
```

## Project Setup

### Step 1: Clone and Install
```bash
# Clone the repository
git clone [email protected]:acme-corp/atlas.git
cd atlas

# Install dependencies (pnpm, not npm)
pnpm install

# This also runs the postinstall script which:
# - Generates Prisma client
# - Sets up git hooks via Husky
# - Validates .nvmrc matches your Node version
```

### Step 2: Start Infrastructure Services
```bash
# Start PostgreSQL, Redis, and MinIO (S3-compatible storage) via Docker
docker compose up -d

# Verify all services are healthy
docker compose ps
# Should show 3 services with status "healthy"

# Expected ports:
# PostgreSQL: 5432
# Redis:      6379
# MinIO:      9000 (API) / 9001 (Console)
```

### Step 3: Configure Environment Variables

```bash
# Copy the example environment file
cp .env.example .env
```

Edit `.env` with the following values. Secrets marked with [1PASSWORD] should be retrieved from the "Atlas Dev" vault in 1Password.

```bash
# Database (Docker Compose defaults - no changes needed for local dev)
DATABASE_URL="postgresql://atlas:atlas_dev_password@localhost:5432/atlas_dev"

# Redis (Docker Compose defaults)
REDIS_URL="redis://localhost:6379"

# Object Storage (MinIO - Docker Compose defaults)
S3_ENDPOINT="http://localhost:9000"
S3_ACCESS_KEY="minioadmin"
S3_SECRET_KEY="minioadmin"
S3_BUCKET="atlas-uploads"

# Authentication
AUTH_SECRET="generate-locally-see-command-below"
GOOGLE_CLIENT_ID="[1PASSWORD: Atlas Dev > Google OAuth > Client ID]"
GOOGLE_CLIENT_SECRET="[1PASSWORD: Atlas Dev > Google OAuth > Client Secret]"

# Email (development uses local mailpit - no config needed)
SMTP_HOST="localhost"
SMTP_PORT="1025"

# External Services
STRIPE_SECRET_KEY="[1PASSWORD: Atlas Dev > Stripe > Test Secret Key]"
STRIPE_WEBHOOK_SECRET="[1PASSWORD: Atlas Dev > Stripe > Webhook Secret]"
OPENAI_API_KEY="[1PASSWORD: Atlas Dev > OpenAI > API Key]"

# Application
NODE_ENV="development"
PORT="3000"
LOG_LEVEL="debug"
```

```bash
# Generate the AUTH_SECRET value
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Paste the output as the AUTH_SECRET value in .env
```

### Step 4: Initialize the Database
```bash
# Run all migrations to create tables
pnpm db:migrate

# Seed development data (creates test users, sample data)
pnpm db:seed

# Verify the database is set up correctly
pnpm db:studio
# Opens Prisma Studio at http://localhost:5555
# You should see tables with seeded data
```

### Step 5: Start the Development Server
```bash
# Start the application in development mode (hot reload enabled)
pnpm dev

# Application: http://localhost:3000
# API docs:    http://localhost:3000/api/docs
# Email inbox: http://localhost:8025 (Mailpit - catches all dev emails)
```

### Step 6: Verify Everything Works
```bash
# Run the test suite to confirm your setup is correct
pnpm test

# Run a quick smoke test
pnpm test:smoke

# If all tests pass, your environment is ready
```

### Test Accounts (from seed data)
| Email | Password | Role |
|-------|----------|------|
| [email protected] | password123 | Admin |
| [email protected] | password123 | User |
| [email protected] | password123 | Viewer |

## Service Dependencies

### Service Architecture
```
                    +----------------+
                    |   Next.js App  |
                    |   (port 3000)  |
                    +-------+--------+
                            |
              +-------------+-------------+
              |             |             |
      +-------v---+  +-----v-----+  +----v------+
      | PostgreSQL |  |   Redis   |  |   MinIO   |
      | (port 5432)|  |(port 6379)|  |(port 9000)|
      +------------+  +-----------+  +-----------+
```

### PostgreSQL (Primary Database)
- **Purpose**: All application data - users, documents, teams, billing
- **Version**: 16.x
- **Local access**: `psql postgresql://atlas:atlas_dev_password@localhost:5432/atlas_dev`
- **GUI**: Prisma Studio (`pnpm db:studio`) or pgAdmin/DBeaver

### Redis (Cache and Queues)
- **Purpose**: Session store, rate limiting, background job queue (BullMQ)
- **Version**: 7.x
- **Local access**: `redis-cli` or RedisInsight
- **Note**: Flushing Redis in dev is safe - sessions will just expire and jobs will re-enqueue

### MinIO (Object Storage)
- **Purpose**: File uploads, document attachments, profile images
- **Console**: http://localhost:9001 (login: minioadmin/minioadmin)
- **Note**: S3-compatible API. Production uses AWS S3. Code is identical.

## Common Development Commands

```bash
# Application
pnpm dev                    # Start dev server with hot reload
pnpm build                  # Production build
pnpm start                  # Start production build locally
pnpm lint                   # Run ESLint
pnpm type-check             # TypeScript compiler check

# Database
pnpm db:migrate             # Apply pending migrations
pnpm db:migrate:create      # Create a new migration
pnpm db:seed                # Seed development data
pnpm db:reset               # Drop all tables, re-migrate, re-seed
pnpm db:studio              # Open Prisma Studio GUI

# Testing
pnpm test                   # Run all unit tests
pnpm test:watch             # Run tests in watch mode
pnpm test:integration       # Integration tests (needs running services)
pnpm test:e2e               # Playwright end-to-end tests
pnpm test:coverage          # Generate coverage report

# Docker
docker compose up -d        # Start all services
docker compose down         # Stop all services
docker compose logs -f      # Tail logs from all services
docker compose down -v      # Stop and delete all data (fresh start)

# Code Generation
pnpm generate:component     # Scaffold a new React component
pnpm generate:route         # Scaffold a new API route
pnpm generate:migration     # Create a new database migration
```

## IDE Setup

### VS Code (Recommended)

#### Required Extensions
Install via the Extensions panel or command line:
```bash
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension Prisma.prisma
code --install-extension usernamehw.errorlens
code --install-extension eamodio.gitlens
```

#### Workspace Settings
The project includes `.vscode/settings.json` with team-standard settings. Key settings:
```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}
```

#### Debugging Configuration
The project includes `.vscode/launch.json` with pre-configured debug profiles:
- **Next.js: Server** - Debug server-side code with breakpoints
- **Next.js: Client** - Debug client-side code in Chrome
- **Jest: Current File** - Debug the currently open test file

### JetBrains (WebStorm)
- Enable ESLint and Prettier integration in Preferences > Languages & Frameworks
- Set Node interpreter to the nvm-managed version
- Import the `.editorconfig` from the project root

## Troubleshooting

### Port Conflicts
```bash
# Check what is using a port
# macOS/Linux:
lsof -i :3000
# Windows (PowerShell):
netstat -ano | findstr :3000

# Kill process on port
# macOS/Linux:
kill -9 $(lsof -t -i :3000)
# Windows:
taskkill /PID [PID] /F

# Or change the port in .env:
PORT=3001
```

### Docker Issues
```bash
# Services will not start
docker compose down -v    # Remove volumes and try fresh
docker compose up -d

# Out of disk space
docker system prune -a    # Remove unused images and containers
docker volume prune       # Remove unused volumes

# Permission denied (Linux)
sudo usermod -aG docker $USER
# Log out and back in
```

### Database Issues
```bash
# Cannot connect to database
docker compose ps         # Is postgres service running?
docker compose logs db    # Check postgres logs for errors

# Migration fails
pnpm db:migrate:status    # Check which migrations have been applied
pnpm db:reset             # Nuclear option - drops everything and starts fresh

# Prisma client out of sync with schema
pnpm prisma generate      # Regenerate the Prisma client
```

### Node/pnpm Issues
```bash
# Wrong Node version
nvm use                   # Reads .nvmrc and switches to correct version

# Dependency resolution errors
rm -rf node_modules
pnpm install --force      # Force reinstall all dependencies

# pnpm lockfile conflicts after merge
git checkout --theirs pnpm-lock.yaml
pnpm install
git add pnpm-lock.yaml
```

## Environment Variables Reference

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | Yes | - | PostgreSQL connection string |
| `REDIS_URL` | Yes | - | Redis connection string |
| `S3_ENDPOINT` | Yes | - | S3/MinIO endpoint URL |
| `S3_ACCESS_KEY` | Yes | - | S3/MinIO access key |
| `S3_SECRET_KEY` | Yes | - | S3/MinIO secret key |
| `S3_BUCKET` | Yes | - | S3/MinIO bucket name |
| `AUTH_SECRET` | Yes | - | NextAuth session encryption secret |
| `GOOGLE_CLIENT_ID` | Yes | - | Google OAuth client ID |
| `GOOGLE_CLIENT_SECRET` | Yes | - | Google OAuth client secret |
| `STRIPE_SECRET_KEY` | No | - | Stripe API key (payments disabled without) |
| `OPENAI_API_KEY` | No | - | OpenAI API key (AI features disabled without) |
| `PORT` | No | 3000 | Application port |
| `NODE_ENV` | No | development | Environment mode |
| `LOG_LEVEL` | No | info | Logging verbosity (debug/info/warn/error) |

## Secrets Management

### Development Secrets
- Store in `.env` (gitignored - never committed)
- Get values from 1Password vault "Atlas Dev"
- Never share secrets over Slack or email - use 1Password sharing

### Generating Local Secrets
```bash
# Generate a random secret key (for AUTH_SECRET, etc.)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Generate a UUID
node -e "console.log(require('crypto').randomUUID())"
```

### Production Secrets
- Managed via [AWS Systems Manager Parameter Store / Vault / etc.]
- Rotated quarterly by the platform team
- Access requests go through [process/tool]