@horka/app-forge 0.1.0

package/templates/packs/vapor-api/Sources/Monitoring/Monitoring.swift

@@ -0,0 +1,110 @@
+import Foundation
+import Vapor
+import Prometheus
+import Metrics
+
+/// Process-global Prometheus registry.
+///
+/// `MetricsSystem.bootstrap` may only run ONCE per process, while tests boot many
+/// `Application`s — so both the registry and the bootstrap are anchored to the process
+/// (thread-safe lazy `static let`), never to an `Application`.
+public enum MetricsRegistry {
+    public static let shared: PrometheusCollectorRegistry = {
+        let registry = PrometheusCollectorRegistry()
+        MetricsSystem.bootstrap(PrometheusMetricsFactory(registry: registry))
+        return registry
+    }()
+}
+
+extension Application {
+    /// Storage key for the Prometheus registry (set when monitoring is enabled).
+    public struct PrometheusRegistryKey: StorageKey {
+        public typealias Value = PrometheusCollectorRegistry
+    }
+
+    /// Storage key for the /metrics bearer token.
+    public struct MetricsTokenKey: StorageKey {
+        public typealias Value = String
+    }
+}
+
+/// Raised at boot when monitoring is enabled but the bearer token is missing/blank.
+/// Surfaced as a named failure instead of a silent /metrics 401 forever (fail-fast doctrine).
+public struct MonitoringConfigurationError: Error, CustomStringConvertible {
+    public let description: String
+    public init(_ description: String) { self.description = description }
+}
+
+/// Wire monitoring into the app. Disabled → no registry in storage → /metrics returns 503.
+///
+/// Fail fast: with monitoring ENABLED, an empty/blank `metricsToken` would make a
+/// constant-time compare against "" reject every request — /metrics 401 forever, a silent
+/// misconfiguration that contradicts the env-discipline doctrine. We refuse to boot instead.
+public func configureMonitoring(app: Application, enabled: Bool, metricsToken: String) throws {
+    guard enabled else {
+        app.logger.info("[MONITORING] disabled")
+        return
+    }
+
+    guard !metricsToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+        throw MonitoringConfigurationError(
+            "MONITORING_ENABLED is true but METRICS_TOKEN is empty — set a non-empty token in "
+            + ".env AND env_dist AND every deploy manifest (an empty token leaves /metrics 401 "
+            + "forever). Disable monitoring or provide the token, then re-run."
+        )
+    }
+
+    app.storage[Application.PrometheusRegistryKey.self] = MetricsRegistry.shared
+    app.storage[Application.MetricsTokenKey.self] = metricsToken
+
+    app.logger.info("[MONITORING] enabled — backend: swift-prometheus")
+}
+
+/// The /metrics route handler: bearer-token gated (constant-time compare), emits the
+/// Prometheus text format. Lives here so the App target never imports Prometheus directly.
+public func handleMetricsRequest(_ req: Request) throws -> Response {
+    guard let registry = req.application.storage[Application.PrometheusRegistryKey.self],
+          let token = req.application.storage[Application.MetricsTokenKey.self] else {
+        throw Abort(.serviceUnavailable, reason: "Monitoring not configured")
+    }
+
+    guard let bearer = req.headers.bearerAuthorization else {
+        throw Abort(.unauthorized, reason: "Missing authentication token")
+    }
+
+    guard constantTimeCompare(bearer.token, token) else {
+        throw Abort(.unauthorized, reason: "Invalid authentication token")
+    }
+
+    var buffer: [UInt8] = []
+    registry.emit(into: &buffer)
+
+    var headers = HTTPHeaders()
+    headers.add(name: .contentType, value: "text/plain; version=0.0.4; charset=utf-8")
+    return Response(status: .ok, headers: headers, body: .init(string: String(decoding: buffer, as: UTF8.self)))
+}
+
+/// Increment the HTTP error counter (called by the typed-error middleware). Counter
+/// emission is an L1 concern — feature code never touches the metrics API directly.
+public func recordHTTPError(status: UInt, errorName: String) {
+    Counter(label: "http_errors_total",
+            dimensions: [("status", "\(status)"), ("error", errorName)]).increment()
+}
+
+/// Constant-time comparison to prevent timing attacks on the bearer token.
+/// Always iterates over the max length of both inputs to avoid leaking length information.
+public func constantTimeCompare(_ lhs: String, _ rhs: String) -> Bool {
+    let lhsData = Array(lhs.utf8)
+    let rhsData = Array(rhs.utf8)
+    let maxLen = max(lhsData.count, rhsData.count)
+
+    // Length mismatch must still fail, but without an early return.
+    var accumulator: UInt8 = lhsData.count == rhsData.count ? 0 : 1
+
+    for i in 0..<maxLen {
+        let lhsByte: UInt8 = i < lhsData.count ? lhsData[i] : 0
+        let rhsByte: UInt8 = i < rhsData.count ? rhsData[i] : 0
+        accumulator |= lhsByte ^ rhsByte
+    }
+    return accumulator == 0
+}

