support_backend/specs/001-ci-pipeline/research.md

# Phase 0 Research: Continuous Integration Pipeline

No `NEEDS CLARIFICATION` markers remained in the Technical Context after `/speckit-plan`'s
Technical Context pass — this document records the decisions behind that context rather than
resolving open unknowns.

## Decision: CI system — Jenkins declarative pipeline

- **Decision**: Use a single `Jenkinsfile` (declarative syntax) at the repo root.
- **Rationale**: The constitution's Technology & Platform Constraints section and
  `docs/09-testing-observability-cicd.md` §3 both name Jenkins explicitly, with a defined stage
  order. This isn't a free choice — using anything else would need a constitution amendment.
- **Alternatives considered**: GitHub Actions / GitLab CI — rejected only because the governing
  docs already commit to Jenkins; otherwise equally viable for this repo's needs.

## Decision: Environment/secrets handling in the pipeline

- **Decision**: The pipeline injects `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `JWT_SECRET`, and AWS
  credentials from Jenkins' credentials store as environment variables / a generated `.env.*`
  file written into the workspace at runtime — never read from a file committed to the
  repository.
- **Rationale**: `.env.development`, `.env.test`, and `.env.prod` were found committed to git
  with real dev credentials in plain text (fixed separately: untracked, `.env.example` added,
  see repo commit `2093898`). `docker-compose.test.yml`'s `app` service still declares
  `env_file: .env.test`, so the pipeline's test stage must materialize a `.env.test` in the
  workspace from Jenkins credentials immediately before `docker compose up`, then discard it when
  the stage ends — the checked-in `.env.test` template must only ever contain non-secret
  placeholder values from here on, matching `.env.prod`'s existing `CHANGE_ME` pattern.
  Production deploy correspondingly generates `.env.prod` the same way, from Jenkins prod
  credentials, never from the repo copy.
- **Alternatives considered**: Docker secrets / mounted files instead of generated `.env` files —
  viable but a larger change to `docker-compose.*.yml`; deferred as out of scope since it doesn't
  change the pipeline's external behavior (FR-008 is satisfied either way).

## Decision: Environment validation stage

- **Decision**: The environment-validation stage runs the existing `env.ts` Zod schema
  (`src/config/env.ts`) against the materialized environment before any test stage starts, by
  invoking a lightweight script (e.g. `node --env-file=.env.<target> -e "require('./dist/src/config/env.js')"`
  post-build, or a dedicated `tsx` invocation pre-build) so a missing/malformed variable fails
  immediately with the schema's existing descriptive Zod error, satisfying FR-002.
- **Rationale**: `src/config/env.ts` already throws a specific, actionable error
  (`❌ Invalid environment variables: ...`) on `safeParse` failure — no new validation logic is
  needed, just an early pipeline invocation of the existing one.
- **Alternatives considered**: A separate shell script re-implementing required-var checks —
  rejected as duplicate logic that could drift from the real Zod schema.

## Decision: Quality stage contents

- **Decision**: Stage-to-script mapping is direct:
  - `install` → `npm ci`
  - `typecheck` → `npm run typecheck`
  - `lint` → `npm run lint` (consider folding `scripts/check-architecture.ts`'s module-boundary
    check into this stage, since it enforces constitution Principle III and already runs in
    `.husky/pre-commit` — confirmed as in-scope, see Assumptions below)
  - `format check` → `npm run format:check`
  - `unit test` → `npm run test:unit`
  - `integration test` → `npm run test:integration` (requires `docker-compose.test.yml`'s
    `postgres`/`redis` services running first)
  - `e2e test` → `npm run test:e2e` (same dependency)
  - `build` → `npm run build:prod` (or `build:test`/`build:development` depending on target,
    matching the `BUILD_COMMAND` pattern already used by each `docker-compose.*.yml`)
  - `docker build` → `docker build` using the existing root `Dockerfile`
- **Rationale**: Every stage maps to a script that already exists and is already exercised
  locally/in the pre-commit hook — the pipeline's job is orchestration and environment isolation,
  not defining new checks (matches plan.md's Summary).
- **Alternatives considered**: None — this mapping is essentially forced by "don't introduce new
  checks" (spec.md Assumptions).

## Decision: Publish/deploy mechanism

- **Decision**: `publish` pushes the built image to a container registry (registry choice left to
  implementation/tasks phase — no registry is currently configured in the repo); `deploy` runs
  `docker compose --env-file <generated .env> -f docker-compose.<target>.yml up -d` on the target
  host/agent, reusing the `docker:up:*` npm scripts' underlying compose invocation.
- **Rationale**: The repo already models per-environment deployment as
  `docker compose -f docker-compose.<env>.yml up -d` (see `docker:up:dev`, `docker:up:test`,
  `docker:up:prod` in `package.json`) — the pipeline should drive the same mechanism an engineer
  would run by hand today, not invent a new one.
- **Alternatives considered**: Kubernetes/Helm deploy — no k8s manifests exist in the repo today;
  out of scope unless a future feature introduces them.

## Decision: Concurrent-run isolation (FR-009)

- **Decision**: Rely on Jenkins' per-build workspace isolation (each pipeline run gets its own
  workspace directory and, for the Docker-dependent stages, project-scoped Compose project names
  e.g. `-p support-test-${BUILD_NUMBER}`) rather than building custom isolation logic.
- **Rationale**: This is a built-in Jenkins guarantee once each build uses its own workspace and
  Compose project name; no additional application code is needed.
- **Alternatives considered**: None needed — default Jenkins behavior already satisfies this when
  Compose project names are parameterized by build number.

## Assumptions carried over from spec.md, confirmed against the codebase

- `package.json` scripts (`typecheck`, `lint`, `format:check`, `test:unit`, `test:integration`,
  `test:e2e`, `build*`, `docker:*`) are confirmed present and are the source of truth for stage
  behavior.
- `docker-compose.development.yml` / `.test.yml` / `.prod.yml` are confirmed present and already
  encode per-environment deploy shape.
- `.husky/pre-commit` already runs `lint-staged` and `scripts/check-architecture.ts` locally —
  the CI lint stage should run the same architecture check server-side so a bypassed/missing
  local hook can't let a boundary violation merge.