Skip to content

plan.md

Latest commit

 

History

History
98 lines (69 loc) · 4.43 KB

plan.md

File metadata and controls

98 lines (69 loc) · 4.43 KB

Implementation Plan: P2P Payment Request

Branch: main | Date: 2026-04-09 | Spec: spec.md Input: Feature specification

Summary

Build a P2P payment request prototype allowing authenticated users to create, view, and act upon payment requests. The application uses a strict state machine for requests (PENDING -> PAID/DECLINED/EXPIRED/CANCELED), and targets Next.js 16 with Supabase for data and authentication.

Technical Context

Language/Version: TypeScript (Next.js 16 App Router)
Primary Dependencies: Tailwind CSS, shadcn/ui, Supabase Auth, Prisma Client
Storage: Supabase (PostgreSQL)
Testing: Playwright (E2E with video recording)
Target Platform: Vercel (Web / Mobile browser responsive) Project Type: Full-stack web application Performance Goals: N/A (Prototype)
Constraints: Money must be handled as integer cents. 2-3s delay for payment simulation.
Scale/Scope: 3 pre-seeded demo users (Alice, Bob, Charlie).

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

  • Spec as Source of Truth: Evaluated and passed. Spec contains all required flows.
  • AI-First, Human-Governed: Evaluated and passed.
  • Prefer Simplicity: Evaluated and passed. No extraneous architecture proposed.
  • Explicit Fintech Modeling: Enforced via Prisma schema (Int for cents, Enums for state).
  • Deterministic System Behavior: Enforced via API routes for simulation state changes.
  • E2E Testing: Addressed via Playwright integration.
  • Single Source of Data Truth: Enforced via shared database state for both requester/recipient views.
  • Separation of Concerns: Next.js App Router enforces Server Components (data) vs Client Components (UI interactivity).
  • Demo-First: Seed script will orchestrate Alice, Bob, Charlie with required dataset.

Project Structure & Architecture

Core Architecture & App Directory

The application will leverage the Next.js App Router for server-side rendering and API actions.

src/app/page.tsx

Splash page that redirects authenticated users to their dashboard.

src/app/(auth)/login/page.tsx

A simple login page connected to Supabase Auth. Allows logging in as the pre-seeded demo users (Alice, Bob, Charlie).

src/app/dashboard/page.tsx

The primary Request Management Dashboard, rendering standard tabs:

  • Outgoing: Lists requests sent by the current user.
  • Incoming: Lists requests received by the current user.

src/app/request/page.tsx

The Request Creation screen. Form with client-side validation (Zod) and server-side verification before inserting the PaymentRequest entity.

src/app/r/[shareToken]/page.tsx

The Request Detail View, publicly accessible but restricting actions (Pay/Decline/Cancel) via strict server-side checks.

Business Domain & State Machine

src/lib/domain/request-actions.ts

All business logic for state transitions (Cancel, Pay, Decline, Create).

  • Enforces the PENDING -> PAID, DECLINED, CANCELED terminal rules.
  • Contains the 2-3 second simulated delay for payment fulfillment.
  • Calculates expiration dynamically and immediately persists EXPIRED if discovered upon action attempt.

src/lib/domain/utils.ts & src/lib/domain/queries.ts

Domain-specific utility functions (amount parsing, contact validation, viewer-role resolving) and centralized database query parameters.

Database & ORM Layer

prisma/schema.prisma

The PaymentRequest and User model definitions. Uses Int for cents to prevent floating-point errors.

prisma/seed.ts

A script that syncs the 3 required Demo Users to Supabase Auth and generates a realistic matrix of requests to populate dashboards.

E2E Testing

tests/e2e/*.spec.ts

Playwright suites explicitly broken down by User Story to ensure isolated component logic verification with required video recording outputs to test-results/.

Verification Plan

Automated Tests

  • Explicitly run npx playwright test to verify all Acceptance Scenarios are satisfied.

Manual Verification

  1. Access the web app, login as "Alice".
  2. Create a request for "Bob".
  3. Log out, login as "Bob".
  4. Navigate to incoming requests and click "Pay".
  5. Verify the simulated delay and the state updates.
  6. Confirm constraints prevent paying expired or already-paid scenarios.

Complexity Tracking

No violations of project constitution detected. Simplicity is maintained.