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

# Implementation Plan: Continuous Integration Pipeline

**Branch**: `001-ci-pipeline` | **Date**: 2026-08-21 | **Spec**: [spec.md](./spec.md)

**Input**: Feature specification from `specs/001-ci-pipeline/spec.md`

## Summary

Add an automated CI/CD pipeline (Jenkins, per the constitution's Technology & Platform
Constraints and `docs/09-testing-observability-cicd.md` §3) that runs on every proposed change:
checkout → install → environment validation → typecheck → lint → format check → unit test →
integration test → E2E test → build → Docker build → publish → deploy. It wires together
quality gates and npm scripts that already exist in the repo — it does not introduce new checks,
only automates and sequences the ones already defined in `package.json`.

## Technical Context

**Language/Version**: Groovy (Jenkins declarative pipeline) driving Node.js 20 (per `engines` in
`package.json`) / TypeScript 5.4 build steps.

**Primary Dependencies**: Jenkins (declarative pipeline, `Jenkinsfile` at repo root), Docker /
Docker Compose (already present as `docker-compose.development.yml`, `docker-compose.test.yml`,
`docker-compose.prod.yml`), the existing npm scripts (`typecheck`, `lint`, `format:check`,
`test:unit`, `test:integration`, `test:e2e`, `build`), Prisma CLI (`prisma:generate`,
`prisma:deploy`) for schema/client generation before build.

**Storage**: N/A for the pipeline itself — it depends on ephemeral PostgreSQL/Redis instances
(brought up via `docker-compose.test.yml`) to run integration/E2E tests against.

**Testing**: Vitest (`test:unit`, `test:integration`, `test:e2e`) — already configured; the
pipeline invokes these, it does not define new test tooling.

**Target Platform**: Linux CI agent (Jenkins), producing a Linux container image; deploy targets
are the `development`, `test`, and `prod` environments already defined via
`docker-compose.*.yml` + `.env.*` files.

**Project Type**: Backend service (single Fastify modular monolith) — this feature only adds
CI/CD tooling around the existing `supporthub-api` project; no new application code paths.

**Performance Goals**: N/A (process/tooling feature, not a runtime performance concern). Informal
target: full validate→build pipeline completes in a time that keeps PR feedback fast (not
formally measured by this feature).

**Constraints**: MUST NOT read production secrets from the repository (constitution Principle
governance + FR-008); MUST fail fast on missing/invalid environment configuration before running
expensive test stages; MUST isolate concurrent runs (FR-009) — Jenkins agent workspace-per-build
satisfies this natively.

**Scale/Scope**: One `Jenkinsfile` at repo root for `supporthub-api`. Out of scope: the sibling
`supporthub-web` frontend pipeline (separate repo/feature if/when needed), flaky-test
retry/quarantine policy (explicitly deferred in spec.md Edge Cases).

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle / Section | Check | Result |
|---|---|---|
| III. Layered Architecture With Enforced Module Boundaries | This feature adds no application code — no controllers/services/repositories touched. | PASS — N/A |
| VI. Durable Audit & History | Not directly applicable to CI itself; pipeline run history is retained by Jenkins (build history), satisfying FR-010's "visible without server/log access" via the Jenkins UI. | PASS |
| VII. Concurrency-Safe, Durable Job Handling | Not applicable — no SLA timers or job handlers introduced. | PASS — N/A |
| Technology & Platform Constraints | Constitution names Jenkins explicitly for CI/CD; this plan uses Jenkins declarative pipeline, not an alternative CI tool. | PASS |
| Testing, Observability & CI/CD Gates | Constitution requires exactly this stage order: checkout → install → env validation → typecheck → lint → format check → unit → integration → E2E → build → Docker build → publish → deploy. Plan matches verbatim. | PASS |
| Governance ("secrets never committed") | Plan requires Jenkins-managed credentials store for all env/prod secrets. Verified in Phase 0 (research.md): `.env.*` files were found committed with real dev credentials, fixed out-of-band (commit `2093898` — untracked, `.env.example` added); pipeline generates `.env.<target>` from Jenkins credentials at runtime, never reads the repo copy. | PASS (post-design) |

No violations requiring Complexity Tracking justification.

## Post-Design Constitution Re-check

All gates above remain PASS after Phase 1 design (data-model.md, contracts/, quickstart.md). No
new violations introduced — this feature adds zero application code, only pipeline
configuration, so Principles I, II, IV, V, VIII (identity boundary, config-over-hardcode, AI
policy, evidence-based verification, ticket/problem separation) are not applicable and were
correctly excluded from the gate table above.

## Project Structure

### Documentation (this feature)

```text
specs/001-ci-pipeline/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md         # Phase 1 output (minimal — see note)
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output (pipeline stage contract)
└── tasks.md             # Phase 2 output (/speckit-tasks — not created here)
```

### Source Code (repository root)

```text
supporthub-api/
├── Jenkinsfile                       # NEW — declarative pipeline, stages per Constitution
├── package.json                      # EXISTING — source of truth for script names each stage calls
├── docker-compose.development.yml    # EXISTING — used for local/dev parity, not directly by CI
├── docker-compose.test.yml           # EXISTING — brings up ephemeral Postgres/Redis for CI test stages
├── docker-compose.prod.yml           # EXISTING — referenced by the deploy stage for prod rollout
├── .env.development / .env.test / .env.prod   # EXISTING — env files; secrets injected by Jenkins
│                                                 credentials at pipeline runtime, not read from repo
└── scripts/
    └── check-architecture.ts         # EXISTING — architecture boundary check; candidate addition to
                                         the lint/typecheck stage (confirmed in research.md)
```

**Structure Decision**: Single project (this is the existing `supporthub-api` backend). No new
application source directories are introduced — the only new artifact is a root-level
`Jenkinsfile` plus its supporting CI documentation under `specs/001-ci-pipeline/`. The sibling
`supporthub-web` repository is explicitly out of scope (see Technical Context → Scale/Scope).

## Complexity Tracking

*No constitution violations — table intentionally omitted.*