Local Dev Setup

:::info Source Sourced from services/assignment-service/LOCAL_DEV_SETUP.md in the documentation repo. :::

Companion: ../../README.md

---

1. Prerequisites

Tool	Version
Node.js	22.x LTS
pnpm	9.x
Docker + Compose	24+ / v2
Git	2.40+
direnv (recommended)	2.x

Optional:

• k6 (load tests)
• grpcurl / nats-cli
• gh (GitHub CLI)

2. Clone & Install

git clone git@github.com:ghasi-edtech/platform.git
cd platform/services/assignment-service
pnpm install
cp .env.example .env
direnv allow

3. Dev Stack (Docker Compose)

From repo root:

docker compose -f infra/dev/compose.yml up -d \
  postgres nats redis otel-collector signoz

Services exposed locally:

• Postgres 5432 (user: ghasi / pass: ghasi / db: ghasi)
• NATS 4222, monitor 8222
• Redis 6379
• OTel collector OTLP 4318
• SigNoz UI http://localhost:3301

4. Database Bootstrap

pnpm db:migrate
pnpm db:seed:dev        # seeds a demo tenant tnt_dev with 50 users, 2 courses

The seed generates:

• tnt_dev
• Users usr_dev_001..050
• Courses crs_dev_fire_safety, crs_dev_hipaa_basics (published v1 in catalog)
• One draft assignment asn_dev_sample

5. Run

Four roles — run in separate terminals during dev, or use the dev orchestrator:

# one-shot
pnpm dev

# or individually:
APP_ROLE=api        pnpm dev:role
APP_ROLE=worker     pnpm dev:role
APP_ROLE=scheduler  pnpm dev:role
APP_ROLE=ai-suggest pnpm dev:role

API is available at http://localhost:8080. OpenAPI UI at http://localhost:8080/api/v1/docs.

6. Environment Variables

NODE_ENV=development
LOG_LEVEL=debug
PORT=8080

POSTGRES_URL=postgres://ghasi:ghasi@localhost:5432/ghasi
REDIS_URL=redis://localhost:6379/2
NATS_URL=nats://localhost:4222

INTERNAL_SVC_JWT_SIGNING_KEY=dev-secret-do-not-use-in-prod
AI_GATEWAY_URL=http://localhost:8090
AI_GATEWAY_TOKEN=dev

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=assignment-service

RRULE_HORIZON_DAYS=90
MATERIALIZER_BATCH_SIZE=100
OVERDUE_SWEEP_INTERVAL=1m
CLOSED_MISSED_SWEEP_INTERVAL=2m
FEATURE_AI_SUGGEST=on

7. Authentication (Dev)

Dev JWTs are signed by the shared dev key; use the helper:

pnpm tok:dev --role compliance_admin --tenant tnt_dev --sub usr_dev_admin
# copy Bearer token into your API client

8. Example Requests

# Create assignment
curl -X POST http://localhost:8080/api/v1/assignments \
  -H "Authorization: Bearer $DEV_JWT" \
  -H "X-Tenant-Id: tnt_dev" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @examples/create-yearly.json

# Activate
curl -X POST http://localhost:8080/api/v1/assignments/asn_dev_sample/activate \
  -H "Authorization: Bearer $DEV_JWT" \
  -H "X-Tenant-Id: tnt_dev"

# List windows
curl -G http://localhost:8080/api/v1/assignments/asn_dev_sample/windows \
  -H "Authorization: Bearer $DEV_JWT" -H "X-Tenant-Id: tnt_dev"

9. Watch Events (NATS)

nats sub 'assignment.*' --creds etc/dev.creds

Handy scripts:

pnpm nats:replay --since=1h          # replay last hour
pnpm nats:dlq:list                   # list DLQ subjects

10. Testing

pnpm test                # unit
pnpm test:int            # integration (spins Testcontainers)
pnpm test:contract       # event + HTTP contract
pnpm test:e2e            # full platform
pnpm test:load           # k6 smoke
pnpm test:coverage       # HTML report in coverage/

11. Tooling

• Linting: ESLint + @ghasi/eslint-config.
• Formatting: Prettier.
• Type check: pnpm tsc --noEmit.
• Commit hook: lint-staged + husky (pre-commit), commitlint (commit-msg).

12. Debugging

• DEBUG=assignment:* — app debug logs
• PG_QUERY_LOG=1 — log SQL with params (never in prod)
• VSCode launch.json profile assignment-api attaches inspector at 9229.

13. Useful Make Targets

make dev         # alias for pnpm dev
make test        # full suite
make seed        # reseed tenant
make reset-db    # drop + migrate + seed
make gen:openapi # regen openapi from code
make gen:events  # regen event schema types

14. Troubleshooting

Symptom	Fix
readyz stuck	check docker containers up; docker compose logs postgres
Empty windows after activate	is scheduler running? check cron in logs
tenant_id missing error	did you set X-Tenant-Id header?
OpenAPI validator 400	pnpm gen:openapi drifted; regenerate
Slow tests	prune Testcontainers: docker system prune

15. Offline-first Authoring (S5)

To exercise admin offline flow:

pnpm dev:sync               # starts sync-service local
pnpm demo:admin-offline     # opens admin UI with network toggle

16. Contribution Checklist

Before opening PR:

• pnpm test && pnpm lint && pnpm tsc --noEmit
• New events → add schema + contract test
• New handlers → add metric + trace span
• DB changes → migration up+down (if reversible) + sample data update
• Update CHANGELOG.md (Unreleased)

---