ref: future-proof makefile with per-service targets

[DogukanUrker]

Summary

Refactor the Makefile to support per-service targets (make install-mail-service, make lint-form-service, make run-form-frontend, etc.) using a template-based approach that requires only adding a service name to a list when new services are introduced.

Motivation

Currently, adding a new backend service or frontend app requires manually updating 8+ targets in the Makefile. This creates maintenance burden and risk of inconsistency.

Naming Convention

• Backend services: {action}-{service}-service (e.g., run-mail-service, lint-form-service)
• Frontend apps: {action}-{app}-frontend (e.g., run-form-frontend, lint-form-frontend)

---

Implementation Plan

1. Makefile Refactoring

Complete rewrite using define/call/eval macros for DRY target generation.

Service Registries (lines 1-10)

• Add BACKEND_SERVICES := form mail list
• Add FRONTEND_APPS := form list
• Add TESTABLE_SERVICES := mail list (services with tests)
• Add command variables (BACKEND_INSTALL_CMD, BACKEND_LINT_CMD, etc.)

Backend Service Macro

define backend_service_targets
install-$(1)-service:
	cd services/$(1) && uv sync --all-extras
lint-$(1)-service:
	cd services/$(1) && uv run ruff check --fix .
format-$(1)-service:
	cd services/$(1) && uv run ruff format .
run-$(1)-service:
	cd services/$(1) && uv run fastapi dev
endef
$(foreach svc,$(BACKEND_SERVICES),$(eval $(call backend_service_targets,$(svc))))

Backend Test Macro (separate for optional tests)

define backend_test_targets
test-$(1)-service:
	cd services/$(1) && uv run pytest -v --cov=app
endef
$(foreach svc,$(TESTABLE_SERVICES),$(eval $(call backend_test_targets,$(svc))))

Frontend App Macro

define frontend_app_targets
install-$(1)-frontend:
	cd frontend/$(1) && bun install
lint-$(1)-frontend:
	cd frontend/$(1) && bun run biome check --write .
format-$(1)-frontend:
	cd frontend/$(1) && bun run biome check --write .
run-$(1)-frontend:
	cd frontend/$(1) && bun dev
build-$(1)-frontend:
	cd frontend/$(1) && bun run build
endef
$(foreach app,$(FRONTEND_APPS),$(eval $(call frontend_app_targets,$(app))))

Global Targets

• install → depends on all install-* targets
• lint → depends on all lint-* targets
• format → depends on all format-* targets
• test → depends on all test-* targets
• clean → unchanged (global artifact cleanup)
• dev → unchanged (runs form backend + frontend)

Auto-Generated Help

• Dynamic help that lists all available targets based on service registries

Special Commands (explicit, not macro-generated)

• sync-prompts → unchanged
• run-mail-campaign → unchanged

---

2. Adding a New Service (Post-Implementation)

New Backend Service (e.g., "auth")

# Change:
BACKEND_SERVICES := form mail
# To:
BACKEND_SERVICES := form mail auth

# If it has tests, also change:
TESTABLE_SERVICES := mail
# To:
TESTABLE_SERVICES := mail auth

Auto-generates: install-auth-service, lint-auth-service, format-auth-service, run-auth-service, test-auth-service

New Frontend App (e.g., "dashboard")

# Change:
FRONTEND_APPS := form
# To:
FRONTEND_APPS := form dashboard

Auto-generates: install-dashboard-frontend, lint-dashboard-frontend, format-dashboard-frontend, run-dashboard-frontend, build-dashboard-frontend

---

3. GitHub Actions Updates

Update workflows to use Makefile targets where possible.

.github/workflows/frontend-check.yaml

• Replace direct biome check frontend/ with make lint-form-frontend
• Keep bun install step for CI dependency setup

.github/workflows/python-check.yaml

• Add make install for both services dependencies
• Replace ruff check services/ scripts/ with per-service targets
• Note: Scripts directory not a service, may keep separate

.github/workflows/test-mail-service.yaml

• Replace cd services/mail && uv sync --all-extras with make install-mail-service
• Replace cd services/mail && uv run ruff check . with make lint-mail-service
• Already uses make test-mail-service ✓

---

4. Documentation Updates

Update all documentation to reference new Makefile targets.

.ai/INSTRUCTIONS.md

Update "Development Commands" section with new per-service targets:

# Global
make install              # Install all dependencies
make lint                 # Lint all code
make format               # Format all code
make test                 # Run all tests

# Backend Services
make install-form-service    # Install form service deps
make install-mail-service    # Install mail service deps
make lint-form-service       # Lint form service
make lint-mail-service       # Lint mail service
make run-form-service        # Run form dev server
make run-mail-service        # Run mail dev server
make test-mail-service       # Run mail tests

# Frontend
make install-form-frontend   # Install form frontend deps
make lint-form-frontend      # Lint form frontend
make run-form-frontend       # Run form frontend dev server

services/form/README.md

Update Setup section to reference makefile targets

services/mail/README.md

Update Setup and Testing sections to reference:

• make install-mail-service
• make run-mail-service
• make lint-mail-service
• make format-mail-service
• make test-mail-service

---

Files to Modify

• Makefile - Main refactoring
• .github/workflows/frontend-check.yaml
• .github/workflows/python-check.yaml
• .github/workflows/test-mail-service.yaml
• .ai/INSTRUCTIONS.md
• services/form/README.md
• services/mail/README.md

---

Verification Plan

Automated Tests

# Verify Makefile syntax
make -n install          # Should show all install commands
make -n lint             # Should show all lint commands
make -n test             # Should show test-mail-service command

# Verify per-service targets
make -n install-mail-service   # Should show: cd services/mail && uv sync --all-extras
make -n lint-form-service      # Should show: cd services/form && uv run ruff check --fix .
make -n run-mail-service       # Should show: cd services/mail && uv run fastapi dev
make -n test-mail-service      # Should show: cd services/mail && uv run pytest -v --cov=app

# Verify frontend targets
make -n install-form-frontend  # Should show: cd frontend/form && bun install
make -n run-form-frontend      # Should show: cd frontend/form && bun dev
make -n lint-form-frontend     # Should show: cd frontend/form && bun run biome check --write .

Manual Verification

1. Run make help - verify all targets are listed dynamically
2. Run make install-mail-service - verify only mail service dependencies install
3. Run make lint-form-service - verify only form service is linted
4. Run make test - verify mail tests run (the only testable service)
5. Run make install - verify all services install in sequence
6. Push branch and verify GitHub Actions workflows pass