ACC-63: PostgreSQL-Quellenarchitektur und Develop-Preview

[hernstev97]

Ergebnis

• legt PostgreSQL als einzige künftige Finanzquelle und Google Sheets als einmaliges Importformat fest
• trennt Google OAuth als reine Identitätsfunktion in einer eigenen ADR ab
• ersetzt ADR 0001 und ADR 0003, während ADR 0004 für den Single-User-Schnitt bestehen bleibt
• definiert interne owners.id, ownergebundene Schlüssel und den unveränderten Browservertrag FinanceDataV1
• hält Finanzlogik aus SQL heraus und verhindert einen dauerhaften Dual-Source-Betrieb

Develop- und Preview-Workflow

• Arbeitsbranches basieren künftig auf develop; Production bleibt auf master
• alle Vercel-Preview-Builds verwenden die anonyme, bereits authentifizierte Mock-API
• der Production-Build bleibt fail-closed auf der realen API und enthält keinen Mock-Chunk
• GitHub-CI läuft zusätzlich auf Pushes nach develop

Verifikation

• npm test: 237 Vitest-Tests und 11 Node-Tests erfolgreich
• npm run lint: erfolgreich
• npm run licenses:check: erfolgreich
• normaler npm run build: erfolgreich, kein Mock-Chunk
• simulierter Vercel-Preview-Build: erfolgreich, Mock-Chunk vorhanden
• Browser-Smoke gegen den gebauten Preview-Modus: erfolgreich
• npm run docs:check: ausschließlich die zwei bereits bestehenden Fehler wegen der fehlenden .env.example; keine neuen Doku-Fehler

Scope

ACC-63 enthält bewusst noch keine PostgreSQL-Migration, API-Umschaltung oder Editor-Implementierung. Diese folgen über ACC-71, ACC-29, ACC-66 und ACC-72.

Linear: https://linear.app/kiumu-app/issue/ACC-63/architektur-fur-den-quellenwechsel-festlegen-und-adr-0001-ersetzen

Greptile Summary

The PR establishes PostgreSQL as the future sole finance source, limits Google OAuth to identity after cutover, and clearly distinguishes that target architecture from the currently implemented Sheets flow.

• Adds ADRs 0013 and 0014 and updates the architecture, roadmap, schema, configuration, and ADR indexes consistently.
• Introduces a build-time finance runtime-mode resolver so Vercel Preview deployments use anonymous mock data while production remains on the real API.
• Extends CI pushes to develop and documents the develop-to-master release workflow.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking defects identified.

The preview mode is selected at build time, production remains on the real API path, and the architectural documentation consistently distinguishes the current implementation from the accepted target state.

Important Files Changed

Filename	Overview
build/financeRuntimeMode.ts	Centralizes build-time mock selection, enabling it only for exact Vercel preview builds and retaining the explicit local-development switch.
build/financeRuntimeMode.test.ts	Covers preview detection, local mock development, ordinary development, and rejection of the local override during non-preview builds.
vite.config.ts	Compiles the resolved runtime mode into the application alongside existing source-build metadata.
src/main.tsx	Replaces the development-only environment check with the compiled flag while preserving lazy loading of the mock implementation.
.github/workflows/ci.yml	Adds push-based CI coverage for the persistent develop integration branch.
docs/entscheidungen/0013-postgresql-als-finanzquelle.md	Defines PostgreSQL ownership, persistence boundaries, source cutover, and preservation of the FinanceDataV1 browser contract.
docs/entscheidungen/0014-google-oauth-nur-als-identitaet.md	Defines the post-cutover OAuth boundary and removal of persistent Google finance-access grants.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Vite build starts] --> B{VERCEL_ENV or VITE_VERCEL_ENV}
  B -->|preview| C[Compile mock flag as true]
  B -->|production or absent| D[Compile mock flag as false]
  C --> E[Load anonymous mock finance API]
  D --> F[Use production finance API]
  E --> G[Vercel Preview]
  F --> H[Production bundle without mock chunk]

Loading

_{Reviews (1): Last reviewed commit: "docs(architecture): define postgres sour..." | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
finance-overview	Ready	Preview	Aug 13, 2026 11:16pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 23de3218-da18-4b16-ae54-89209d938ba0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}