package/templates/packs/vapor-api/Sources/{{PROJECT_NAME}}Foundation/String+Trimmed.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+// L0 helper — primitives only. This target depends on nothing; keep it that way.
+public extension String {
+    /// Whitespace/newline-trimmed copy. Services normalize user input with this
+    /// before persisting (storage rule: names are stored trimmed).
+    var trimmed: String {
+        trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    /// True when the string is empty after trimming.
+    var isBlank: Bool {
+        trimmed.isEmpty
+    }
+}

package/templates/packs/vapor-api/Tests/AppTests/AppTests.swift

@@ -0,0 +1,155 @@
+import Testing
+import VaporTesting
+import Vapor
+@testable import App
+@testable import Monitoring
+
+@Suite("{{PROJECT_NAME}} API — boot + contracts")
+struct AppTests {
+    /// Boots the FULL app in `.testing` (in-memory SQLite + real migrations + real
+    /// middleware stack), runs the body, always shuts down. Each test gets a fresh app
+    /// and a fresh database — tests stay order-independent and parallel-safe.
+    private func withApp(_ body: (Application) async throws -> Void) async throws {
+        let app = try await Application.make(.testing)
+        do {
+            try await configure(app)
+            try await body(app)
+        } catch {
+            try? await app.asyncShutdown()
+            throw error
+        }
+        try await app.asyncShutdown()
+    }
+
+    @Test("GET /health responds 200")
+    func healthCheck() async throws {
+        try await withApp { app in
+            try await app.testing().test(.GET, "health") { res async in
+                #expect(res.status == .ok)
+                #expect(res.body.string.contains("ok"))
+            }
+        }
+    }
+
+    @Test("POST /api/items persists, trims the name (L3 rule), returns the DTO")
+    func createItem() async throws {
+        try await withApp { app in
+            try await app.testing().test(.POST, "api/items", beforeRequest: { req in
+                try req.content.encode(App.Item.DTO.Input(name: "  First item  "))
+            }, afterResponse: { res async throws in
+                #expect(res.status == .ok)
+                let output = try res.content.decode(App.Item.DTO.Output.self)
+                #expect(output.name == "First item") // trimming lives in the Service, not the controller
+            })
+
+            try await app.testing().test(.GET, "api/items") { res async throws in
+                #expect(res.status == .ok)
+                let items = try res.content.decode([App.Item.DTO.Output].self)
+                #expect(items.count == 1)
+            }
+        }
+    }
+
+    @Test("Blank name → typed error contract {code, name, description}")
+    func typedErrorContract() async throws {
+        try await withApp { app in
+            try await app.testing().test(.POST, "api/items", beforeRequest: { req in
+                try req.content.encode(App.Item.DTO.Input(name: "   "))
+            }, afterResponse: { res async throws in
+                #expect(res.status == .badRequest)
+                let error = try res.content.decode(
+                    App.Failed.Middlewares.Handler.ErrorDescription.self
+                )
+                #expect(error.code == 400)
+                #expect(error.name == "dataNotValid") // case name = stable public identifier
+            })
+        }
+    }
+
+    @Test("Duplicate name → 409 dataAlreadyExist")
+    func duplicateItem() async throws {
+        try await withApp { app in
+            for expected in [HTTPStatus.ok, .conflict] {
+                try await app.testing().test(.POST, "api/items", beforeRequest: { req in
+                    try req.content.encode(App.Item.DTO.Input(name: "Twice"))
+                }, afterResponse: { res async in
+                    #expect(res.status == expected)
+                })
+            }
+        }
+    }
+
+    @Test("Monitoring enabled with an EMPTY token fails fast at boot (no silent /metrics 401)")
+    func monitoringEmptyTokenFailsFast() async throws {
+        let app = try await Application.make(.testing)
+        do {
+            #expect(throws: MonitoringConfigurationError.self) {
+                try configureMonitoring(app: app, enabled: true, metricsToken: "")
+            }
+            #expect(throws: MonitoringConfigurationError.self) {
+                try configureMonitoring(app: app, enabled: true, metricsToken: "   ")
+            }
+            // Disabled → blank token is fine (no metrics endpoint).
+            #expect(throws: Never.self) {
+                try configureMonitoring(app: app, enabled: false, metricsToken: "")
+            }
+        } catch {
+            try? await app.asyncShutdown()
+            throw error
+        }
+        try await app.asyncShutdown()
+    }
+
+    @Test("Duplicate name under concurrency → exactly one insert, the rest 409 (DB unique constraint)")
+    func duplicateNameRace() async throws {
+        try await withApp { app in
+            // Fire many concurrent creates of the SAME name. With a TOCTOU check-then-insert and
+            // no DB constraint, several would slip through; the unique index + typed-409 mapping
+            // guarantees exactly one success.
+            let name = "RaceMe"
+            await withTaskGroup(of: HTTPStatus.self) { group in
+                for _ in 0..<8 {
+                    group.addTask {
+                        var status: HTTPStatus = .internalServerError
+                        do {
+                            try await app.testing().test(.POST, "api/items", beforeRequest: { req in
+                                try req.content.encode(App.Item.DTO.Input(name: name))
+                            }, afterResponse: { res async in
+                                status = res.status
+                            })
+                        } catch {
+                            status = .internalServerError
+                        }
+                        return status
+                    }
+                }
+                var okCount = 0
+                for await status in group {
+                    if status == .ok { okCount += 1 } else { #expect(status == .conflict) }
+                }
+                #expect(okCount == 1)
+            }
+        }
+    }
+
+    @Test("/metrics is bearer-token gated (constant-time compare)")
+    func metricsTokenGate() async throws {
+        try await withApp { app in
+            try await app.testing().test(.GET, "metrics") { res async in
+                #expect(res.status == .unauthorized)
+            }
+
+            var wrong = HTTPHeaders()
+            wrong.bearerAuthorization = .init(token: "not-the-token")
+            try await app.testing().test(.GET, "metrics", headers: wrong) { res async in
+                #expect(res.status == .unauthorized)
+            }
+
+            var headers = HTTPHeaders()
+            headers.bearerAuthorization = .init(token: "test-metrics-token")
+            try await app.testing().test(.GET, "metrics", headers: headers) { res async in
+                #expect(res.status == .ok)
+            }
+        }
+    }
+}

