#Glossary
Key terms used throughout the tsdevstack documentation.
#Applications
| Term | Description |
|---|---|
| Service | A NestJS backend application. Names end with -service (e.g., auth-service, payments-service). Each service is a separate deployable unit. |
| Worker | Background job processor that runs alongside a service. Workers share the service's codebase but have a separate entry point (worker.ts). |
| Detached worker | A worker deployed to its own container for independent scaling. Registered via register-detached-worker command. |
| Frontend | A user-facing web application. Supports Next.js (SSR) and SPA (Rsbuild) types. |
| Short name | Service name without the -service suffix. Used in URLs (e.g., auth-service → /auth/). |
#Infrastructure
| Term | Description |
|---|---|
| Kong | Kong API gateway that handles routing, authentication, and rate limiting. All requests flow through Kong before reaching services. |
| Gateway | Synonym for Kong in this context. The entry point for all API traffic. |
| Route prefix | The URL path prefix for a service, derived from its short name (e.g., /auth/, /payments/). |
| Exact route | A generated Kong route that matches one OpenAPI path and its declared methods only. Undeclared paths, methods and trailing slashes get 404 at the gateway. See Gateway Routing. |
| Kong plugin | A gateway extension. Kong's bundled plugins are enabled in kong.user.yml; your own Lua plugins go in kong-plugins/ and are built into the gateway image. See Kong Plugins. |
| Framework Kong plugins | Plugins that ship with the CLI and are always in the gateway image: tsdevstack-strip-identity (removes client-sent identity headers), tsdevstack-api-key (checks API keys against Redis) and tsdevstack-api-prefix (removes /api from partner requests). |
| Cloud Map | AWS service discovery. Services and Kong reach each other at {service}.{project}.local inside the VPC. |
| Load balancer | Cloud-managed entry point that terminates TLS and routes traffic to Kong and frontends. ALB on AWS, Cloud Run's built-in LB on GCP, Container App ingress on Azure. |
| Bucket | An object storage container for files. MinIO locally, S3 (AWS), Cloud Storage (GCP), or Blob Storage (Azure) in the cloud. Added via add-bucket-storage. See Object Storage. |
| Terraform | Terraform by HashiCorp — the infrastructure-as-code tool used under the hood. You never write Terraform directly; the framework generates and applies it. |
#Configuration
| Term | Description |
|---|---|
| Framework config | .tsdevstack/config.json — central configuration for the framework. Contains project settings and service registry. |
| Infrastructure config | .tsdevstack/infrastructure.json — per-environment cloud settings (instance counts, database tier, domain). Generated by infra:generate. |
| Secrets files | .secrets.*.json files containing environment-specific secrets. See How Secrets Work. |
| Generated files | Files created by tsdevstack sync: Docker Compose, Kong config, the gateway Dockerfile, etc. Do not edit them; they are overwritten. |
#CI/CD & Deployment
| Term | Description |
|---|---|
| Environment | Deployment target: dev, staging, or prod. Each has isolated infrastructure and secrets. |
| CI workflows | GitHub Actions workflows generated for build, test, and deploy pipelines. |
| Scheduled job | A job that runs on a cron schedule. Cloud Scheduler (GCP), EventBridge (AWS), or Container App Jobs (Azure). Configured in .tsdevstack/infrastructure.json and deployed via deploy-scheduler. See Scheduled Jobs. |
| Database migration | Schema changes applied via Prisma Migrate. Preview with plan-db-migrate, apply with run-db-migrate. |
NPM_TOKEN | Single global GitHub repository secret (not per-env) for authenticating against private npm registries during host npm ci and tsdevstack-spawned docker builds. Auto-detected when .npmrc exists at project root. See Private npm packages. |
| BuildKit secret mount | Docker BuildKit --mount=type=secret,... directive that exposes a secret only during a single RUN step — never persisted in image layers, never visible in docker history. Used for NPM_TOKEN on the npm ci line in generated Dockerfiles. |
#Authentication
| Term | Description |
|---|---|
| JWT | JSON Web Token used for stateless authentication. Validated at the gateway level. |
| Access token | Short-lived JWT for API requests. |
| Refresh token | Longer-lived token for obtaining new access tokens. |
| Public endpoint | Route that doesn't require authentication. Marked with @Public() decorator. |
| Trust token | Secret (KONG_TRUST_TOKEN) that Kong adds to every forwarded request as X-Kong-Trust. Services only accept identity headers on requests that carry it. |
| System role | The framework-owned role of a user: USER or ADMIN (systemRole claim). See Roles. |
| Custom role | A product-defined role declared in the auth-service (roles claim). A user can hold several. Checked with @Roles(). |
ADMIN_EMAILS | Auth-service secret listing email addresses promoted to ADMIN at login. How the first admin is created. See Managing Users. |
| Partner API | API endpoints accessible via API key instead of JWT (@PartnerApi()). Exposed under /api/ prefix. See API Keys. |
| API key | A key for machine access to @PartnerApi() endpoints, sent in x-api-key. Belongs to a consumer, not a user; created and revoked at runtime through the auth-service admin API. |
| Consumer | The name an API key was issued to (for example acme-corp). Backends read it with @Partner(). |
#Observability
| Term | Description |
|---|---|
| Structured logging | JSON-formatted logs with consistent fields for querying. Powered by Pino. |
| Metrics | Prometheus-compatible measurements exposed at /metrics. |
| Tracing | Distributed request tracing via OpenTelemetry. Visualized in Jaeger. |
| Health check | Endpoint at /health reporting service status. |
#Development
| Term | Description |
|---|---|
| Monorepo | Single repository containing all apps and packages. Managed with npm workspaces and Lerna for task orchestration. |
| Package | Shared code library in packages/ directory. Used by multiple services. |
| Hot reload | Automatic restart when source files change during development. |
| OpenAPI spec | API documentation generated from NestJS decorators. Powers Swagger UI and client generation. |
| Generated client | Type-safe TypeScript HTTP client generated from a service's OpenAPI spec via generate-client. Placed in packages/shared/ for use by other services. |
| MCP | Model Context Protocol — the standard for AI agent tool integration. The built-in MCP server exposes 54 tools and 12 resources so agents like Claude Code can deploy, query, and debug your project. See MCP Server. |