Claude Project Tracker

Physical rollout for Phase 1 pilot.\n\n- Confirm which station is the pilot (default VAJRA0001)\n- Send print design (#56) to signage vendor (#Q17 answer: existing vendor)\n- Receive 2 laminated A5 stickers (Gun 1 + Gun 2)\n- Physically apply to gun/panel\n- Coordinate with ops staff to be on-site during pilot testing window\n- Document station-owner communications (landlord awareness of pilot)\n\nBlocked on #56 (design finalized) + Razorpay QR issued (#52 + #61).</body>

added 08-02 11:53 · by saravanan@scrumclaw.ai · claude-cowork

Pre-launch gate for Phase 1. Test matrix:\n\n- App: BHIM, Google Pay, PhonePe, Paytm, WhatsApp Pay (5 apps)\n- Amount: ₹100, ₹500, ₹1000 (3 amounts)\n- Scenario: happy path, gun offline (simulate), gun already charging, RemoteStart rejected (simulate)\n\nTotal ~30 test runs at pilot station. Log any UPI-app-specific quirks (BHIM in particular has stricter parsing).\n\nWhoever pilots — use throwaway UPI-linked phone number so we can also validate the walk-in-user creation path (not an existing app user's phone).\n\nBlocked on Phase 1 implementation complete + QR sticker printed.</body>

added 08-02 11:53 · by saravanan@scrumclaw.ai · claude-cowork

Backend API for the admin web page (#55). Under /admin/* (or /internal/admin/*) behind role-gated middleware.\n\n- GET /admin/users?search=... — search by phone/email/VPA/user_id\n- GET /admin/users/:id — user detail including wallet balance, ledger, sessions, UPI handles\n- GET /admin/payments/:razorpay_payment_id — payment lookup\n- POST /admin/payments/:razorpay_payment_id/refund — full/partial refund via Razorpay Refunds API + REVERSAL ledger entry\n- QR management endpoints (see #61)\n- GET /admin/audit — recent admin actions log\n\nRole gate: reuse existing JWT + add role claim, or a dedicated admin_users table. TDD to decide.\n\nBlocked on TDD (#50).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

The app-user "Start Charging" button calls some Go function that ultimately sends OCPP RemoteStartTransaction to the charger. Same code path needs to be triggerable from the webhook handler (server-initiated, no user JWT context).\n\nTasks:\n1. Locate the current Go function/method for starting a session (likely inside internal/handlers/charging_handler.go or an internal service).\n2. Confirm it can be called with (user_id, charger_id, connector_id, reserved_amount) purely from server code — no gin.Context assumption.\n3. If it currently requires a gin.Context, refactor to extract a pure service function chargingService.StartSession(...).\n4. Wire the walk-in webhook to call this shared entry point.\n5. Add 3x5s retry wrapper per BRD FR19.\n\nBlocked on TDD (#50).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Per BRD v1 §7.2 FR6–FR9.\n\nExtend existing internal/handlers/wallet_handler.go PaymentWebhook to switch on hook.Event:\n\n switch hook.Event {\n case "payment.captured": // existing app topup path\n case "qr_code.credited": // NEW walk-in path\n h.handleQRCredit(payload)\n }\n\nhandleQRCredit implements:\n1. Lookup gun via notes.charger_id + notes.connector_id (cross-check charger_qr_codes row exists)\n2. Call resolveOrCreateUser(contact, email, vpa)\n3. Insert TOPUP ledger entry (idempotency key: qrpay:<payment_id>)\n4. Check OCPP status of connector — if Available, trigger RemoteStart via existing internal path with 3x5s retry (see #62)\n5. If not Available, credit persists in wallet only\n6. If WALKIN_QR_SMS_ENABLED flag on → dispatch appropriate SMS template (Phase 1.5)\n7. Return 200 to Razorpay\n\nBlocked on TDD (#50), migrations 0028–0029.</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Per BRD v1 §7.1 FR1–FR4.\n\nNew backend endpoints under /internal/admin/:\n\n- POST /admin/chargers/:id/connectors/:cid/qr — create if not exists; returns razorpay_qr_id + image_url\n- POST /admin/chargers/:id/connectors/:cid/qr/regen — close existing QR (via Razorpay POST /v1/payments/qr_codes/:id/close) and create new one; updates charger_qr_codes row\n- GET /admin/chargers/:id/connectors/:cid/qr — return current QR + image URL for reprint\n- GET /admin/chargers/qr — list all QRs across all stations, for admin console listing\n\nWraps Razorpay QR Codes API. All calls go server-to-server with Razorpay API key basic auth (reuse pattern in wallet_handler.go createRazorpayOrder).\n\nBlocked on Razorpay QR API enablement (#52) and TDD (#50).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Per BRD v1 §7.3 FR10–FR15. New Go methods on UserRepository:\n\n- GetByVPA(vpa string) (*User, error) — JOIN with user_upi_handles\n- GetByEmail(email string) (*User, error) — if not already present\n- InsertUPIHandle(userID, vpa, source string, primary bool) error\n- TouchUPIHandle(userID, vpa string) error — bump last_seen_at + payment_count++\n- New service function resolveOrCreateUser(contact, email, vpa string) — implements the phone > email > VPA priority + backfill-on-match + walk-in creation logic\n\nBlocked on migration 0028 (#57) landing.</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Per BRD v1 §7.1 FR3.\n\nCREATE TABLE charger_qr_codes (\n id UUID PK,\n charger_id VARCHAR(50) NOT NULL,\n connector_id INT NOT NULL,\n razorpay_qr_id VARCHAR(100) UNIQUE NOT NULL,\n razorpay_qr_short_url TEXT,\n razorpay_qr_image_url TEXT,\n status VARCHAR(20) NOT NULL DEFAULT 'active',\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n UNIQUE (charger_id, connector_id)\n);\n\nBlocked on TDD lock (#50).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Per BRD v1 §7.3 + Appendix B.\n\n- ALTER users ALTER COLUMN phone_number DROP NOT NULL\n- Recreate phone UNIQUE as partial index (WHERE phone_number IS NOT NULL)\n- CREATE TABLE user_upi_handles (per WIP schema in #51)\n- Register 'upi_walkin' as an accepted auth_provider value (no enum in Postgres — code-side check only)\n\nDoes NOT touch existing wallets/ledger/sessions/reservations tables.\n\nBlocked on TDD lock (#50).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Chosen in BRD Q18 as the ops interface. Minimum scope for Phase 1: - Login (reuse existing admin auth or add role gate) - User lookup by phone / email / VPA / payment_id — show wallet balance, session history, walk-in vs app-registered - Payment lookup by Razorpay payment_id / order_id — show status, ability to refund (full/partial) - QR management: list all gun QRs, image download (for reprint), regenerate (close+create) button - Simple audit log: which admin took which action, when Can be a subroute of the existing Expo web app (feature-flagged /admin route) or a separate small React/Next admin app. Existing app already has JWT auth we can extend with a role claim. 1–2 weeks frontend work. Backend needs matching admin endpoints (~1 week).</body>

added 08-02 11:45 · by saravanan@scrumclaw.ai · claude-cowork

DLT SMS registration is NOT done. 2–4 weeks external timeline. Track in parallel to Phase 1 build. Templates needed (send via Fast2SMS post-approval): - **wk_session_start** — "Vajra Volt: Charging started at {station}·Gun {gun}. ₹{reserved} reserved. Support: 88831-61155." - **wk_session_low_balance** — "Vajra Volt: Wallet running low (₹{remaining}). Scan QR to add money and keep charging." - **wk_session_end** — "Vajra Volt: Session complete. Used {kwh} kWh, cost ₹{cost}. Balance ₹{remaining}. Reply CLAIM to link this account." - **wk_payment_gun_busy** — "Vajra Volt: Payment ₹{amount} received but Gun {gun} is unavailable. Amount saved to your wallet. Support: 88831-61155." - **wk_refund_initiated** — "Vajra Volt: Refund of ₹{amount} initiated to your UPI. Reflects in 1–3 business days." All 4 languages (Q11 answer). English variants can be filed immediately; regional translations need vendor. Phase 1 launches WITHOUT SMS (see decision item). SMS goes live in Phase 1.5 once DLT approved.</body>

added 08-02 11:44 · by saravanan@scrumclaw.ai · claude-cowork

After BRD + design review are locked, produce the formal technical design doc covering: - Sequence diagram (customer → Razorpay → backend → OCPP → charger) - Data model changes (schema migration text) - API contracts (webhook handler, admin QR provisioning, guest-mode read endpoints) - Idempotency + concurrency model - Failure/retry semantics (webhook re-fires, gun offline, RemoteStart rejected, refund flow) - SMS content + provider integration details - Observability (metrics + logs to add) - Test plan (unit + integration + one live pilot station) - Rollout / rollback plan - Estimated effort per phase Commit finalized TDD to docs/TDD-walkin-qr.md in the backend repo. Only after this ships do we start implementation items.</body>

added 07-31 03:24 · by saravanan@scrumclaw.ai · claude-cowork

Once BRD v1 is locked, walk through the WIP technical design (see WIP note) and confirm / update each element against BRD requirements. Identified areas that likely need change: - Amount UX (fixed / preset / open) - Plug-in sequence vs payment sequence - Session termination criteria (money-out / SoC-100 / unplug / time-cap) - Refund vs wallet-retention default policy - Failure paths (gun offline, RemoteStart rejected, payment succeeded) - SMS content templates (English / vernacular) - Guest-mode web page scope (Phase 1 vs later) - QR provisioning ops (batch API + printable exports) - Walk-in → app-user claim/merge flow Output: a delta list feeding into the TDD.</body>

added 07-31 03:24 · by saravanan@scrumclaw.ai · claude-cowork

Draft the business requirements document covering: - Executive summary + business rationale - Success metrics/KPIs - Scope (in / out / later) - Personas (New walk-in, Returning walk-in, App user, Ops) - User journeys (happy path + 3-5 unhappy paths) - Functional requirements (FR1–FRn) — business-level, not code - Non-functional (latency, SMS SLA, PII, KYC/PPI) - Business rules (min/max payment, wallet retention policy, refund SLA, expiry, etc.) - Dependencies (Razorpay QR product, Fast2SMS, OCPP, physical print vendor, legal) - Risks & mitigations - Rollout phases - Open questions requiring product/business owner decision v0 draft lives in this session's outputs/vajra-walkin-qr-brd-v0.md. Once user answers the OPEN QUESTIONS in v0, we cut v1 and commit to docs/BRD-walkin-qr.md in the backend repo.</body>

added 07-31 03:24 · by saravanan@scrumclaw.ai · claude-cowork

Migration 0027 only inserts positive ADJUSTMENT entries when `wallets.balance > 0 AND gap.amount >= 0.01`. Users whose legacy wallets.balance is 0 (never populated) but who accumulated CHARGE entries end up with negative ledger balances and no automatic reconciliation. Concrete case: saravanan.hp@gmail.com currently shows balance = -11152.52. Ledger has CHARGE entries but no matching TOPUP history was migrated in. Options: (a) Backfill missing legacy topups from external Razorpay reports before running the reconcile. (b) Add a companion migration that reconciles from a manually-curated CSV of legacy balances. (c) Add an admin credit tool + audit trail so support can fix these case-by-case. Track down the actual topup history for affected users (query Razorpay payments API filtered by our account) and decide the right long-term reconciliation approach.

added 07-31 02:51 · by saravanan@scrumclaw.ai · claude-cowork

ProcessTopupWebhook uses `if topup.Amount != amount` — direct float64 equality. A tiny rounding drift (e.g., 500.00 stored vs 499.99999998 derived from Razorpay's paise/100) will falsely reject the webhook as 'amount mismatch', leaving the user paying but not credited. Change to: if math.Abs(topup.Amount - amount) > 0.01 { ... } Or better: store amount as int64 paise everywhere and compare integers.

added 07-31 02:51 · by saravanan@scrumclaw.ai · claude-cowork

Useful for ops debugging (missing webhook, dispute lookup, reconciliation). Wraps Razorpay: GET https://api.razorpay.com/v1/payments/qr_codes/:qr_id/payments Backend endpoint: GET /admin/chargers/:charger_id/connectors/:connector_id/payments Returns array of payments captured against that gun's QR (all-time), each with vpa, contact, email, amount, timestamp, status. Enables ops to answer "who paid at this gun today" without querying our DB. Small addition to the admin endpoints in #65. Roughly 1 hour of Go + admin console UI work.</body>

added 08-02 12:10 · by saravanan@scrumclaw.ai · claude-cowork

Behind WALKIN_QR_SMS_ENABLED flag. 5 templates × 4 languages (see #53).\n\nBackend changes:\n- Templates stored in Go source (map[templateKey]map[lang]string) with DLT template IDs from #53\n- Language selection: prefer user.preferred_language if set; fallback to English\n- Dispatch service reuses existing Fast2SMS integration (already in codebase for OTP)\n- Fire-and-forget from webhook handler (async goroutine); log failures but don't block webhook response\n\nBlocked on DLT approval (#53).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Both flags default false, set via /opt/ocpp/.env:\n\n- WALKIN_QR_ENABLED — master gate. When false, /webhooks/payment ignores qr_code.credited events (returns 200 "ignored"). Enable per station rollout.\n- WALKIN_QR_SMS_ENABLED — separate switch for Phase 1.5. When true, dispatch SMS via Fast2SMS on start/end/etc.\n\nAdd to internal/config/config.go loader. Wire into wallet_handler.go and any SMS-sending code.\n\nAllows Phase 1 → Phase 1.5 rollout without redeploy.</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

Per BRD v1 §7.6 FR26 — for phone-less walk-in recovery.\n\nALTER TABLE charging_sessions ADD COLUMN session_code VARCHAR(10);\nCREATE UNIQUE INDEX charging_sessions_session_code_idx ON charging_sessions (session_code) WHERE session_code IS NOT NULL;\n\nOnly populated for walk-in sessions where contact is missing. Short human-readable code (e.g. V-4F2A9) customer can quote to support.\n\nBlocked on TDD lock (#50).</body>

added 08-02 11:52 · by saravanan@scrumclaw.ai · claude-cowork

BRD Q8 spec locked: - A5 landscape (5.8" × 8.3"), vinyl, laminated for outdoor durability - Contents: Razorpay QR image (large, centered) + human-readable station+gun ID (e.g., "Vajra Volt · VAJRA0001 · Gun 2") + typical-cost hint ("Typical 30-min charge ≈ ₹150–300") - Support phone number visible - English only (Q20 answer) - Print files: SVG + PDF at 300 DPI - Vendor: existing signage vendor already identified (Q17) Sample layout: [ Vajra Volt logo ] [ QR CODE 4"x4" ] VAJRA0001 · Gun 2 Scan any UPI app to pay Typical charge ≈ ₹150–300 Support: 88831-61155 Deliverable: printable design ready for vendor.</body>

added 08-02 11:45 · by saravanan@scrumclaw.ai · claude-cowork

The webhook endpoint currently accepts any POST from anywhere. HMAC signature check is the only defense — cryptographically sound, but each invalid request still triggers signature compute + JSON parse + DB lookup, so it's a cheap DoS vector. Two things worth adding (nginx-level is easiest): 1. Restrict source IPs to Razorpay's published webhook IPs (they publish a list): allow only those in the nginx server block for /webhooks/*. 2. Rate-limit /webhooks/* at nginx (limit_req_zone). Even a modest 20 rps burst limit stops volumetric noise. Doesn't change functionality, just hardens.

added 07-31 02:51 · by saravanan@scrumclaw.ai · claude-cowork

Frontend passes `me.phone_number || storedEmail || ''` into Razorpay's prefill.contact. That field expects a phone number and is used to auto-detect UPI apps. Passing an email makes checkout look wrong and skips UPI autofill. Fix: only set prefill.contact when we have an actual phone number; put the email into prefill.email instead. prefill: { name: userName, contact: me?.phone_number?.trim() || undefined, email: storedEmail || undefined, }

added 07-31 02:51 · by saravanan@scrumclaw.ai · claude-cowork

Backend constant minTopupAmount is 1 but the error message and frontend both say the minimum is 100. Change minTopupAmount to 100 so the backend actually enforces what the message claims — otherwise a bespoke client can top up ₹1 (bypasses the intended floor). - const minTopupAmount = 1 + const minTopupAmount = 100

added 07-31 02:51 · by saravanan@scrumclaw.ai · claude-cowork

Razorpay deprecated the payment_capture parameter for the Orders API — capture behavior is now controlled at the account/merchant level. Not a functional bug today, but noise, and Razorpay may eventually reject unknown fields in future API versions. Drop the key from the payload in createRazorpayOrder.

added 07-31 02:51 · by saravanan@scrumclaw.ai · claude-cowork

DLT registration is 2–4 weeks. Rather than delay walk-in launch, Phase 1 will ship with LED-based confirmation only: - Customer knows charging started when the green LED on the gun activates (Q5 confirmed). - No SMS on session start, low balance, or session end for Phase 1 walk-ins. - App users still get all their existing notifications (unaffected). - After DLT approval + template registration, Phase 1.5 patches SMS in as a config flip — no schema change needed. Trade-off: walk-in session-end UX is worse. If a customer left their car and walked away, they won't know when charging finished. Mitigation: - Set the 2-hour hard cap (Q6) so guns don't stay locked forever. - Print the phone number on the QR sticker so customers can call to check status. - Auto-stop threshold of ₹50 remaining (Q7) reduces the "session died silently" scenario for underpayers. If DLT lands earlier than expected we'll enable SMS immediately.</body>

added 08-02 11:45 · by saravanan@scrumclaw.ai · claude-cowork

The initial ad-hoc technical sketch for walk-in QR-pay (schema + matching logic) surfaced multiple design gaps around amount UX, session termination policy, plug-in sequence, failure handling, and refund/wallet retention. Rather than iterate on code, we're switching to: 1. Write BRD → capture business requirements + explicit open questions 2. Review current technical design against BRD → find gaps 3. Iterate design; lock via TDD (technical design doc) 4. Only then implement (migration, repo logic, handlers, etc.) This prevents rework and ensures every stakeholder is aligned before code is written. All future items in this feature reference the eventual TDD.</body></priority>

added 07-31 03:24 · by saravanan@scrumclaw.ai · claude-cowork

Where to find each customer field in the qr_code.credited webhook payload. Confirmed from Razorpay official docs (docs/webhooks/qr-codes). **Payload path for VPA:** `payload.payment.entity.vpa` **Trimmed sample:** ```json { "event": "qr_code.credited", "contains": ["payment", "qr_code"], "payload": { "payment": { "entity": { "id": "pay_HO2fEpc9JeOQU5", "amount": 200, "method": "upi", "vpa": "gauri.kumar@okhdfcbank", "email": "gauri.kumari@example.com", "contact": "+919000090000", "customer_id": "cust_HKsR5se84c5LTO", "notes": {}, "acquirer_data": { "rrn": "116812981837" } } }, "qr_code": { "entity": { "id": "qr_HO2e0813YlchUn", "notes": { "charger_id": "VAJRA0001", "connector_id": "2" } } } } } ``` **Two subtle gotchas:** 1. **Two separate `notes` blocks** — `payload.payment.entity.notes` is per-payment (usually empty for QR), and `payload.qr_code.entity.notes` is the QR's notes (where we set charger_id + connector_id at QR creation). Read the second one for gun identification. 2. **VPA presence:** always present for QR-triggered payments (method is always upi). Fallback: null. **Go struct extraction:** see TDD §4.3 `qrCreditedPayload`. **Fallback retrieval (webhook lost):** - `GET /v1/payments/pay_XXX` — fetch single payment; includes vpa - `GET /v1/payments/qr_codes/qr_XXX/payments` — list all payments for a QR (great for admin ops "show all payments to this gun") Sources: - https://razorpay.com/docs/webhooks/qr-codes/ - https://razorpay.com/docs/webhooks/payloads/payments/</body>

added 08-02 12:10 · by saravanan@scrumclaw.ai · claude-cowork

Snapshot of the initial ad-hoc design so it isn't lost during the BRD/TDD process. May be revised or discarded. **Users table change:** - ALTER users ALTER COLUMN phone_number DROP NOT NULL - Recreate UNIQUE index as partial (WHERE phone_number IS NOT NULL) so multiple NULLs are allowed - New auth_provider value: 'upi_walkin' **New table user_upi_handles** — many VPAs per user, source-tagged: id UUID PK, user_id UUID FK, vpa VARCHAR(100), first_seen_at, last_seen_at, payment_count INT, source VARCHAR(30), is_primary BOOL, UNIQUE(user_id, vpa), INDEX on LOWER(vpa) **Match priority (webhook → user):** phone (contact) → email → vpa → else create walk-in **Repository additions:** UserRepository.GetByVPA(vpa) UserRepository.InsertUPIHandle(userID, vpa, source, primary) UserRepository.TouchUPIHandle(userID, vpa) **Auth claim flow (later):** OTP login on existing walk-in phone → attach, don't duplicate Flip auth_provider from 'upi_walkin' → 'password' Wallet balance + history preserved This design has open gaps around amount UX, plug/pay order, session termination, and failure handling — see the BRD-vs-design review todo.</body>

added 07-31 03:24 · by saravanan@scrumclaw.ai · claude-cowork