Review: Deposit Flow -- Stripe Checkout to Pool Balance

review-846-2026-04-05 Doc

review needs-refinement

Project

[x] Type -- Feature
[x] Lineage -- V2 ticket, depends on schema ticket, part of #66
[x] Repo -- forgejo_admin/twitch-2k-wager
[x] User Story -- player deposits funds into pool via Stripe Checkout
[x] Context -- explains V1 per-game payment vs V2 pool deposit model
[x] File Targets -- 3 NEW + 1 UPDATE, all with descriptions
[x] Acceptance Criteria -- 6 testable items
[x] Test Expectations -- 3 items
[x] Constraints -- 4 constraints including dependency, Stripe mode, metadata, backwards compat
[x] Checklist -- standard 3-item
[x] Related -- references #66 parent and schema dependency

[x] story:player-pool label -- present on board item #846
[ ] story note MISSING -- project-twitch-2k-wager page has no user-stories section (page TOC is empty). [SCOPE] Create user-stories section on project-twitch-2k-wager with player-pool story entry.
[x] arch:dataflow-twitch-2k-wager label -- present on board item #846
[ ] arch note MISSING -- search_notes("arch-dataflow-twitch-2k-wager") returned zero results. [SCOPE] Create architecture note arch-dataflow-twitch-2k-wager for the data flow component.
[x] Forgejo issue -- #68, open, well-formed

[x] src/routes/deposit/+page.svelte -- NEW: deposit directory does not exist yet (expected for new feature). Parent src/routes/ verified.
[x] src/routes/deposit/+page.server.ts -- NEW: same directory as above (expected).
[x] src/routes/api/deposit/+server.ts -- NEW: src/routes/api/ exists (contains admin, checkout, webhooks). New deposit subdirectory expected.
[x] src/routes/api/webhooks/stripe/+server.ts -- UPDATE: verified exists. Currently handles checkout.session.completed (game payments via game_id metadata) and account.updated. Deposit flow needs metadata type check to distinguish deposit from game -- ticket correctly calls this out.
[ ] src/lib/stripe.ts -- NOT LISTED but likely needs update. Existing createCheckoutSession is game-specific (takes game_id, tier, challenger details). Deposit flow will need either a new helper or modification. [BODY] Add as potential UPDATE target.

OK. Issue filed on twitch-2k-wager, all file targets are in twitch-2k-wager. Single-repo change. No cross-repo concerns.

BLOCKING: Issue #67 (v2 schema -- player_pools, proposals, peer-to-peer game model) is in backlog on board-twitch-2k-wager (board item #845). This ticket explicitly depends on the player_pools table. Verified: db.ts and types.ts have zero pool/balance/deposit references. Schema must land first.
Issue #66 (parent vision -- peer-to-peer proposal flow) is open. This ticket is a child of that vision. Not a blocker.
No other board items appear blocked by this ticket.

6 AC items -- all concrete and verifiable by an agent:

[x] /deposit page renders with amount input and current balance -- testable via navigation + DOM check
[x] Submitting creates Stripe Checkout session -- testable via API call verification
[x] Webhook adds funds to pool balance -- testable via DB state check after webhook
[x] Pool balance updates visible on page refresh -- testable via page reload + DOM check
[x] $1 min / $500 max enforced -- testable via boundary inputs
[x] Auth required -- testable via unauthenticated access attempt

All criteria are specific and programmatically verifiable. No ambiguous language.

Webhook handler update is the highest-risk change. Existing game payment flow must not break. Ticket correctly requires backwards compatibility via metadata type discriminator.
src/lib/stripe.ts createCheckoutSession is game-specific (takes game_id, tier, challenger metadata). Deposit flow will likely need a separate function or significant parameter changes. Not mentioned in file targets.
Rollback is straightforward: remove deposit route + revert webhook changes. No schema migration in this ticket (that is #67).

Apply the three-thing limit and five-minute rule:

4 file targets across 1 repo -- within limits
6 AC items -- borderline but tightly coupled to one deposit flow
All changes serve a single user journey (deposit funds into pool)
Frontend (deposit page) and backend (API + webhook) could theoretically be parallelized, but the tight coupling makes sequential execution simpler
Estimated agent time: ~5 minutes -- at the boundary but acceptable for a cohesive feature

No decomposition needed.

[SCOPE] Create user-stories section on project-twitch-2k-wager with player-pool story entry.
[SCOPE] Create architecture note arch-dataflow-twitch-2k-wager for the data flow component.
[BODY] Add src/lib/stripe.ts as a potential UPDATE target -- the deposit checkout session likely needs a new helper or modification to createCheckoutSession.
[BODY] Replace vague "schema ticket" dependency reference with explicit #67 issue number in Constraints and Related sections.

Verdict: NEEDS_REFINEMENT