process-documentation-suite-1

Introduction

Create user-facing documentation aligned to the approved spec and current implementation: a tutorial for local runs, a how-to for API key rotation, and an explanation of reachability rationale. Follow the four-part documentation framework (Tutorials, How-to Guides, Reference, Explanations).

0. Existing Project Analysis

Architecture Patterns Detected:

• Go 1.25 service; Huma v2 for OpenAPI/UI; net/http middleware; Prometheus metrics
• Read-only informer-driven projection; static bearer auth via Secret or file
• K8s manifests under deploy/manifests; Dockerfile under build/

Technology Stack (Current):

• Matches spec: Go + Huma v2 + client-go + Prometheus

Implementation Constraints:

• Single business endpoint GET /v1/ingresses with ETag/304
• Auth required for /v1/*; no mutation endpoints
• Docs must reflect top-level hosts[] response (ADR-0001)

1. Spec Alignment & Traceability Summary

• Source Spec: Ingress Info Service v1.0.0 (status: Approved, updated: 2025-09-15)
• Scope Mapping: DOC-001, DOC-002, DOC-004; supports FR-001, FR-004, FR-007; AC-001, AC-005, AC-008; OPS-002; DECISION-002

2. Requirements & Constraints

• From Spec:
• DOC-001: Tutorial for local run
• DOC-002: How-to guide for key rotation (OPS-002, SEC-002)
• DOC-004: Explanation for passive reachability (DECISION-002)
• Related FR/NFR/AC:
  • FR-001, AC-001; FR-004, AC-005; FR-007, AC-008; OPS-002; DECISION-002
• Constraints:
  • CON-001: Keep examples aligned to current API schema (HostsList)
  • GUD-001: Use concise, copyable commands with bash
  • PAT-001: Follow the four-part documentation structure

3. Implementation Steps

Implementation Phase 1

• GOAL-001: Deliver end-to-end tutorial for local run using a KUBECONFIG file

Implementation Phase 2

• GOAL-002: Provide key rotation how-to

Implementation Phase 3

• GOAL-003: Explain reachability rationale and limitations

4. Alternatives

• ALT-001: Embed docs inline in README only (rejected; less discoverable; conflicts with the four-part documentation structure)
• ALT-002: Generate docs from OpenAPI only (rejected for tutorial/how-to; acceptable for API reference already covered)

5. Dependencies

Existing Dependencies (Already Available):

• DEP-004 Prometheus client_golang (referenced in metrics examples)

New Dependencies (To Be Added):

• None

6. Files

Files to Modify:

• README.md (add links to new docs)

Files to Create:

• docs/tutorials/local-run.md
• docs/how-to/rotate-keys.md
• docs/explanations/reachability.md

7. Testing

Existing Test Patterns to Follow:

• N/A for prose; validate via quick start commands and curl examples

Test Tasks:

• TEST-110: Ensure tutorial curl against /v1/ingresses returns 401 without auth and 200 with a valid key (manual verification steps listed)
• TEST-120: Verify key rotation steps result in new key accepted within refresh interval (manual)

8. Documentation

• DOC-001: Tutorial (docs/tutorials/local-run.md)
• DOC-002: How-to (docs/how-to/rotate-keys.md)
• DOC-004: Explanation (docs/explanations/reachability.md)

9. Risks & Assumptions

• RISK-101: Instructions drift if env var defaults change — Mitigate by referencing spec and config file keys explicitly
• RISK-102: Cluster differences affect rotation steps — Provide generic K8s manifests examples
• ASM-101: Users have kubectl and access to create/update Secrets in target namespace

10. Related Specifications / Further Reading

• docs/specification.md (DOC-001, DOC-002, DOC-004; FR-001, FR-004, FR-007; DECISION-002)
• internal/auth/keys.go (file override and refresh)
• internal/reachability/* (passive classification)

11. Compliance & Change Control

• Deviations from Spec require ADRs
• Any change to auth or reachability behaviour requires spec update and acceptance

Traceability Index

Next Steps

• After completing this plan, link from README and optionally publish docs via your chosen site generator.