Skip to content

Commit bfb85fe

Browse files
AliEmre007AliEmre007
committed
feat: add PayLedger customer and operations UI
1 parent be21893 commit bfb85fe

19 files changed

Lines changed: 4527 additions & 0 deletions

‎docs/frontend-runbook.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# PayLedger Frontend Runbook
2+
3+
## Purpose
4+
5+
The frontend is a TypeScript single-page application that exercises the secured
6+
PayLedger API. It does not calculate balances, mutate financial state locally,
7+
or replace backend authorization and business rules.
8+
9+
## Local Prerequisites
10+
11+
- Node.js 22 or newer.
12+
- Backend API running on `http://localhost:18080`.
13+
- Local Keycloak running on `http://localhost:18081`.
14+
- Local realm `payledger-local` imported from
15+
`infra/compose/keycloak/import/payledger-local-realm.json`.
16+
17+
Start local infrastructure from the repository root:
18+
19+
```bash
20+
docker compose -f infra/compose/compose.yaml up -d
21+
```
22+
23+
Start the backend:
24+
25+
```bash
26+
cd backend
27+
./mvnw spring-boot:run
28+
```
29+
30+
Start the frontend:
31+
32+
```bash
33+
cd frontend
34+
npm install
35+
npm run dev
36+
```
37+
38+
Open:
39+
40+
```text
41+
http://localhost:5173
42+
```
43+
44+
The Vite development server proxies `/api`, `/actuator`, and `/api-docs` to the
45+
backend, so browser calls use same-origin API paths during local development.
46+
47+
## Authentication
48+
49+
The browser uses Keycloak Authorization Code Flow with PKCE through client:
50+
51+
```text
52+
payledger-frontend
53+
```
54+
55+
The browser client is public, uses `S256` PKCE, and has direct password grants
56+
disabled. The existing `payledger-dev-cli` client remains development-only for
57+
terminal workflows and is not used by browser code.
58+
59+
Default local user:
60+
61+
```text
62+
username: alice
63+
password: alice-dev-password
64+
realm role: CUSTOMER
65+
```
66+
67+
Operations screens are visible only when the access token contains
68+
`OPERATIONS` or `ADMIN` in `realm_access.roles`.
69+
70+
## Customer Workflows
71+
72+
The customer workspace supports:
73+
74+
- login and logout;
75+
- wallet balance lookup by wallet ID;
76+
- paginated statement lookup for the selected wallet;
77+
- wallet-to-wallet transfer with a stable idempotency key for the current
78+
transfer draft;
79+
- payment authorization by wallet and merchant ID;
80+
- cancellation of the most recently authorized payment shown in the UI.
81+
82+
The backend remains the source of truth. Balances displayed after commands are
83+
fetched from API responses and follow ledger/hold semantics.
84+
85+
## Operations Workflows
86+
87+
The operations workspace supports:
88+
89+
- customer KYC submit/approve/reject;
90+
- wallet freeze/unfreeze/close;
91+
- merchant onboarding and activation;
92+
- payment capture/refund;
93+
- settlement batch creation;
94+
- settlement reconciliation;
95+
- paginated reads for audit events, customers, wallets, payment intents, and
96+
reconciliation cases.
97+
98+
All operations mutations require a reason and rely on backend role checks. The
99+
frontend hides operations screens for customer-only tokens, but the API remains
100+
the enforcement point.
101+
102+
## Configuration
103+
104+
Optional Vite environment variables:
105+
106+
```text
107+
VITE_API_BASE_URL=
108+
VITE_KEYCLOAK_URL=http://localhost:18081
109+
VITE_KEYCLOAK_REALM=payledger-local
110+
VITE_KEYCLOAK_CLIENT_ID=payledger-frontend
111+
```
112+
113+
For local development, `VITE_API_BASE_URL` should usually stay empty so the
114+
Vite proxy handles backend calls.
115+
116+
## Verification
117+
118+
Run frontend checks:
119+
120+
```bash
121+
cd frontend
122+
npm run build
123+
npm test
124+
```
125+
126+
Run backend checks before completing the sprint:
127+
128+
```bash
129+
cd backend
130+
./mvnw test
131+
```
132+
133+
Then from the repository root:
134+
135+
```bash
136+
git diff --check
137+
git status --short
138+
```

‎frontend/index.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>PayLedger</title>
7+
</head>
8+
<body>
9+
<div id="app"></div>
10+
<script type="module" src="/src/main.ts"></script>
11+
</body>
12+
</html>

0 commit comments

Comments
 (0)