package/templates/packs/vapor-api/claude/memory/COMMANDS.md

@@ -0,0 +1,30 @@
+# {{PROJECT_NAME}} — Commands
+
+> Only commands proven to work in THIS project, with exact flags.
+
+## Build & test (fast loop — always first)
+swift build
+swift test
+swift test --filter AppTests        # one suite
+
+## Run locally
+cp env_dist .env                    # once — then fill values (never commit .env)
+docker run -d --name {{PROJECT_NAME}}-db -p 5432:5432 \
+  -e POSTGRES_USER=vapor_username -e POSTGRES_PASSWORD=vapor_password \
+  -e POSTGRES_DB=vapor_database postgres:16-alpine
+swift run App serve --hostname 127.0.0.1 --port 8080
+swift run App serve --log debug     # one-off verbosity bump
+curl -s localhost:8080/health       # liveness proof
+
+## Database
+swift run App migrate               # run pending migrations manually
+swift run App migrate --revert      # revert the last batch
+
+## Quality gates (before any ship)
+bash scripts/validate-env-vars.sh   # AppConfig.Key ↔ env_dist ↔ manifests
+bash scripts/generate-error-codes.sh   # regenerate docs/ERROR_CODES.md from Failed.swift
+docker run --rm -v "$PWD:/src" -w /src swift:6.2-noble swift test   # Linux gate
+
+## Docker image
+docker build -t {{BUNDLE_ID}} .
+docker run --rm -p 8080:8080 --env-file .env {{BUNDLE_ID}}

