Local stack & dev setup

The Ghasi-edTech repo (ghasi-EdTech) is a Turborepo + pnpm workspace. Local development uses Docker for PostgreSQL and Keycloak; application services run on the host with pnpm dev.

What runs in Docker today

Service	Default port	Purpose
PostgreSQL 16	5432	Shared dev database (schemas per service; see each service migrations folder). Default DB/user in infra/docker-compose.yml: ghasi_identity / ghasi / ghasi.
Keycloak 24	8081	OIDC issuer http://localhost:8081/realms/ghasi (realm imported from infra/keycloak/).

From the repo root (Windows: PowerShell):

pnpm infra:up

Equivalent to docker compose -f infra/docker-compose.yml up -d via scripts/start-infra.ps1. Use pnpm infra:down to stop. Optional: pnpm infra:up:kong for the Kong smoke stack under infra/kong/.

Environment files

Each service and app with a .env.example expects its own .env for local runs. Generate them from the examples (ports and cross-service URLs filled for local dev):

pnpm env:create

Use pnpm env:create -- --force to overwrite existing .env files. Without pnpm env:create, DATABASE_URL and other variables are missing and database scripts will fail.

Database migrations and seeds

After Postgres is healthy, apply SQL migrations and seeds for all services (runs one package at a time to avoid connection stampedes):

pnpm db:setup

This is the same as pnpm db:setup:all. You can also run pnpm db:migrate:all or pnpm db:seed:all separately.

Platform-wide contract (additional infra)

As more runtime pieces land in Compose, the stack is expected to grow toward:

Service	Port	Purpose
Redis 7	6379	Cache, rate limit, idempotency replay protection.
NATS JetStream	4222	Event broker.
OpenSearch	9200	Lexical search.
MinIO	9000	S3-compatible object storage.
Mailpit	1025 / 8025	SMTP capture for verification flows.

Seed personas for demos (when seeds define them) include learner@example.test, instructor@example.test, tenant-admin@example.test, and platform-admin@example.test.

Root package.json scripts (monorepo)

Script	What it does
pnpm build	turbo run build - production build for all packages that define build.
pnpm dev	turbo run dev - start dev servers (persistent) across the workspace.
pnpm lint	turbo run lint.
pnpm typecheck	turbo run typecheck.
pnpm test	turbo run test.
pnpm test:integration	turbo run test:integration.
pnpm test:contract	turbo run test:contract.
pnpm format	Prettier over ts, tsx, md, json, yml, yaml.
pnpm sync:openapi	Emit OpenAPI specs from Nest services into the repo (Postman pipeline).
pnpm sync:postman	Generate Postman collections from OpenAPI.
pnpm sync:stubs	Generate request/response stubs for tooling.
pnpm sync:env	Refresh Postman environment files from local port config.
pnpm sync:all	Runs sync:openapi, then sync:env, then sync:stubs, then sync:postman.
pnpm env:create	Create per-package .env from .env.example with local URLs and ports.
pnpm lint:platform	Lint cross-service / Postman platform invariants.
pnpm validate:openapi	Validate OpenAPI artifacts.
pnpm check:drift	Check generated API artifacts for drift vs code.
pnpm kong:surface	Derive Kong route surface from OpenAPI.
pnpm lint:kong	Lint Kong declarative config.
pnpm db:migrate:all	Run db:migrate in every package (sequential concurrency).
pnpm db:seed:all	Run db:seed in every package (sequential concurrency).
pnpm db:generate:all	Run db:generate where defined (e.g. ORM clients).
pnpm db:setup	Run db:setup everywhere: migrate then seed per service (sequential concurrency). Same as db:setup:all.
pnpm db:setup:all	Alias for pnpm db:setup.
pnpm infra:up	Start Postgres + Keycloak (PowerShell wrapper; detached).
pnpm infra:up:kong	Start Postgres, Keycloak, and optional Kong stack.
pnpm infra:down	Tear down the infra started by the scripts above.