> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Glossary

Key terms used throughout the tsdevstack documentation.

## Applications

| Term                | Description                                                                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Service**         | A [NestJS](https://nestjs.com/) 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](https://nextjs.org/) (SSR) and SPA ([Rsbuild](https://rsbuild.dev/)) types.                                          |
| **Short name**      | Service name without the `-service` suffix. Used in URLs (e.g., `auth-service` → `/auth/`).                                                                            |

## Infrastructure

| Term                       | Description                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kong**                   | [Kong](https://konghq.com/) 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](/docs/building-apis/gateway-routing.md#exact-routes).                                                                                                                                                    |
| **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](/docs/customization/kong-plugins.md).                                                                                                                                                                     |
| **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-client-ip` (identifies the frontend's visitors for rate limits), `tsdevstack-trust` (sets the trust header), `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. [RustFS](https://rustfs.com/) locally, S3 (AWS), Cloud Storage (GCP), or Blob Storage (Azure) in the cloud. Added via `add-bucket-storage`. See [Object Storage](/docs/features/object-storage.md).                                                                                                                                                |
| **Terraform**              | [Terraform](https://www.terraform.io/) 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](/docs/secrets/how-secrets-work.md).                |
| **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](/docs/features/scheduled-jobs.md).                                                  |
| **Database migration**    | Schema changes applied via [Prisma Migrate](https://www.prisma.io/docs/orm/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](/docs/infrastructure/cicd-setup.md#private-npm-packages). |
| **BuildKit secret mount** | Docker BuildKit `--mount=type=secret,...` directive that exposes a secret only during a single `RUN` step. It is 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](https://jwt.io/) 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](/docs/authentication/roles.md).                                                           |
| **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](/docs/authentication/managing-users.md).           |
| **Partner API**     | API endpoints accessible via API key instead of JWT (`@PartnerApi()`). Exposed under `/api/` prefix. See [API Keys](/docs/authentication/api-keys.md).                            |
| **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](https://getpino.io/).                                   |
| **Metrics**            | [Prometheus](https://prometheus.io/)-compatible measurements exposed at `/metrics`.                                                |
| **Tracing**            | Distributed request tracing via [OpenTelemetry](https://opentelemetry.io/). Visualized in [Jaeger](https://www.jaegertracing.io/). |
| **Health check**       | Endpoint at `/health` reporting service status.                                                                                    |

## Development

| Term                 | Description                                                                                                                                                                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Monorepo**         | Single repository containing all apps and packages. Managed with [npm workspaces](https://docs.npmjs.com/cli/using-npm/workspaces) and [Lerna](https://lerna.js.org/) 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](https://swagger.io/tools/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](https://modelcontextprotocol.io/), the standard for AI agent tool integration. The built-in MCP server exposes 57 tools and 12 resources so agents like Claude Code can deploy, query, and debug your project. See [MCP Server](/docs/features/mcp-server.md). |
