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

Getting started with local development:

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

Docker Workflow

Docker-based development:

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

Git Workflow

Version control best practices:

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

NPM Commands

Common development commands:

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

Database Migrations

Schema changes and migrations:

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

TypeScript

TypeScript best practices:

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

Code Style

Coding standards and conventions:

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

Testing

Testing strategies:

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

Debugging

Debugging techniques:

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

Quick Start

Local Development (No Docker)

Terminal 1: API Server

cd api
npm install
npm run dev
# Runs on http://localhost:4000

Terminal 2: Admin GUI

cd admin
npm install
npm run dev
# Runs on http://localhost:3000

Terminal 3: Media API (Optional)

cd api
npm run dev:media
# Runs on http://localhost:4100

Docker Development

Start Core Services

docker compose up -d v2-postgres redis
docker compose up -d api admin

View Logs

docker compose logs -f api
docker compose logs -f admin

Rebuild After Changes

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

// 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

// 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

# Run API tests
cd api && npm test

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

Frontend Tests

# Run component tests
cd admin && npm test

# Test build
cd admin && npm run build

Type Checking

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

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

Debugging

API Debugging

# 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

# View admin logs
docker compose logs -f admin

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

Code Quality

Linting

# Lint API
cd api && npm run lint

# Lint admin
cd admin && npm run lint

Formatting

# Format API
cd api && npm run format

# Format admin
cd admin && npm run format

Type Safety

All code uses TypeScript with strict mode:

{
  "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
• Docker Workflow
• Git Workflow
• NPM Commands
• Migrations
• TypeScript
• Code Style
• Testing
• Debugging
• Contributing