docs: add repo review and next production-safe implementation phase #27
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,58 @@ | ||||||
| # zWallet Production-Safe Next Phase Plan (Repository Review) | ||||||
|
|
||||||
| Date: 2026-05-14 | ||||||
|
|
||||||
| ## Scope Reviewed | ||||||
| - Monorepo structure under `apps/*`, `packages/*`, and `docs/*`. | ||||||
| - Runtime/build orchestration (`package.json`, `pnpm-workspace.yaml`, `turbo.json`). | ||||||
| - Backend API module coverage for wallet-adjacent surfaces. | ||||||
|
|
||||||
| ## Key Findings | ||||||
| 1. **Repository/package mismatch vs. current runbook assumptions** | ||||||
| - The workspace contains `apps/backend`, `apps/frontend-miniapp`, `packages/contracts`, `packages/game-unity`. | ||||||
| - Packages referenced in the runbook (`@zwallet/shared-types`, `@zwallet/wallet-engine`, `@zwallet/admin-wallet`) do **not** exist in this repository. | ||||||
|
|
||||||
| 2. **Current backend already exposes partial wallet-adjacent functionality** | ||||||
| - Auth wallet connect flow exists (`/auth/wallet/connect`). | ||||||
| - Bridge, DeFi, FinTech, Enterprise, Rewards, and related modules are present. | ||||||
| - Documentation claims wallet create/get/balance endpoints, but no dedicated wallet module file set is present in `apps/backend/src/modules`. | ||||||
|
|
||||||
| 3. **Phase artifacts and docs are broad, but execution guardrails are inconsistent** | ||||||
| - Top-level scripts encourage recursive workflows (`turbo run build/test/lint`) that conflict with your current production-safe constraints. | ||||||
|
|
||||||
| ## Next Incremental Phase to Implement (Single PR) | ||||||
|
|
||||||
| ## Phase N+1: Minimal Wallet Module Hardening (Backend-only) | ||||||
|
|
||||||
| Implement a **small, isolated backend slice** that closes the gap between documented and actual wallet API behavior while avoiding infra/runtime churn: | ||||||
|
|
||||||
| 1. Add `wallet` module to `apps/backend/src/modules/wallet/` with: | ||||||
| - `POST /api/wallet/create` | ||||||
| - `GET /api/wallet/:userId` | ||||||
| - `GET /api/wallet/:userId/balance` | ||||||
| 2. Back endpoints with existing Prisma `User.walletAddress` and a conservative placeholder balance provider (no chain writes). | ||||||
|
Comment on lines
+32
to
+33
There was a problem hiding this comment. Implementing a balance endpoint with a placeholder while the authoritative source is still listed as a blocker (Line 54) introduces a risk of shipping misleading data. For a production-safe plan, the source of truth (on-chain vs. internal ledger) should be defined before exposing this API to avoid technical debt and potential consistency issues. |
||||||
| 3. Add DTO validation and strict response typing. | ||||||
| 4. Register module in `app.module.ts`. | ||||||
| 5. Add focused unit tests only for new wallet service/controller behavior. | ||||||
|
|
||||||
| ### Why this is the correct next step | ||||||
| - Directly aligns with currently documented API surface and closes production confusion. | ||||||
| - Keeps blast radius limited to backend application code. | ||||||
| - Avoids Cloudflare/Terraform/Docker changes. | ||||||
| - Supports iterative rollout behind existing service runtime (`tsx`). | ||||||
|
|
||||||
| ## Validation Plan for That Next PR | ||||||
| Use package-scoped commands only (no recursive monorepo build/lint/typecheck): | ||||||
|
|
||||||
| - `pnpm --filter ./apps/backend test -- wallet` | ||||||
| - `pnpm --filter ./apps/backend build` | ||||||
| - `pnpm --filter ./apps/backend exec tsx src/main.ts` (smoke run) | ||||||
|
There was a problem hiding this comment. For a production-safe validation plan, it is preferable to smoke-test the compiled build artifact rather than using tsx on source files. This ensures that the build process itself is successful and that the resulting bundle behaves as expected in an environment closer to production.
Suggested change
|
||||||
|
|
||||||
| ## Remaining Blockers (Before/While Implementing) | ||||||
| 1. Runbook-to-repo naming drift (`@zwallet/*` package names absent) must be acknowledged in execution notes. | ||||||
| 2. No explicit dedicated wallet persistence model beyond `User.walletAddress`; confirm whether multi-wallet per user is needed before schema expansion. | ||||||
| 3. Clarify authoritative source for wallet balance (on-chain indexer vs. internal ledger) to avoid shipping misleading “real balance” semantics. | ||||||
|
|
||||||
| ## Rollback Notes (for upcoming implementation PR) | ||||||
| - Revert only new `wallet` module files and `app.module.ts` import wiring. | ||||||
| - No DB migration in this phase, so rollback is code-only and low risk. | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The POST /api/wallet/create endpoint is proposed while the multi-wallet persistence model is still a blocker (Line 53). Since the current Prisma schema enforces a unique walletAddress per User, the purpose of a 'create' endpoint is unclear. Defining the wallet cardinality should precede the API definition to prevent immediate architectural misalignment.