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¶

Create schema in *.schemas.ts
Add service method in *.service.ts
Add route handler in *.routes.ts
Register router in server.ts
Test with Postman/curl

Add New Page¶

Create page component in pages/
Add route in App.tsx
Add to sidebar menu (if admin page)
Create API client calls
Test in browser

Add Database Field¶

Update prisma/schema.prisma
Run npx prisma migrate dev --name add_field
Update TypeScript types
Update API endpoints
Update frontend forms

Add New Service Integration¶

Create client in services/
Add environment variables
Create admin routes
Add admin page
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