changemaker.lite/mkdocs/docs/v2/development/index.md

# Development Guide

This section covers development workflows, local setup, coding standards, testing, and best practices for contributing to Changemaker Lite V2.

## Development Workflow

### [Local Setup](local-setup.md)

Getting started with local development:

- Prerequisites (Node.js, Docker, Git)
- Repository setup
- Environment configuration
- Database initialization
- Running development servers

### [Docker Workflow](docker-workflow.md)

Docker-based development:

- Starting services with Docker Compose
- Viewing logs
- Rebuilding containers
- Database operations
- Volume management

### [Git Workflow](git-workflow.md)

Version control best practices:

- Branch naming conventions
- Commit message format
- Pull request process
- Code review guidelines
- Merge strategies

### [NPM Commands](npm-commands.md)

Common development commands:

- Development servers
- Build commands
- Testing
- Type-checking
- Linting and formatting

### [Database Migrations](migrations.md)

Schema changes and migrations:

- Creating migrations (Prisma)
- Applying migrations
- Schema push (Drizzle)
- Rolling back changes
- Testing migrations

### [TypeScript](typescript.md)

TypeScript best practices:

- Type definitions
- Strict mode
- Common patterns
- Zod integration
- Prisma types

### [Code Style](code-style.md)

Coding standards and conventions:

- ESLint configuration
- Prettier formatting
- Naming conventions
- File organization
- Comment standards

### [Testing](testing.md)

Testing strategies:

- Unit tests
- Integration tests
- API testing
- Component testing
- E2E testing (future)

### [Debugging](debugging.md)

Debugging techniques:

- VS Code debugging
- Browser DevTools
- API debugging
- Database queries
- Log analysis

## Quick Start

### Local Development (No Docker)

**Terminal 1: API Server**
```bash
cd api
npm install
npm run dev
# Runs on http://localhost:4000
```

**Terminal 2: Admin GUI**
```bash
cd admin
npm install
npm run dev
# Runs on http://localhost:3000
```

**Terminal 3: Media API (Optional)**
```bash
cd api
npm run dev:media
# Runs on http://localhost:4100
```

### Docker Development

**Start Core Services**
```bash
docker compose up -d v2-postgres redis
docker compose up -d api admin
```

**View Logs**
```bash
docker compose logs -f api
docker compose logs -f admin
```

**Rebuild After Changes**
```bash
docker compose build api
docker compose up -d api
```

## Development Tools

### Required

- **Node.js 20+** - JavaScript runtime
- **npm 10+** - Package manager
- **Docker 24+** - Container runtime
- **Docker Compose 2+** - Multi-container orchestration
- **Git 2+** - Version control

### Recommended

- **VS Code** - IDE with TypeScript support
- **Prisma Studio** - Database GUI
- **Postman** - API testing
- **Redis Insight** - Redis GUI (optional)

### VS Code Extensions

- **Prisma** - Schema syntax highlighting
- **ESLint** - JavaScript linting
- **Prettier** - Code formatting
- **TypeScript** - Language support
- **Docker** - Container management

## Project Structure

```
changemaker.lite/
├── api/                    # Backend (Express + Fastify)
│   ├── src/
│   │   ├── server.ts       # Express entry point
│   │   ├── media-server.ts # Fastify entry point
│   │   ├── modules/        # Feature modules
│   │   ├── services/       # Shared services
│   │   ├── middleware/     # Express middleware
│   │   └── utils/          # Utilities
│   ├── prisma/
│   │   ├── schema.prisma   # Main schema
│   │   └── migrations/     # Migration history
│   └── package.json
│
├── admin/                  # Frontend (React + Vite)
│   ├── src/
│   │   ├── App.tsx         # Main router
│   │   ├── components/     # Shared components
│   │   ├── pages/          # Page components
│   │   ├── lib/            # API clients
│   │   └── stores/         # Zustand stores
│   └── package.json
│
├── docker-compose.yml      # V2 orchestration
├── .env                    # Environment variables (not committed)
└── .env.example            # Example environment
```

## Development Patterns

### Backend Module Structure

```
api/src/modules/feature/
├── feature.routes.ts       # Express router
├── feature.service.ts      # Business logic
├── feature.schemas.ts      # Zod validation
└── feature-public.routes.ts # Public routes (optional)
```

### Frontend Page Structure

```
admin/src/pages/
├── admin/                  # Admin pages (30)
├── public/                 # Public pages (8)
├── volunteer/              # Volunteer pages (4)
└── auth/                   # Auth pages (1)
```

### API Client Pattern

```typescript
// admin/src/lib/api.ts
import axios from 'axios';

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
});

// Interceptor for auth
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('accessToken');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});
```

### Service Pattern

```typescript
// api/src/modules/feature/feature.service.ts
import { prisma } from '../../lib/prisma';

class FeatureService {
  async create(data: CreateInput) {
    return await prisma.feature.create({ data });
  }

  async findAll(filters: Filters) {
    return await prisma.feature.findMany({ where: filters });
  }
}

export const featureService = new FeatureService();
```

## Common Tasks

### Add New API Endpoint

1. Create schema in `*.schemas.ts`
2. Add service method in `*.service.ts`
3. Add route handler in `*.routes.ts`
4. Register router in `server.ts`
5. Test with Postman/curl

### Add New Page

1. Create page component in `pages/`
2. Add route in `App.tsx`
3. Add to sidebar menu (if admin page)
4. Create API client calls
5. Test in browser

### Add Database Field

1. Update `prisma/schema.prisma`
2. Run `npx prisma migrate dev --name add_field`
3. Update TypeScript types
4. Update API endpoints
5. Update frontend forms

### Add New Service Integration

1. Create client in `services/`
2. Add environment variables
3. Create admin routes
4. Add admin page
5. Test integration

## Testing

### API Tests

```bash
# Run API tests
cd api && npm test

# Test specific endpoint
curl http://localhost:4000/api/campaigns
```

### Frontend Tests

```bash
# Run component tests
cd admin && npm test

# Test build
cd admin && npm run build
```

### Type Checking

```bash
# Check API types
cd api && npx tsc --noEmit

# Check admin types
cd admin && npx tsc --noEmit
```

## Debugging

### API Debugging

```bash
# View API logs
docker compose logs -f api

# Access container shell
docker compose exec api sh

# Run Prisma Studio
cd api && npx prisma studio
```

### Frontend Debugging

```bash
# View admin logs
docker compose logs -f admin

# Access browser DevTools
# Open http://localhost:3000
# F12 for DevTools
```

## Code Quality

### Linting

```bash
# Lint API
cd api && npm run lint

# Lint admin
cd admin && npm run lint
```

### Formatting

```bash
# Format API
cd api && npm run format

# Format admin
cd admin && npm run format
```

### Type Safety

All code uses TypeScript with strict mode:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}
```

## Best Practices

### Backend

- Use Zod for validation
- Service layer for business logic
- Middleware for cross-cutting concerns
- Error handling with try/catch
- Logging with Winston

### Frontend

- Use React hooks
- Zustand for state management
- Ant Design components
- Type-safe API calls
- Error boundaries

### Database

- Use migrations for schema changes
- Index frequently queried fields
- Use transactions for multi-step operations
- Avoid N+1 queries

## Related Documentation

- [Local Setup](local-setup.md)
- [Docker Workflow](docker-workflow.md)
- [Git Workflow](git-workflow.md)
- [NPM Commands](npm-commands.md)
- [Migrations](migrations.md)
- [TypeScript](typescript.md)
- [Code Style](code-style.md)
- [Testing](testing.md)
- [Debugging](debugging.md)
- [Contributing](../contributing/index.md)