Inventory and Architecture Decisions #27

Type: Architecture / Research
Priority: High
Parent: PostgreSQL & Vault Migration
Dependencies: None

Objective

Establish an accurate understanding of the existing PayGuard infrastructure before making implementation changes.

Tasks

Repository Assessment

• Inspect all business services and shared modules.
• Review root and service-level Maven configurations.
• Identify Oracle JDBC, Flyway, ORM, and jOOQ dependencies.
• Inventory existing database configurations and SQL migrations.
• Review Docker, CI workflows, and infrastructure configuration.
• Identify the current database ownership model.
• Identify database secrets, HMAC peppers, provider credentials, and other sensitive configuration.
• Inspect repository instructions and existing ADRs.
• Record baseline build and test results.
• Determine whether existing databases contain data requiring migration.

Architecture Decisions

• Select PostgreSQL version and deployment topology.
• Select compatible, pinned Flyway, JDBC, and Testcontainers dependencies.
• Select supported self-hosted Vault version and verify licensing.
• Define database ownership and service isolation.
• Define runtime versus migration privileges.
• Design the application-to-Vault authentication approach.
• Define database credential lifecycle and connection-pool expectations.
• Decide on cutover and rollback strategy.

ADRs

• PostgreSQL adoption and service database ownership.
• Oracle-to-PostgreSQL migration and cutover.
• HashiCorp Vault secrets-management strategy.
• Dynamic database credential lifecycle.
• PostgreSQL concurrency strategy, if required.

Acceptance Criteria

• A complete service/database inventory is available.
• Every Oracle dependency and configuration is identified.
• The selected technology versions are compatible with the actual build.
• ADRs document alternatives, trade-offs, failure behavior, and verification.
• Existing-data risks and environmental blockers are documented.

Definition of Done

All architecture decisions are documented and reviewed before implementation begins.