nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: sync from backend 10de752 — defer legacy mongo imports

Browse Source
This commit is contained in:
Siavash Sameni
2026-06-02 10:30:06 +04:00
parent 1a59dacf87
commit c90f286b12
2 changed files with 19 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
02 - Data Models/Postgres Runtime Cutover Status.md
View File

@@ -3,14 +3,14 @@ title: Postgres Runtime Cutover Status
tags: [data-model, postgres, migration, runtime-status]
aliases: [Postgres Status, PG Cutover Status, Mongo vs Postgres Runtime]
created: 2026-05-31
source: backend integrate-main-into-development@134d155 + frontend integrate-main-into-development@18af5dd + deployment main@38cb75b
source: backend integrate-main-into-development@10de752 + frontend integrate-main-into-development@3dfbac2 + deployment main@38cb75b
---
# Postgres Runtime Cutover Status
> **Current branch:** backend `integrate-main-into-development` at `134d155`, version `2.8.32`; frontend `integrate-main-into-development` at `18af5dd`, version `2.8.32`; dev deployment `main` at `38cb75b`.
> **Current branch:** backend `integrate-main-into-development` at `10de752`, version `2.8.33`; frontend `integrate-main-into-development` at `3dfbac2`, version `2.8.33`; dev deployment `main` at `38cb75b`.
>
> **Bottom line:** this branch is **Postgres-capable**, not fully Postgres-backed. Dev deployment now defaults the seven existing PG-capable runtime stores to Postgres: auth-owned users/Telegram auth, confirmation-threshold config/history, user addresses, categories, level config, shop settings, and reviews. Code-level defaults remain Mongo outside that deployment override, and Mongo remains the compatibility store for still-Mongo domains. The category PG path enforces one active visible category per normalized name. As of backend `2.8.32`, the config, shop-settings, and review facades lazy-load Mongo fallback/backfill models instead of importing them at module load. All PG-backed stores require `PG_URL`.
> **Bottom line:** this branch is **Postgres-capable**, not fully Postgres-backed. Dev deployment now defaults the seven existing PG-capable runtime stores to Postgres: auth-owned users/Telegram auth, confirmation-threshold config/history, user addresses, categories, level config, shop settings, and reviews. Code-level defaults remain Mongo outside that deployment override, and Mongo remains the compatibility store for still-Mongo domains. The category PG path enforces one active visible category per normalized name. As of backend `2.8.33`, the active startup/health/admin/report import surface no longer has non-type top-level `mongoose` or `models/*` imports; legacy Mongo models are lazy-loaded only when fallback/backfill/maintenance actions run. All PG-backed stores require `PG_URL`.
## What Uses Postgres Now
@@ -18,7 +18,7 @@ source: backend integrate-main-into-development@134d155 + frontend integrate-mai
|---|---|---|
| Postgres connection | Available when `PG_URL` is set | Current store facades use `src/infrastructure/postgres/client.ts`; the broader `src/db/` Drizzle layer and repository factory exist, but most live services are not wired through that factory yet. |
| Runtime schema bootstrap | Implemented for auth, config, address, and reference stores | Auth tables are bootstrapped from `src/services/auth/postgresAuthSchema.ts`; store facades bootstrap their own tables at startup when their `*_STORE=postgres` flag is enabled. |
| Health observability | Implemented in `/api/health` | `checks.postgres` reports `configured`, `required`, `storeModes`, `enabledStores`, and `enabledStoreCount`, so Gatus/operators can verify both PG reachability and which runtime stores are actively PG-backed. Dev Gatus now asserts all seven PG-capable store modes are `postgres`. |
| Health observability | Implemented in `/api/health` | `checks.postgres` reports `configured`, `required`, `storeModes`, `enabledStores`, and `enabledStoreCount`, so Gatus/operators can verify both PG reachability and which runtime stores are actively PG-backed. Dev Gatus now asserts all seven PG-capable store modes are `postgres`. Backend `2.8.33` lazy-loads Mongoose for the legacy Mongo health check and skips it when Mongo is optional under `MONGO_CONNECT_MODE=auto/never`. |
| Auth-owned user store | PG-backed in dev deployment; code opt-in with `AUTH_STORE=postgres` | Auth, passkey, Telegram auth/link/session/temp-verification, and `/api/user` profile paths use an auth-store facade. In PG mode, users are stored in Postgres and mirrored back to Mongo through `legacy_object_id` for compatibility with still-Mongo services. |
| Confirmation-threshold runtime config | PG-backed in dev deployment; code opt-in with `CONFIG_STORE=postgres` | `ConfigSetting` / `ConfigSettingHistory` access for `/api/admin/settings/confirmation-thresholds` and transaction-safety confirmation thresholds uses a config-store facade. PG-mode writes mirror back to Mongo for rollback. Backend `2.8.32` removed top-level Mongo model imports from this facade; legacy models load only for Mongo fallback/backfill/mirror paths. |
| User addresses | PG-backed in dev deployment; code opt-in with `ADDRESS_STORE=postgres` | `/api/addresses` CRUD uses an address-store facade. PG mode enforces one primary address per user with a partial unique index and mirrors writes/deletes back to Mongo for rollback. |
@@ -32,14 +32,14 @@ source: backend integrate-main-into-development@134d155 + frontend integrate-mai
## What Is Still Mongo-Backed
Most of the service layer still imports Mongoose models directly. Auth-owned paths now have an auth-store boundary; confirmation-threshold config, user addresses, categories, level config, shop settings, and reviews have store boundaries, and their PG-capable facades lazy-load legacy Mongo fallbacks instead of top-loading them. Funds ledger appends/balance reads now use the payment repository seam, but default to Mongo unless `REPO_PAYMENT` is flipped. Broad marketplace requests/offers/templates, most payment paths, points transactions, chat, notification, and admin paths remain Mongo-first.
Active app startup, health, and the PG-capable store facades no longer top-load Mongoose models. Auth-owned paths now have an auth-store boundary; confirmation-threshold config, user addresses, categories, level config, shop settings, and reviews have store boundaries, and their PG-capable facades lazy-load legacy Mongo fallbacks instead of top-loading them. Funds ledger appends/balance reads now use the payment repository seam, but default to Mongo unless `REPO_PAYMENT` is flipped. Broad marketplace requests/offers/templates, most payment paths, points transactions, chat, notification, and admin maintenance actions remain Mongo-first when exercised.
| Domain | Current live store | Why not Postgres yet |
|---|---|---|
| Legacy/broad user consumers | MongoDB mirror | Auth-owned users can be PG-backed, but still-Mongo domains expect Mongo ObjectId user references. PG-mode writes therefore maintain a Mongo mirror until those domains are cut over. |
| Admin cleanup / seed address tooling | MongoDB | User-facing address CRUD is PG-capable, but admin cleanup and seed scripts still operate on Mongo first. Seed scripts backfill addresses to PG when `ADDRESS_STORE=postgres`. |
| Admin cleanup / seed address tooling | MongoDB | User-facing address CRUD is PG-capable, but admin cleanup and seed scripts still operate on Mongo first. Backend `2.8.33` makes admin cleanup lazy-load its Mongo models only when cleanup/stat/user-data maintenance actions run. Seed scripts backfill addresses to PG when `ADDRESS_STORE=postgres`. |
| Marketplace requests/offers/templates | MongoDB | Marketplace, checkout, and seller-offer services still call `PurchaseRequest`, `SellerOffer`, and `RequestTemplate` directly. Category and shop-settings reads/writes are PG-capable through facades. PurchaseRequest/SellerOffer/RequestTemplate backfill tooling is now operator-ready, but runtime reads/writes remain Mongo-first and RequestTemplate still has no runtime repo/service wiring. |
| Payments and escrow state | MongoDB primary | Request Network, AMN scanner, webhook, admin, release/refund, adapter, reconciliation, and legacy payment paths still create/update `Payment` Mongoose documents directly. Payment repository methods exist but are not broadly wired into runtime services yet. |
| Payments and escrow state | MongoDB primary | Request Network, AMN scanner, webhook, admin, release/refund, adapter, reconciliation, and legacy payment paths still create/update `Payment` Mongoose documents directly. Payment repository methods exist but are not broadly wired into runtime services yet. The SHKeeper migration report lazy-loads `Payment` and `FundsLedgerEntry` as of backend `2.8.33`, but the report remains Mongo-backed. |
| Funds ledger | Repository-backed, default Mongo | `appendFundsLedgerEntry` and `getFundsBalanceBy*` now call `getPaymentRepo()`. In default mode that is `MongoPaymentRepo`; `REPO_PAYMENT=dual`/`pg` can exercise the PG ledger implementation after backfill/soak. Drizzle balance reads support both UUID refs and external/string refs used by template checkout. |
| Derived destinations and sweeps | MongoDB | Wallet destination allocation and sweep services call `DerivedDestination` directly. |
| Points/referrals/transactions | MongoDB | Level configuration is PG-capable, but `User` points fields, `PointTransaction`, referral aggregation, and Mongo transactions remain Mongo-backed. |

