Glossary
Glossary
Project-specific terms used across the docs, collected here so you do not have to hunt definitions page by page.
4
core categories
Gitignored
config
Lint-enforced
contract
Architecture vocabulary
Section titled “Architecture vocabulary”The workspace apps
The folders that compose BoringStack’s runtime: apps/api, apps/ui, and infra/compose. They live in one monorepo so Compose, CI, and docs can reference every layer through stable relative paths. infra/bootstrap provisions a VPS via OpenTofu and is optional.
Feature folder
A single directory per feature (src/api/<feature>/, src/features/<feature>/). Holds the routes, services, types, and tests for that one feature. The unit of independent change. The apps/api ships auth, users, billing, dashboard, admin, health as framework features; no demo domain resource. Read more.
Route / service / types split
The API app’s per-feature pattern. For a hypothetical posts resource: posts.routes.ts does HTTP only, posts.service.ts does business logic + DB, posts.types.ts holds the shapes shared between them. Enforced by ESLint. Read more.
Component anatomy
The UI app’s per-component pattern. A page like DashboardPage/ is a folder of ~8 files (.tsx, .hooks.ts, .types.ts, .constants.ts, .utils.ts, .test.tsx, .stories.tsx, index.ts). Read more.
View object
The shape a hook returns to its component (IDashboardPageView returned by useDashboardPage). The component never reads queries, stores, or env directly; it only renders the view object. Decouples logic from JSX.
Module boundary
The lint-enforced rule that a file can have one semantic concern. No mixing routes + services + utils in one file. Enforced by @boring-stack-pkg/eslint-plugin-module-boundaries.
Infra vocabulary
Section titled “Infra vocabulary”Stack
The deployment target: STACK=dev or STACK=prod. Picks which compose overlay (HTTP routes + host ports for dev, HTTPS + ACME for prod) gets merged on top of the base.
Overlay
An opt-in docker-compose.<name>.yml file that adds services to the base stack. Activated by a WITH_<NAME>=1 env var. Overlays compose freely (e.g. WITH_OBSERVABILITY=1 WITH_GLITCHTIP=1). Read more.
Profile
A docker-compose feature for grouping services within a single file. The infra stack uses profiles (--profile dev, --profile observability) alongside overlays; profiles activate services within a file, overlays add files.
Base stack
The always-on services: Postgres + Valkey + api-migrate (one-shot) + the app containers. Traefik is in the prod profile only; dev uses Vite’s dev-server proxy. Everything else is an overlay.
Data plane
Postgres + Valkey. The services that hold state. Deliberately not exposed to the frontend Docker network, so the only path from the world to the data plane is through the API.
Valkey
The BSD-licensed Redis-protocol-compatible store BoringStack uses for cache + queues. Drop-in compatible with Redis: same wire protocol, same client libraries (ioredis, BullMQ). Env vars are renamed VALKEY_HOST / VALKEY_PORT / VALKEY_PASSWORD / VALKEY_DB so the operator-facing names match the binary; third-party containers (bull-board, GlitchTip) still read their own REDIS_* env names internally, with our compose overlays bridging the value. Maintained by the Linux Foundation with AWS, Google, and Oracle as primary sponsors.
Architecture rules vocabulary
Section titled “Architecture rules vocabulary”The contract
Shorthand for “the rules the ESLint plugins enforce.” When something is “in the contract,” violating it fails bun run validate. The phrase emphasizes that the lint is load-bearing, not the prose docs. Read more.
Fire-and-forget
A call site that intentionally doesn’t await a Promise. Used for audit-log writes and other telemetry where failure must never propagate to the caller. The void prefix marks the intent for both readers and the linter.
Pluggable provider
An interface with multiple concrete implementations, selected by env var. Used for email, AI, and cache. The interface is the contract; the implementations are interchangeable.
Data + persistence
Section titled “Data + persistence”Drizzle
The TypeScript-first ORM the apps/api uses for Postgres. Schema-as-TS, migrations as generated SQL files, queries that look like SQL but are typed. Picked over Prisma because there’s no shadow database and migrations are plain SQL.
Schema (Postgres)
A namespace within a database. The apps/api uses two: public (app tables) and audit (the audit log). Keeping them separate lets you grant, archive, or migrate them independently.
Audit log
The append-only audit.audit_log table. Records security- and compliance-relevant events. Fire-and-forget; writes never block requests. Read more.
Background work
Section titled “Background work”Queue
A named work buffer in Valkey, owned by a directory under src/queues/<name>/. Producers enqueue; workers consume. The directory follows a fixed pattern (constants, types, queue, worker, setup) so producer + consumer can’t drift on names.
QueueManager
The process-singleton that owns all queues + workers. Application code never imports BullMQ’s Queue class directly; it calls manager.enqueueX(...). Read more.
Idempotent
A job that produces the same result if run twice. BullMQ retries on failure, so workers must be idempotent. Patterns: natural keys, UNIQUE constraints with caught violations, check-then-do inside a transaction.
dev.sh
The infra orchestrator. Forwards every argument to docker compose with the right overlay + profile flags based on STACK= and WITH_*= env vars. Plain bash; you can read what it does.
bun run validate / bun run validate
The merge gate. Typecheck + lint + tests. A PR can’t merge if validate fails. The phrase “the merge gate” anywhere in the docs means this command.
Related
Section titled “Related”- Repository layout; where the monorepo workspaces live and how they connect.
- Stack at a glance; the dependency inventory behind the vocabulary.
- Profiles & overlays; overlay vs profile in practice.
- Commands cheatsheet; what to type for each term.
- Lint as the contract; the rules these terms refer back to.