Phase 6: Document PostgreSQL migration, Vault integration, and operational procedures

Type: Documentation / Architecture
Priority: High
Parent: PostgreSQL & Vault Migration
Depends on: Implemented outcomes and evidence from Phases 1–5

Objective

Create comprehensive, reproducible documentation covering the actual PostgreSQL migration and HashiCorp Vault implementation.

Tasks

Architecture Documentation

• Update the PayGuard README.
• Update relevant architecture documents.
• Link all PostgreSQL and Vault ADRs.
• Document service/database ownership.
• Document the final PostgreSQL topology.
• Document runtime and migration role privileges.
• Document Vault authentication and access policies.
• Document the application secrets lifecycle.

Implementation Guide

Create:

`docs/guides/postgresql-vault-migration.md`

Include:

• Initial Oracle infrastructure and inspected repository state.
• Architecture decisions and technology versions.
• Service-by-service change ledger.
• PostgreSQL schema and type mappings.
• Flyway migration structure and historical compatibility.
• Docker and local infrastructure configuration.
• Vault bootstrap and authentication flow.
• Dynamic database credential lifecycle.
• Connection-pool renewal/replacement behavior.
• HMAC pepper storage and rotation strategy.
• Data migration, reconciliation, and rollback procedures.
• Database and Vault failure recovery.
• Exact installation, startup, and verification commands.
• Actual test results and environmental limitations.
• Remaining Oracle references and explanations.
• Security considerations and known limitations.

Final Handover

• Verify documentation against the final code.
• Record unresolved work as separate GitHub Issue drafts.
• Document which features are implemented versus planned.
• Link relevant pull requests and commits.
• Provide a final migration verification summary.
• Confirm all required Sub-issues satisfy their Definition of Done.

Acceptance Criteria

• Another engineer can reproduce the documented local environment.
• Architecture documentation matches actual implementation.
• Every security and correctness claim has corresponding evidence.
• Operational recovery and credential lifecycle procedures are clear.
• Outstanding production-dependent work is explicitly identified.

Definition of Done

Documentation is complete, reviewed, reproducible, and aligned with the implementation.