package/templates/packs/vapor-api/docs-architecture/ARCHITECTURE.md

@@ -0,0 +1,144 @@
+# ARCHITECTURE — Layered Vapor API (Swift 6, server-side)
+
+Pattern for Vapor 4 APIs deployed on Linux. The service is assembled from SPM targets
+(compiler-enforced walls) + role folders inside the App target (convention-enforced,
+grep-verifiable). Read `ARCHITECTURE_PRINCIPLES.md` first — this maps it onto Swift.
+
+## 1. Layer Model — Swift instantiation of the universal L0–L5 contract
+
+```
+L5  COMPLETE FEATURES   Sources/App/Configure/    entrypoint, configure, routes, AppConfig (composition root)
+                        Features/<F>/Controllers/ HTTP boundary: routes, decode/encode DTOs
+                        Features/<F>/DTO/          wire types (Input/Output Content structs)
+L4  SHARED FEATURES     created on demand: logic needed by ≥2 feature modules gets its own
+                        SPM target (e.g. an auth or billing module). Don't pre-create.
+L3  CORE LOGIC          Features/<F>/Services/     BUSINESS RULES: validation, normalization,
+                                                   typed errors, orchestration
+                        Features/<F>/Entities/     Fluent models (domain shape + persistence mapping)
+L2  DATA                Features/<F>/Repositories/ data access ONLY — answers "what does the DB say"
+                        Features/<F>/Migrations/   schema changes (append-only)
+                        Features/<F>/Jobs/         queued/scheduled work (created when needed; calls Services)
+                        Sources/<X>Client/         one SPM target per external API (AsyncHTTPClient)
+L1  OPS                 Sources/Monitoring/        SPM target: JSON logs, HTTP timing, metrics registry
+L0  FOUNDATION          Sources/{{PROJECT_NAME}}Foundation/  SPM target: pure primitives, ZERO dependencies
+```
+
+Notes on the mapping:
+- **Targets enforce the big walls.** Foundation and Monitoring cannot import App — the
+  compiler guarantees it. External-API clients live in their own targets so they build
+  and test without booting the app.
+- **Folders enforce the rest.** Inside the App target, layers are roles within a feature
+  module. The compiler can't help there, so the rules below must be grep-checkable.
+- **Third-party frameworks are not layers.** Monitoring (L1) imports Vapor as
+  infrastructure; the dependency rule governs imports between PROJECT bricks only.
+
+## 2. Dependency Direction Rules
+
+| Layer | May use | Must NEVER use | Why |
+|---|---|---|---|
+| Controllers (L5) | Services, DTO, `App.Failed` | Fluent queries, Repositories directly | HTTP translation only — logic in services stays testable without HTTP |
+| Services (L3) | Repositories, Entities, Foundation, `App.Failed` | `Request`, `Response`, HTTP types | Services take plain values; one service = one testable unit |
+| Repositories (L2) | Fluent + Entities | `App.Failed` business errors, Services, validation | A repository reports DB facts; deciding what they MEAN is L3 |
+| Migrations (L2) | Fluent schema builder | Entities' current code for data backfill | A migration must stay valid when the model changes later |
+| Monitoring (L1) | Vapor, metrics libs | anything in App | Reusable across services; no domain knowledge |
+| Foundation (L0) | Swift stdlib + Foundation | everything else | Primitives stay portable and instantly testable |
+
+Grep checks (run them when in doubt — empty output = healthy):
+```bash
+grep -rn "query(on:" Sources/App/Features/*/Controllers/   # controllers bypassing services
+grep -rn "import Vapor" Sources/App/Features/*/Services/   # services seeing HTTP (Request/Response live in Vapor)
+grep -rn "App.Failed" Sources/App/Features/*/Repositories/ # repositories making decisions
+grep -rn "URLSession" Sources/                             # forbidden — GOTCHAS_LINUX_SWIFT.md
+```
+
+## 3. Feature modules — the unit of growth
+
+One folder per feature under `Sources/App/Features/`, everything colocated by role.
+`Features/Item/` is the REFERENCE module — copy its shape:
+
+```
+Features/Item/
+├── AppItem.swift            namespace + registration surfaces (the module's front door)
+├── Controllers/             RouteCollections
+├── DTO/                     Input/Output Content structs
+├── Entities/                Fluent models
+├── Migrations/              append-only schema changes
+├── Repositories/            data access
+└── Services/                business logic
+```
+
+The namespace is an enum: `extension App { enum Item { … } }` — call sites read as domain
+language (`App.Item.Service`), and registration is type-scoped, not global.
+
+> ⚠️ **Gotcha:** Symptom — two features need the same service and one starts importing the
+> other's folder. Cause — sideways dependency between sibling features. Fix — promote the
+> shared logic to its own SPM target (L4) and have both features depend on it. A feature
+> never reaches into a sibling feature.
+
+## 4. Auto-registration — one line per feature, ever
+
+Three protocols in `Sources/App/Registry/` (`ControllersRegister`, `MigrationsRegister`,
+`MiddlewaresRegister`) give every module the same wiring surface:
+
+```swift
+// In the module:  AppItem.swift
+extension App.Item.Controllers: ControllersRegister {
+    static func allCases() -> [any RouteCollection] { [Crud()] }
+}
+
+// In Configure/routes.swift — the ONLY line the rest of the app sees:
+try App.Item.Controllers.register(app: app)
+```
+
+Adding a feature touches exactly two central lines: its controllers in `routes.swift`,
+its migrations in `configure.swift`. Everything else stays inside the module folder.
+This is what keeps agent diffs small: a new endpoint never rewrites the bootstrap.
+
+## 5. Migration ordering — explicit, central, load-bearing
+
+`configure.swift > migrationsInit` registers every module's migrations **in an explicit
+sequence**. Fluent runs them in registration order; a schema referencing another table
+(foreign key) must be registered after that table's `Create`.
+
+> ⚠️ **Gotcha:** Symptom — fresh deploy crashes with `relation "xxx" does not exist`,
+> while every dev machine boots fine. Cause — dev databases migrated incrementally over
+> weeks, so ordering bugs stay invisible; only a from-scratch migration run exposes them.
+> Fix — order registrations by foreign-key dependency, comment WHY a module is positioned
+> where it is, and verify every migration change against a scratch database (drop +
+> re-migrate) before shipping.
+
+## 6. Where Does a New File Go?
+
+| You are adding… | It lives in… |
+|---|---|
+| A new endpoint for an existing feature | `Features/<F>/Controllers/` (+ DTO if the shape changes) |
+| A business rule (validation, limits, workflow) | `Features/<F>/Services/` |
+| A query, a DB lookup | `Features/<F>/Repositories/` |
+| A schema change | `Features/<F>/Migrations/` — NEW file, registered after its FK targets |
+| A queued/scheduled job | `Features/<F>/Jobs/` (conform a JobsRegister-style surface) |
+| A whole new feature | `Features/<NewF>/` copied from the Item module shape |
+| A new error case | `Sources/App/Error/Failed.swift` + regenerate ERROR_CODES (CONVENTIONS.md) |
+| A new environment variable | `AppConfig.Key` + `env_dist` + manifests (CONVENTIONS.md) |
+| An external API client | new SPM target `Sources/<X>Client/` using AsyncHTTPClient |
+| A log/metric/middleware concern | `Sources/Monitoring/` |
+| A pure helper (string, date, parsing) | `Sources/{{PROJECT_NAME}}Foundation/` |
+
+## 7. Why This Works Exceptionally Well With AI Agents
+
+- **Fast ground truth without infrastructure.** `swift test` boots the real app on
+  in-memory SQLite — full middleware stack, real migrations, zero services to start.
+- **Compiler-enforced walls where it counts.** An agent that makes Monitoring import App
+  code gets a build error, not a slow architectural rot.
+- **Grep-visible violations everywhere else.** Every folder rule above has a one-line
+  grep; agents can self-audit before claiming done.
+- **Predictable file placement.** The feature-module shape means an agent knows the 5–7
+  files a feature needs; diffs stay small and reviewable.
+- **The error contract is testable.** Typed errors make failure paths assertable
+  (`#expect(error.name == "dataNotValid")`) — failure behavior survives refactors.
+
+Build matrix an agent should run before claiming "done":
+```bash
+swift build && swift test                                   # full stack on the host
+docker run --rm -v "$PWD:/src" -w /src swift:6.2-noble swift test   # Linux = the real target
+bash scripts/validate-env-vars.sh                           # config drift check
+```

