support_backend/specs/004-product-knowledge/plan.md

Implementation Plan: Product Knowledge Management & Retrieval

Branch: 004-product-knowledge | Date: 2026-09-02 | Spec: spec.md

Input: Feature specification from specs/004-product-knowledge/spec.md

Summary

Add the KnowledgeEntry/ErrorCode/KnownIssue/Runbook domain: admin CRUD with a draft/published/unpublished lifecycle and version-on-edit for knowledge entries and runbooks, structured lookup for error codes/known issues, and a filtered (non-semantic) retrieval query. This is the first feature to populate src/modules/ai-support/ — doc 07 places knowledge inside the ai-support module group, which doesn't exist in the codebase yet; this feature creates it with just the knowledge submodule, leaving the rest of that group (agents, sessions, diagnosis, tools, etc.) for the future AI-support feature (Phase 4).

Technical Context

Language/Version: TypeScript 5.4 / Node.js 20+.

Primary Dependencies: Prisma (new models), Zod. No new runtime dependency — retrieval is implemented as filtered Prisma queries (research.md), not a vector-search library.

Storage: PostgreSQL via Prisma (new KnowledgeEntry, ErrorCode, KnownIssue, Runbook models per docs/06-database-schema.md).

Testing: Vitest — unit tests for the version-on-edit logic and retrieval filter/ranking logic; integration tests for the full admin CRUD + retrieval flow against a real Postgres.

Target Platform: Same Fastify modular monolith. New module: src/modules/ai-support/knowledge/ (standard module shape per doc 07 — no existing scaffold to extend, unlike prior features).

Project Type: Backend service — single project.

Performance Goals: Not performance-sensitive at this phase (no semantic search, no LLM calls) — a retrieval query is a straightforward filtered/indexed Postgres query.

Constraints: MUST NOT return draft/unpublished/not-yet-effective entries from retrieval (FR-012); MUST preserve prior versions on edit, never overwrite in place (FR-004/FR-009); MUST scope retrieval to the requested product, never leak cross-product (FR-011).

Scale/Scope: Admin CRUD endpoints for all four entity types, one retrieval query endpoint. Explicitly excludes: semantic/vector retrieval, runbook execution, AI diagnosis, tool systems (all Phase 4) — see spec.md Assumptions.

Constitution Check

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

Principle / Section	Check	Result
I. SaaS Is the Sole Identity & Access Authority	Not directly implicated — knowledge is SupportHub-owned content, not SaaS identity data. owner/lastReview are free-text admin-set fields, not references into SaaS identity.	PASS — N/A
II. Configuration Over Hardcoding	Publish/validation lifecycle, versioning, and retrieval filters are all data-driven (status/effectiveDate/validationStatus columns), not hardcoded conditionals.	PASS
III. Layered Architecture With Enforced Module Boundaries	New ai-support/knowledge module follows the standard controller/service/repository/routes/schema/mapper/types/constants shape and exposes only its index.ts — same convention as every prior module in this codebase.	PASS
IV. AI Recommends, Deterministic Policy Decides	Not applicable — no AI reasoning in this feature; retrieval is deterministic filtering, not model inference.	PASS — N/A
V. Evidence-Based Verification	Not applicable — no resolution/verification concept in this feature.	PASS — N/A
VI. Durable Audit & History	Publish/unpublish and version-on-edit are themselves the durable history mechanism (FR-004/FR-009's "prior versions remain retrievable") — no separate audit log needed for this feature's own concern, though admin actions could optionally also write AuditLog rows (see research.md).	PASS
VII. Concurrency-Safe, Durable Job Handling	Version-on-edit uses the same optimistic-concurrency-adjacent pattern as 003-ticketing where two admins could race to edit the same entry — see research.md. No background jobs in this feature.	PASS
VIII. Problem and Ticket Are Separate, Related Entities	Not applicable — this feature doesn't touch tickets/problems.	PASS — N/A
Technology & Platform Constraints	Prisma + Zod only, no new dependency.	PASS

No violations requiring Complexity Tracking justification.

Post-Design Constitution Re-check

All gates above remain PASS after Phase 1 design. The version-history refinement (research.md) is worth calling out against Principle VI explicitly: it turns "prior versions remain retrievable" from an aspiration into a mechanical guarantee (a query, not a promise), which is exactly what durable audit/history is supposed to mean in this codebase.

Project Structure

Documentation (this feature)

specs/004-product-knowledge/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
└── tasks.md             # Phase 2 output (/speckit-tasks — not created here)

Source Code (repository root)

supporthub-api/
├── prisma/
│   └── schema.prisma                    # MODIFIED — add KnowledgeEntry, ErrorCode,
│                                           KnownIssue, Runbook models per docs/06
├── src/
│   └── modules/
│       └── ai-support/                   # NEW module group (doc 07) — only `knowledge`
│           └── knowledge/                  populated in this feature
│               ├── controller/
│               ├── routes/
│               ├── schema/
│               ├── repository/
│               ├── service/
│               ├── types/
│               ├── mapper/
│               ├── constants/
│               └── index.ts
└── tests/
    ├── unit/knowledge/                   # version-on-edit, retrieval filter/ranking logic
    └── integration/                      # admin CRUD + retrieval end to end

Structure Decision: Single project. New top-level module group ai-support/ is created for the first time (doc 07 places knowledge there), but only its knowledge submodule is built — agents/sessions/diagnosis/troubleshooting/tools/tool-execution/verification/escalation are left for the Phase 4 feature that actually needs them, matching this codebase's established pattern of building only what the current phase requires (e.g. identity/auth, orchestration/* remain untouched stubs from the original scaffold).

Complexity Tracking

No constitution violations — table intentionally omitted.