> /init

touch CLAUDE.md
# or
mkdir -p .claude && touch .claude/CLAUDE.md

# Project: [Your Project Name]

## Overview
[Brief description of what this project does]

## Tech Stack
- [Language/Framework 1]
- [Language/Framework 2]
- [Database]
- [Other tools]

## Project Structure
[Key directories and their purposes]

## Conventions
[Coding standards and patterns to follow]

## Important Notes
[Things Claude should know or avoid]

# Project: E-Commerce Platform

## Overview
A B2B e-commerce platform for wholesale distributors. Handles inventory 
management, order processing, and multi-tenant storefronts.

## Business Context
- Primary users: Warehouse managers and procurement teams
- Peak usage: Monday-Friday, business hours
- Critical flows: Order placement, inventory sync, invoice generation

## Tech Stack

### Frontend
- Next.js 14 with App Router
- TypeScript 5.3 (strict mode)
- Tailwind CSS 3.4
- React Query for data fetching

### Backend
- Node.js 20 LTS
- Express.js with TypeScript
- Prisma ORM 5.x
- PostgreSQL 15

### Infrastructure
- Vercel (frontend)
- Railway (backend + database)
- Redis for caching
- S3 for file storage

## Project Structure

- **apps/web/** - Next.js frontend
- **apps/api/** - Express backend
- **packages/ui/** - Shared component library
- **packages/config/** - Shared configuration
- **packages/types/** - Shared TypeScript types
- **prisma/schema.prisma** - Database schema
- **prisma/migrations/** - Migration files
- **scripts/** - Development and deployment scripts

### Key Directories
- `apps/web/app/`: Next.js App Router pages and layouts
- `apps/api/src/routes/`: API endpoint handlers
- `packages/ui/src/components/`: Reusable UI components

## Coding Conventions

### TypeScript
- Use strict mode, no `any` types without justification
- Prefer interfaces over types for object shapes
- Use Zod for runtime validation

### React Components
- Functional components only
- Custom hooks in `hooks/` directory
- Use named exports, not default exports

### Naming
- Components: PascalCase (e.g., `UserProfile.tsx`)
- Utilities: camelCase (e.g., `formatDate.ts`)
- Constants: UPPER_SNAKE_CASE
- Database tables: snake_case

### File Organization
- One component per file
- Co-locate tests: `Component.tsx` → `Component.test.tsx`
- Shared types in `types/` directory

### Git
- Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`
- Branch naming: `feature/`, `fix/`, `chore/`
- Squash merge to main

## Important Notes

### Off-Limits Areas
- **DO NOT** modify `/apps/api/src/billing/` - handled by external payment team
- **DO NOT** change database schema without creating a migration
- **DO NOT** commit `.env` files or expose API keys

### Critical Considerations
- All API endpoints must validate input with Zod schemas
- Database queries must use Prisma transactions for multi-table updates
- Frontend routes require authentication middleware

### Known Issues
- The legacy `/api/v1/` routes are deprecated but still used by mobile app
- Redis connection sometimes fails in dev - restart with `npm run redis:restart`

### External Dependencies
- Stripe webhook signatures must match `STRIPE_WEBHOOK_SECRET`
- SendGrid templates are managed in their dashboard, not in code

## Common Tasks

### Adding a New API Endpoint
1. Create route handler in `apps/api/src/routes/`
2. Add Zod schema in `apps/api/src/schemas/`
3. Register route in `apps/api/src/index.ts`
4. Add tests in `apps/api/src/routes/__tests__/`

### Creating a Database Migration
```bash
cd apps/api
npx prisma migrate dev --name description_of_change

npm run test          # All tests
npm run test:unit     # Unit tests only
npm run test:e2e      # End-to-end tests

npm run dev           # Start all services
npm run dev:web       # Frontend only
npm run dev:api       # Backend only

---

## Advanced CLAUDE.md Patterns

### Dynamic Content with Commands

Include live data from your project:

```markdown
## Current Dependencies

Main dependencies from package.json:
- See `package.json` for full list

## Recent Changes

Check recent commits with:
```bash
git log --oneline -10

### Environment-Specific Instructions

```markdown
## Environment Notes

### Development
- Use `.env.local` for local overrides
- Database: Local PostgreSQL on port 5432
- API runs on http://localhost:3001

### Staging
- Database: Railway staging instance
- Requires VPN for access

### Production
- Never run migrations directly
- Changes require PR review from 2 team members

## Team Ownership

| Area | Owner | Notes |
|------|-------|-------|
| Frontend | @frontend-team | All `/apps/web/` |
| API | @backend-team | All `/apps/api/` |
| Database | @data-team | Schema changes need review |
| Payments | @billing-team | External - don't modify |
| DevOps | @platform-team | CI/CD and infrastructure |

## Custom Commands

We have custom slash commands for common workflows:

- `/deploy-staging` - Deploy current branch to staging
- `/db-migrate` - Run pending database migrations
- `/generate-types` - Regenerate TypeScript types from Prisma

See `.claude/commands/` for implementation details.

# Personal Preferences

## Coding Style
- I prefer explicit type annotations
- Use descriptive variable names
- Add comments for complex logic

## Communication
- Explain your reasoning briefly
- Show diffs for file changes
- Ask before making large refactors

## Tools I Use
- VS Code with Vim keybindings
- iTerm2 on macOS
- Prefer npm over yarn

# Monorepo: My Platform

## Shared Conventions
- All packages use TypeScript strict mode
- Shared types in `/packages/types/`
- Use workspace dependencies: `"@myorg/ui": "workspace:*"`

# Frontend App

Inherits from root CLAUDE.md.

## Additional Conventions
- Use Next.js App Router patterns
- Server components by default
- Client components marked with 'use client'

> /memory

> Remember that we're migrating from REST to GraphQL. 
> New endpoints should use GraphQL, but maintain REST compatibility.

# Project: TaskFlow - Project Management SaaS

## Overview
A Trello-like project management app with real-time collaboration.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict)
- Prisma + PostgreSQL
- Socket.io for real-time
- Tailwind + Radix UI

## Architecture
- Feature-based folder structure: `/features/[feature]/`
- Each feature has: components/, hooks/, api/, types/
- Shared UI in `/components/ui/` (Radix-based)

## Conventions
- React Query for server state
- Zustand for client state
- Zod for validation (shared between client/server)
- No `any` types - use `unknown` and narrow

## Critical Rules
1. All database writes must be in transactions
2. Real-time events go through `/lib/realtime/emit.ts`
3. Never store sensitive data in client state
4. All API routes need authentication middleware

# Project: DataPipeline API

## Overview
REST API for data processing pipeline management.

## Tech Stack
- Python 3.11
- FastAPI + Pydantic v2
- SQLAlchemy 2.0 + PostgreSQL
- Celery + Redis for async tasks
- Docker Compose for local dev

## Project Structure

- **src/api/** - FastAPI routes
- **src/models/** - SQLAlchemy models
- **src/schemas/** - Pydantic schemas
- **src/services/** - Business logic
- **src/tasks/** - Celery tasks
- **src/utils/** - Helpers

## Conventions
- Type hints required everywhere
- Docstrings for public functions (Google style)
- Async/await for I/O operations
- Dependency injection via FastAPI Depends

## Commands
- `make dev` - Start development server
- `make test` - Run pytest
- `make lint` - Run ruff + mypy

## Important
- Long-running tasks MUST use Celery, not synchronous endpoints
- All endpoints need OpenAPI documentation
- Database migrations via Alembic only

# Project: FitTrack Mobile

## Overview
Fitness tracking app with workout logging and progress analytics.

## Tech Stack
- React Native 0.73 + Expo SDK 50
- TypeScript
- React Query + Zustand
- React Navigation 6

## Conventions
- Functional components with hooks
- Styles: StyleSheet.create, not inline
- Icons: @expo/vector-icons only
- Animations: Reanimated 3

## Platform Notes
- Test on both iOS and Android before PR
- Use Platform.select for platform-specific code
- Safe area handling via react-native-safe-area-context

## Off-Limits
- Don't modify native modules without tech lead approval
- Don't add native dependencies without checking Expo compatibility
- Push notifications handled by external service

## Testing
- Jest for unit tests
- Detox for E2E (run on CI only)

## Override User Preferences
For this project, ignore personal preferences about:
- We use Yarn, not npm
- We use tabs, not spaces

## Documentation
- API docs: `/docs/api/`
- Architecture: `/docs/architecture.md`
- Onboarding: `/docs/onboarding.md`

Claude can read these files when needed.