Development Guide

This module provides guidance for developers working on the Event and Membership Management system. It covers development workflow, CI/CD pipelines, local development setup, and build automation.

Workflow and CI/CD

Understanding the development process and continuous integration:

Development Workflow - GitFlow branching model and release process
Claude Design ↔ Claude Code Workflow - How web-based Claude Design and WSL-based Claude Code interoperate: feature inventory, user-story template, session kickoff, design→code handoff, phase-tag discipline
GitHub Actions CI/CD - CI/CD pipeline architecture and configuration
Repository Rules - Branch protection rulesets and code owner configuration

Local Development

Setting up a local development environment for front-end and full-stack development:

Running Backend Services Locally - Docker Compose configurations for starting backend dependencies
GreenMail Email Server - Local email testing without external SMTP servers

Framework Guides

Cookbooks for building on the shared frameworks in admin-service:

Adding a Reactor - Step-by-step guide to implementing background processing on the Signal & Sweep framework: choosing signal vs sweep, aggregate keys and debounce, emitting signals correctly, testing, and debugging via the admin API

Traps and Trust

Knowing when a green tick means nothing, and where the pipeline and the migrations lie to you:

Which Test Suites Actually Run - Per repository, whether a passing check means tests ran: the front-end check whose test step is opt-in, the Jest runner that must go through the Angular builder, and the PHP suites that exit zero having run nothing
CI and Release Pipeline Traps - Re-running a job cannot pick up a shared-workflow fix, runner starvation and the local release path, docs-only path filters on release branches, reading the status check rollup, and the cross-repository merge ordering between the service and the database
Liquibase Migration Traps - A half-applied changeset silently blocking every later migration, fixture loads under MySQL strict mode, and when a defensive precondition is and is not warranted

Build Conventions

The shared conventions every EMS service follows for build + image + chart:

Maven POM Conventions - Parent POM, Maven profiles determining build variants, shared plugin set
Jib Docker Build - Container image build via Jib, base image, layering, extra directories
Helm Chart Structure - Per-service chart layout, values schema, templates, secrets
Docker Compose for Developers - Local dev stack: MySQL, GreenMail, and gateway-only dev for frontend developers

Build Automation

Automation workflows for building and publishing artifacts:

Manual Helm Chart Release - Retired for the service repos; charts are packaged by push-dev.yml / push-main.yml. Kept for legacy event-admin-ui.
Docker Compose Version Sync - Retired autotask; dev.yml is maintained by hand. Explains why, and how to update it.