12
09 - Audits/Activity Log.md
View File

@@ -11,6 +11,18 @@ entries on top. Maintained by agents per the rule in `../AGENTS.md`.
---
### 2026-06-02 — backend@10de752, frontend@3dfbac2 — defer legacy Mongo runtime imports
**Commits:** backend `10de752` (version `2.8.33`), frontend `3dfbac2` (version `2.8.33`)
**Touched:**
- Backend: `src/infrastructure/database/connection.ts`, `src/services/health/healthCheckService.ts`, `src/services/admin/dataCleanupService.ts`, `src/services/payment/migration/reportService.ts`, `package.json`, `package-lock.json`
- Frontend: `package.json` version metadata only.
**Why:** Continue removing MongoDB as a runtime dependency by deferring the remaining active startup/health/admin/report Mongoose/model loads. Legacy Mongo connection, health ping, admin cleanup, and SHKeeper migration report paths still work, but now load Mongoose/models only when those legacy actions actually run.
**Verification:** Backend `npm run typecheck`; backend `npm test -- --runTestsByPath __tests__/health-check-service.test.ts --runInBand`; backend `npm test -- --runTestsByPath __tests__/payment-migration.service.test.ts --runInBand`; backend static scan for non-type top-level `mongoose`/`models/*` imports in active app/routes/services/infrastructure returned no matches; backend/frontend `git diff --check`; `BASE_URL=https://dev.amn.gg bash scripts/smoke/backend-health.sh` passed against dev before push.
**Linked docs updated:** [[Postgres Runtime Cutover Status]]
---
### 2026-06-02 — backend@134d155, frontend@18af5dd — lazy-load PG-capable store Mongo fallbacks
**Commits:** backend `134d155` (version `2.8.32`), frontend `18af5dd` (version `2.8.32`)