package/templates/packs/vapor-api/docs-architecture/CONVENTIONS.md

@@ -0,0 +1,121 @@
+# CONVENTIONS — Server-Side Swift (Vapor 4, Swift 6 strict concurrency)
+
+Prescriptive — follow as written. The layer rules live in `ARCHITECTURE.md`; this file is
+about HOW each kind of code is written.
+
+## 1. Feature module anatomy
+
+- Namespace enum per feature: `extension App { enum Item { enum Controllers {}; enum Migrations {}; enum DTO {} } }`.
+  Sub-enums exist ONLY for roles the feature actually has — don't pre-create empty ones.
+- **One type per file**; file name = feature + role + type: `ItemControllersCrud.swift`,
+  `ItemEntity.swift`, `ItemMigrationCreate.swift`, `ItemService.swift`, `ItemRepository.swift`.
+- The front-door file (`AppItem.swift`) holds the namespace + ALL registration conformances —
+  reading one file tells you everything the module plugs into.
+- Checklist for a new feature `Foo`:
+  1. Copy the `Features/Item/` shape → `Features/Foo/`.
+  2. Conform `App.Foo.Controllers: ControllersRegister`, `App.Foo.Migrations: MigrationsRegister`.
+  3. Add `try App.Foo.Controllers.register(app: app)` to `routes.swift`.
+  4. Add `App.Foo.Migrations.register(app: app)` to `configure.swift` — positioned AFTER
+     every table its schema references.
+  5. Write the feature test (boot + endpoint + typed-error case) in `Tests/AppTests/`.
+
+## 2. Typed errors — the public failure contract
+
+Every intentional failure is a case of an enum in `Sources/App/Error/Failed.swift`:
+
+```swift
+enum BadRequest: CustomError {
+    case dataNotValid
+    func convert() -> HTTPStatus { .badRequest }   // ONE line — the generator parses this
+}
+// usage, in a Service:
+guard !cleanName.isEmpty else { throw App.Failed.BadRequest.dataNotValid }
+```
+
+The middleware (`FailedMiddleware.swift`) serializes any thrown case as
+`{"code": 400, "name": "dataNotValid", "description": "Bad Request"}` and increments the
+error counter. Rules:
+
+- **Feature code never throws raw `Abort`** and never builds error Responses by hand.
+  `Abort` is tolerated only in infrastructure handlers (e.g. the /metrics gate).
+- The **case name is the public identifier** — clients match on it. Renaming a case is a
+  breaking API change; treat it like one.
+- Throw from **Services** (business decisions) and Controllers (HTTP-shape problems like
+  undecodable JSON). Repositories return facts (`nil`, `false`), never typed errors.
+- `docs/ERROR_CODES.md` is **GENERATED** from the enum by `scripts/generate-error-codes.sh`.
+  Never write it by hand; regenerate in the same commit that touches `Failed.swift`.
+  A hand-written error table starts lying the week after it's written — the generated one
+  cannot lie.
+
+> ⚠️ **Gotcha:** Symptom — a client breaks on an error response with a shape nobody
+> documented. Cause — someone threw `Abort(.badRequest, reason: "…")` in feature code,
+> which bypasses the typed contract and produces Vapor's `{"error": true, "reason": …}`
+> shape instead. Fix — grep `Abort(` over `Features/` in review; it should only hit
+> infrastructure files.
+
+## 3. Environment variables — typed, fail-fast, cross-checked
+
+ONE pattern, no exceptions (`Sources/App/Configure/AppConfig.swift`):
+
+- Every variable is a case of `AppConfig.Key` (CaseIterable). `Key.get` fail-fasts with
+  the variable's NAME if missing — the service dies at boot, not at the first request
+  that needed the value.
+- `Environment.get` is called nowhere else. If you need a new value: add the Key case,
+  add a typed property on `AppConfig`, add the line to `env_dist`, add it to every deploy
+  manifest, run `bash scripts/validate-env-vars.sh`.
+- Tests get `AppConfig.testing` through an EXPLICIT branch on `app.environment == .testing`
+  — never sniff the test runner from process arguments, env leftovers, or CI flags. The
+  environment is a parameter, not a guess.
+- Config reaches code via `Application.storage` (`app.config` / `req.config`) — no global
+  singleton. Singletons hide the dependency and make per-test configuration impossible.
+- `LOG_LEVEL` is the single sanctioned exception: read in `entrypoint.swift` before
+  config exists (logging must work even when configuration is broken).
+
+> ⚠️ **Gotcha:** Symptom — deploy green, then the service dies at boot with a missing
+> variable that "was added weeks ago". Cause — the variable was added to code and the dev
+> .env, but never to the production manifest; nothing cross-checked them. Fix — the
+> validate script runs in CI and blocks the merge, not the deploy.
+
+## 4. DTOs — the wire contract
+
+- `DTO.Input` / `DTO.Output` structs conforming to `Content`, one pair per resource shape.
+- **Entities never serialize directly.** The entity is a persistence detail; the DTO is
+  the public API. Renaming a DB column must never be an API-breaking change.
+- `Output.init(entity:)` is the single mapping point — `try entity.requireID()` there,
+  so an unsaved entity fails loudly instead of emitting a null id.
+- Decode with intent: `guard let input = try? req.content.decode(...) else { throw App.Failed.BadRequest.jsonNotDecodable }`
+  — undecodable JSON is a typed 400, not a Vapor default.
+
+## 5. Concurrency (Swift 6, strict)
+
+- Route handlers are `@Sendable` funcs on a struct `RouteCollection`.
+- Services and Repositories are `Sendable` structs holding `let db: any Database` —
+  created per request, no shared mutable state.
+- Fluent models are `final class … Model, @unchecked Sendable` — the ONLY tolerated
+  `@unchecked` in the codebase, imposed by Fluent. Containment rule in
+  `GOTCHAS_LINUX_SWIFT.md`: entities never leave the request scope.
+- **No `Task.detached`, no fire-and-forget `Task {}`** in request handlers. Work that
+  outlives the request goes through a queued Job (see GOTCHAS — request-scoped resources
+  die with the request).
+- Process-wide one-time setup (metrics registry, log bootstrap) anchors to a lazy
+  `static let` — thread-safe by language guarantee, no locks to get wrong.
+
+## 6. Logging
+
+- Always through `req.logger` / `app.logger` (request-scoped loggers carry request IDs).
+  Never `print()` — invisible to the structured pipeline.
+- **Values go in metadata, not in the message string**: the message is a stable label,
+  metadata keys are queryable (`"duration_ms"`, `"path"`, `"error_type"`).
+- Every `catch` that swallows or converts an error logs the operation name + the error.
+- Never log secrets, tokens, or full request bodies. Probe paths (/health, /metrics) are
+  excluded from request logs by `HTTPLoggingMiddleware` — keep it that way.
+
+## 7. Naming quick reference
+
+- Actions are verbs (`create`, `list`); queries are nouns; booleans read as assertions
+  (`isBlank`, `monitoringEnabled`).
+- Routes: plural resources, kebab-case path segments (`/api/items`, `/api/team-invites`).
+- DB: snake_case columns, plural snake_case tables (`created_at`, `items`).
+- Migrations: `Create`, `AddXxx`, `FixXxx` — named for what they do, append-only.
+- Names express intent, not technology (`ItemRepository`, not `ItemDBManager`).
+- Comments explain WHY (the decision, the trap), never what the code already says.