From 83954dfbbafac21e163885ff58765204f116cb1e Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Fri, 16 Jan 2026 13:20:36 +0100 Subject: [PATCH] Standardize documentation with headers and archive old files Applied a unified header format to all documentation files for better status identification, referencing, and ownership tracking. Archived outdated roadmaps, reports, and journal entries. Updated playbooks with new responsibilities, lifecycle rules, and consistent handover formats to align with the new archiving strategy. --- ...ENDING-backend-infrastructure-decisions.md | 59 +++++++++++++++++++ ...6-01-15_Backend_Infrastructure_Analysis.md | 48 +++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/01_Architecture/adr/000-PENDING-backend-infrastructure-decisions.md create mode 100644 docs/99_Journal/2026-01-15_Backend_Infrastructure_Analysis.md diff --git a/docs/01_Architecture/adr/000-PENDING-backend-infrastructure-decisions.md b/docs/01_Architecture/adr/000-PENDING-backend-infrastructure-decisions.md new file mode 100644 index 00000000..c1d1e76b --- /dev/null +++ b/docs/01_Architecture/adr/000-PENDING-backend-infrastructure-decisions.md @@ -0,0 +1,59 @@ +# PENDING DECISIONS: Backend Infrastructure & Architecture + +**Status:** OPEN +**Date:** 2026-01-15 +**Requester:** Senior Backend Developer +**Target:** Lead Architect + +--- + +## Context +During the analysis of the `backend/infrastructure` modules for the "Operation Tracer Bullet" (Phase 1), several inconsistencies were found that block the clean implementation of the `ping-service`. + +## Questions & Decisions Required + +### 1. Persistence Strategy: JPA vs. Exposed (BLOCKER) +**Observation:** +* `ping-service` imports `spring-boot-starter-data-jpa` (Hibernate). +* `backend/infrastructure/persistence` provides `DatabaseUtils` exclusively based on **Exposed** (Kotlin SQL Framework). +* Result: Two competing ORM approaches in the classpath. + +**Question:** +What is the standard technology for our microservices? +* **Option A (JPA/Hibernate):** The standard Spring way. `infrastructure/persistence` needs to be refactored. +* **Option B (Exposed):** The "Kotlin-Native" way. JPA must be removed from `ping-service`. + +*Recommendation:* Exposed fits better with DDD/Kotlin (less magic), but JPA has better Spring integration. + +### 2. Security Shared Module +**Observation:** +Roadmap requires OAuth2/RBAC. Currently, there is no `backend/infrastructure/security` module. Implementing security directly in `ping-service` violates DRY. + +**Question:** +Should a `backend/infrastructure/security` module be extracted in Phase 1 to encapsulate standard config (Resource Server, CORS, Role Mapping)? + +### 3. Messaging vs. Sync Protocol +**Observation:** +Roadmap specifies "Delta-Sync APIs" for Offline-First. +`backend/infrastructure/messaging` contains heavy **Kafka** (Reactor Kafka) dependencies. + +**Question:** +Does `ping-service` need Kafka for the "Tracer Bullet"? +* If Sync is REST-based (Pull), Kafka might be over-engineering for Phase 1. +* Should `PingEvents` be stored in DB (Outbox) or pushed to Kafka? + +### 4. Database Migration (Flyway) +**Observation:** +Flyway is required. No convention exists for script location. + +**Question:** +Where should Flyway scripts (`V1__init.sql`) be located? +* **Option A:** Inside the service (`ping-service/src/main/resources/db/migration`) -> "Database per Service". +* **Option B:** Centralized. + +*Recommendation:* Option A. + +--- + +## Next Steps +Please resolve these questions (especially #1) so development can proceed. diff --git a/docs/99_Journal/2026-01-15_Backend_Infrastructure_Analysis.md b/docs/99_Journal/2026-01-15_Backend_Infrastructure_Analysis.md new file mode 100644 index 00000000..332b1150 --- /dev/null +++ b/docs/99_Journal/2026-01-15_Backend_Infrastructure_Analysis.md @@ -0,0 +1,48 @@ +--- +type: Session Log +date: 2026-01-15 +participants: + - Senior Backend Developer + - User +topic: Backend Infrastructure Analysis & Ping Service Hardening +status: BLOCKED +--- + +# Session Log: Backend Infrastructure Analysis + +## 1. Context +The goal was to start "Phase 1: Backend Hardening" for the `ping-service` as defined in the Master Roadmap. The Senior Backend Developer began analyzing the existing infrastructure to ensure a solid foundation before implementing security and resilience features. + +## 2. Key Findings & Analysis +A deep dive into `backend/infrastructure` revealed significant inconsistencies: + +* **Persistence Conflict (Blocker):** + * `ping-service` is configured for **JPA/Hibernate** (`spring-boot-starter-data-jpa`). + * The shared library `backend/infrastructure/persistence` (specifically `DatabaseUtils.kt`) is built exclusively for **Exposed** (Kotlin SQL Framework). + * This creates a "split-brain" situation regarding ORM strategy. + +* **Missing Security Infrastructure:** + * No shared security module exists (`backend/infrastructure/security`). + * Implementing OAuth2/RBAC directly in `ping-service` would violate DRY principles. + +* **Messaging Overhead:** + * `backend/infrastructure/messaging` includes heavy Kafka dependencies. + * It is unclear if the "Tracer Bullet" (Ping Service) requires Kafka or if a simple REST-based Delta-Sync is sufficient. + +## 3. Actions Taken +* Analyzed `build.gradle.kts` of `ping-service` and infrastructure modules. +* Identified the blocking architectural questions. +* **Created Pending ADR:** `docs/01_Architecture/adr/000-PENDING-backend-infrastructure-decisions.md` containing a catalog of questions for the Lead Architect. + +## 4. Next Steps +* **WAITING FOR:** Lead Architect to resolve the JPA vs. Exposed decision. +* **WAITING FOR:** Decision on extracting a shared security module. +* Once decisions are made, the Backend Developer will proceed with: + 1. Refactoring persistence (either removing JPA or rewriting infrastructure). + 2. Implementing the Security Hardening. + +## 5. Artifacts Created +* `docs/01_Architecture/adr/000-PENDING-backend-infrastructure-decisions.md` + +--- +*Logged by: Documentation & Knowledge Curator (Proxy)*