Metaboost

HTTP API and Next.js app. Structure and tooling mirror the Podverse monorepo where applicable.

Structure

• apps/api – Standalone Express API (port 4000 by default)
• apps/web – Next.js app (default 4002 on host; see PORT in apps/web/package.json)
• apps/web/sidecar – Runtime-config sidecar (WEB_SIDECAR_PORT, default 4001 on host)
• Infra (database, management database, Docker): See infra/INFRA.md.

Setup

Quick path (clone → running): See docs/QUICK-START.md (Make + Docker for Postgres/Valkey, API and web on host).

With Nix (Linux / macOS): If you use direnv, run direnv allow in the repo root once. The flake provides Node 24 and the shell loads automatically. Without direnv: nix develop to enter the dev shell.

npm install

Local env: App and infra .env files are generated by make local_env_setup, not by copying .env.example alone. See docs/development/LOCAL-ENV-OVERRIDES.md for secrets, overrides, and optional local_env_prepare / local_env_link. docs/QUICK-START.md is the shortest path from clone to running (Docker infra + npm run dev:all).

Run

From the repo root, run make local_env_setup before commands that need generated env files (API, sidecars, infra/config/local/*). Do not rely on manual cp from .env.example for a full local stack.

API and web on host (Postgres and Valkey in Docker): After npm install and make local_env_setup, run make local_infra_up then npm run dev:all (or npm run dev:all:watch). See docs/QUICK-START.md.

API only:

make local_env_setup
npm run dev:api

Web only (no sidecar):

make local_env_setup
npm run dev:web

Web with sidecar (runtime config from env):

make local_env_setup
npm run dev:web-sidecar

This builds the sidecar, then starts the sidecar (default 4001) and the Next.js app (4002). RUNTIME_CONFIG_URL and sidecar env are written by local_env_setup; the app loads config from the sidecar at startup.

Env examples

• API: API_PORT, BRAND_NAME, API_JWT_SECRET, and optionally AUTH_MODE, MAILER_ENABLED (classification / generated apps/api/.env)
• Web: RUNTIME_CONFIG_URL in app (see apps/web/.env.example); sidecar templates under each app’s sidecar/ when present
• Exhaustive variable names, merge defaults (local_docker vs remote_k8s), and Kubernetes placement: docs/development/ENV-VARS-CATALOG.md (regenerate after classification changes: make env_catalog)
• Groups, merge order, and semantics: docs/development/ENV-REFERENCE.md

API auth

The API is versioned under a path prefix (default /v1; set API_VERSION_PATH to change, e.g. API_VERSION_PATH=/v2). Example: GET /v1/health, POST /v1/auth/login. Use JWT: send Authorization: Bearer <token> for protected routes (e.g. GET /v1/auth/me, POST /v1/auth/change-password). Set MAILER_ENABLED=true for self-service signup (POST /v1/auth/signup). When mailer is disabled (default or AUTH_MODE=admin_only), signup is disabled; user creation is handled by the Management API when the Management track (plans 31–33) is in use.

API_JWT_SECRET / MANAGEMENT_API_JWT_SECRET and all other passwords (DB, Valkey) are generated and written by make local_env_setup (or make env_setup). Do not put placeholder passwords in env examples; re-run make local_env_setup to create or refresh local env files. Override files (brand.env, management-superuser.env) are applied when present; use prepare/link to share them across work trees. See docs/development/LOCAL-ENV-OVERRIDES.md.

API docs (Swagger): With the API running, open http://localhost:4000/api-docs for interactive OpenAPI docs. Use Authorize to set a Bearer token from login/signup, then try protected endpoints.

Gitflow and CI

Default branch is develop; open PRs against develop. Use npm run start-feature to create branches (e.g. feature/name, fix/name). CI runs when a PR targets develop (on open/update) and when a maintainer comments /test on a PR. See docs/GITFLOW.md.

Scripts

• npm run build – Build all workspaces
• npm run dev:api – API only (port 4000)
• npm run dev:web – Web only (default port 4002)
• npm run dev:web-sidecar – Build sidecar, then run sidecar (4001) and web (4002)
• npm run dev:all – Build sidecar, then run API, sidecar, and web together
• npm run dev:api:watch – API with auto-rebuild on change (tsc --watch + nodemon)
• npm run dev:web:watch – Web (Next.js dev; already hot-reloads)
• npm run dev:all:watch – API, sidecar, and web with auto-rebuild on change
• npm run lint – ESLint + Prettier check (TS/JS, YAML, JSON, MD, etc.)
• npm run lint:fix – ESLint --fix + Prettier --write (fixes all supported files, including docker-compose)
• npm run prettier:check / npm run prettier:write – Prettier only

Version bump: Run ./scripts/publish/bump-version.sh when cutting a release. It updates root and all workspace package.json versions, then commits and pushes (no npm publish or image push).

Alpha publish: Merging to the alpha branch runs the Publish Alpha workflow and pushes Docker images (api, web, web-sidecar) to GHCR. See docs/PUBLISH.md.

GitHub labels: Run ./scripts/github/setup-all-labels.sh to create or update repo labels (requires gh auth login). See scripts/github/SCRIPTS-GITHUB.md and docs/repo-management/GITHUB-LABELS.md. For one-time repo setup (labels, branch protection, default branch), see docs/repo-management/GITHUB-SETUP.md. Dependency update policy and Dependabot (npm, Docker, Actions; Node LTS ≥ 24): docs/repo-management/DEPENDABOT.md.

LLM / Cursor

See .llm/LLM.md and AGENTS.md for history tracking and agent guidelines.