Pazhakadai Technical Design

pazhakadai/
├─ docs/                      SPEC.md, flows.html, technical.html
├─ api/
│  ├─ src/Pazhakadai.Api/          ASP.NET Core host: endpoints, auth, SignalR, workers
│  ├─ src/Pazhakadai.Domain/       entities, state machine, money/weight value types
│  ├─ src/Pazhakadai.Infrastructure/  EF Core + Dapper, Razorpay client, FCM, files, PDF
│  └─ tests/                       unit + integration (Testcontainers MySQL)
├─ web/
│  ├─ shop/                   Next.js customer website
│  ├─ admin/                  Next.js admin + supervisor + counter billing
│  └─ packages/api-client/    TypeScript client generated from the API's OpenAPI document
├─ mobile/
│  ├─ customer_app/           Flutter
│  ├─ delivery_app/           Flutter
│  └─ packages/pz_core/       shared Dart: API client, auth, models, formatting
├─ db/migrations/             EF Core migrations (checked in, applied on deploy)
└─ deploy/                    nginx, systemd units, backup scripts, CI workflows

public static long LineTotalPaise(int qtyG, long pricePerKgPaise) =>
    (qtyG * pricePerKgPaise + 500) / 1000;

public static string FinancialYear(DateOnly istDate) =>
    istDate.Month >= 4
        ? $"{istDate.Year}-{(istDate.Year + 1) % 100:00}"
        : $"{istDate.Year - 1}-{istDate.Year % 100:00}";

6.1 Checkout steps

1. Load the cart and the branch settings. Reject if the branch is paused or the PIN isn't served.
2. Start a transaction (READ COMMITTED).
3. For each line, sorted by branch_product_id (consistent lock order prevents deadlocks), run the conditional update below.
4. If any update affects 0 rows, or any current price differs from what the client showed (expectedTotalPaise), roll back and return 409 with a list of changes.
5. Insert orders (PAYMENT_PENDING, hold_expires_at = now + 10 min), order_items (snapshots) and stock_holds (ACTIVE). Commit.
6. After commit, create the Razorpay order. If that call fails, release the hold immediately and return an error.

-- Reserve. Succeeds only if enough is available right now.
UPDATE branch_products
   SET held_g = held_g + @qty
 WHERE id = @branch_product_id
   AND is_sold = 1 AND is_hidden = 0
   AND price_per_kg_paise = @price_seen_by_customer
   AND stock_g - held_g >= @qty;
-- affected rows = 1 → held; 0 → out of stock, hidden, or price changed (re-read to tell which)

6.2 Confirm (payment captured)

Called from the webhook, from the signed checkout callback, and from the expiry worker's reconciliation. It must be idempotent.

BEGIN;
SELECT status FROM orders WHERE id = @order_id FOR UPDATE;    -- serialises confirm vs expiry vs duplicate webhook
INSERT INTO payments (...) VALUES (...)                          -- unique razorpay_payment_id: duplicate → stop, already handled

-- If status = PAYMENT_PENDING (holds still ACTIVE, even if hold_expires_at just passed):
UPDATE branch_products bp JOIN stock_holds h ON h.branch_product_id = bp.id
   SET bp.stock_g = bp.stock_g - h.qty_g,
       bp.held_g  = bp.held_g  - h.qty_g
 WHERE h.order_id = @order_id AND h.status = 'ACTIVE';
UPDATE stock_holds SET status = 'CONVERTED', resolved_at = UTC_TIMESTAMP(6) WHERE order_id = @order_id AND status = 'ACTIVE';
INSERT INTO stock_movements (type = 'SOLD_ONLINE', ...);         -- one per line
-- allocate bill number (section 10), insert bill + lines, generate OTP
UPDATE orders SET status = 'CONFIRMED', delivery_otp = @otp, confirmed_at = UTC_TIMESTAMP(6) WHERE id = @order_id;
INSERT INTO order_status_history (...);
COMMIT;
-- after commit: FCM to customer, SignalR + web push to branch staff

-- If status = PAYMENT_FAILED (hold already released) → status = PAYMENT_REVIEW, is_late = 1. No stock change.
-- If status = CONFIRMED and this is a different payment id → record it, flag for review (customer paid twice).

6.3 Release (failed, dismissed checkout, or expired)

BEGIN;
SELECT status FROM orders WHERE id = @order_id FOR UPDATE;
-- only if status = PAYMENT_PENDING
UPDATE branch_products bp JOIN stock_holds h ON h.branch_product_id = bp.id
   SET bp.held_g = bp.held_g - h.qty_g
 WHERE h.order_id = @order_id AND h.status = 'ACTIVE';
UPDATE stock_holds SET status = 'RELEASED', resolved_at = UTC_TIMESTAMP(6) WHERE order_id = @order_id AND status = 'ACTIVE';
UPDATE orders SET status = 'PAYMENT_FAILED' WHERE id = @order_id;
COMMIT;

6.4 Other stock writers use the same guard

6.5 Timing details

• Razorpay Checkout gets timeout = seconds left on hold − 60, so the payment window closes before the hold does.
• The hold is formally ended by the expiry worker, not by the clock. A capture arriving after hold_expires_at but before the worker ran still converts, because the stock is still held.
• Before releasing an expired order, the worker asks Razorpay for the order's payments (GET /v1/orders/{id}/payments). If one is captured, it confirms instead. This covers missed or delayed webhooks.
• A new checkout by the same customer: if an ACTIVE hold exists with identical lines, return the same Razorpay order; otherwise release the old one first, in the same transaction.

// Checkout callback: signature = HMAC_SHA256(order_id + "|" + payment_id, key_secret)
bool VerifyCheckout(string orderId, string paymentId, string signature) =>
    FixedTimeEquals(HexHmacSha256(keySecret, $"{orderId}|{paymentId}"), signature);

// Webhook: signature = HMAC_SHA256(raw request body, webhook_secret), header X-Razorpay-Signature
app.MapPost("/api/webhooks/razorpay", async (HttpRequest req, PaymentService svc) => {
    var body = await new StreamReader(req.Body).ReadToEndAsync();      // raw bytes, before any JSON parsing
    if (!FixedTimeEquals(HexHmacSha256(webhookSecret, body), req.Headers["X-Razorpay-Signature"]))
        return Results.Unauthorized();
    var eventId = req.Headers["x-razorpay-event-id"].ToString();
    if (!await svc.TryRecordEvent(eventId, body)) return Results.Ok();   // duplicate delivery
    await svc.Handle(body);                                              // fast; heavy work after commit
    return Results.Ok();
});

Refunds (D23: full only, admin only)

POST /v1/payments/{payment_id}/refund
{ "amount": <payment amount in paise>, "speed": "normal",
  "receipt": "<order_no>-R", "notes": { "reason": "...", "staff": "<staff public_id>" } }

Insert refunds (PENDING) and set the order to CANCELLED in the same transaction as the restock, then call Razorpay after commit. refund.processed marks the refund PROCESSED and the order REFUNDED. refund.failed raises an admin alert. A worker re-fetches refunds still PENDING after 24 hours.

Gap-free numbering, per branch per financial year

-- inside the same transaction that inserts the bill; a rollback leaves no gap
INSERT INTO bill_sequences (branch_id, fy, next_no) VALUES (@b, @fy, 1)
  ON DUPLICATE KEY UPDATE next_no = next_no;
SELECT next_no FROM bill_sequences WHERE branch_id = @b AND fy = @fy FOR UPDATE;
UPDATE bill_sequences SET next_no = next_no + 1 WHERE branch_id = @b AND fy = @fy;
-- bill_no = $"{branch.Code}/{fy}/{seq:D6}"  →  A/2026-27/000123

@page { size: 80mm auto; margin: 0 }
body  { width: 72mm; margin: 4mm; font: 11px/1.4 monospace }

// tap 1: open the chat
const msg = `Thank you for shopping at Pazhakadai, ${branchName}. Bill ${billNo}, ₹${total}.`;
window.open(`https://wa.me/91${mobile}?text=${encodeURIComponent(msg)}`, "_blank");

// on save: prefetch
const pdf = new File([await (await api.get(`/api/admin/bills/${id}/pdf`)).blob()],
                     `${billNo.replaceAll("/", "-")}.pdf`, { type: "application/pdf" });

// tap 2: share the file
if (navigator.canShare?.({ files: [pdf] })) await navigator.share({ files: [pdf], title: billNo });
else downloadFallback(pdf);   // desktop browsers without file sharing: download, then drag into WhatsApp Desktop

• Upload via POST /api/admin/products/{id}/image, multipart, max 5 MB. Accept JPEG, PNG and WebP by decoding them, not by trusting the extension.
• SkiaSharp: resize to max 1200 px and a 400 px thumbnail, re-encode as WebP (quality 80). Re-encoding strips metadata and any embedded payload.
• Saved as /srv/pazhakadai/uploads/products/{ulid}.webp and {ulid}_t.webp; the DB stores relative paths. New uploads get new names, so caches never serve stale images.
• nginx serves /uploads/ directly with expires 30d. The API is not involved in reads.

# Auth
POST /auth/customer/register        POST /auth/customer/login       POST /auth/staff/login
POST /auth/refresh                  POST /auth/logout               POST /auth/change-password

# Customer
GET  /branches?pincode=600010        GET  /branches/{id}/products?category=
GET  /addresses   POST /addresses   PUT /addresses/{id}   DELETE /addresses/{id}
GET  /cart        PUT /cart/context  {branchId, fulfilment, addressId}
PUT  /cart/items/{branchProductId}  {qtyG}         DELETE /cart/items/{branchProductId}
POST /checkout    {expectedTotalPaise}  → 200 {orderId, razorpayOrderId, amountPaise, keyId, timeoutSeconds}
                                        → 409 {changes:[{product, kind: PRICE|STOCK|UNAVAILABLE|MIN_ORDER|PAUSED, ...}]}
POST /payments/verify  {razorpayOrderId, razorpayPaymentId, razorpaySignature}
POST /payments/abandon {orderId}                   # checkout dismissed → release now
GET  /orders      GET /orders/{id}  (includes OTP)  GET /orders/{id}/bill.pdf
POST /devices     DELETE /devices/{token}

# Razorpay
POST /webhooks/razorpay

# Admin (branch-scoped)
GET|POST|PUT      /admin/branches  /admin/branches/{id}/pincodes  /admin/branches/{id}/pause
GET|POST|PUT      /admin/categories  /admin/products  POST /admin/products/{id}/image
GET|PUT           /admin/branches/{b}/products/{productId}      # price, step, min, low-stock, hidden
POST              /admin/branches/{b}/stock-movements           {branchProductId, type, qtyG, unitCostPaise?, reason}
GET               /admin/branches/{b}/stock-movements?product=&from=&to=
GET               /admin/orders?branch=&status=&date=
POST              /admin/orders/{id}/pack        {estimatedDate}
POST              /admin/orders/{id}/ready       {pickupDate}
POST              /admin/orders/{id}/assign      {partnerId}
POST              /admin/orders/{id}/return      {estimatedDate}  # after failed attempt
POST              /admin/orders/{id}/collect     {otp}
POST              /admin/orders/{id}/override    {status, reason}
POST              /admin/orders/{id}/cancel      {reason, writeOffItemIds[]}
GET               /admin/orders/{id}/sticker
GET               /admin/payment-reviews        POST /admin/payment-reviews/{orderId}/confirm|refund
POST|GET          /admin/counter-bills          POST /admin/counter-bills/{id}/cancel
GET               /admin/bills/{id}/pdf
GET|POST|PUT      /admin/staff  /admin/partners  POST /admin/staff/{id}/deactivate|reset-password
GET               /admin/customers?mobile=     POST /admin/customers/{id}/reset-password|release-mobile
GET               /admin/reports/{daily-sales|product-sales|stock-wastage|status-board|refunds|partners}?format=csv
GET               /admin/audit?actor=&entity=&from=&to=

# Delivery partner
GET  /partner/orders/today          GET /partner/orders/history?month=
PUT  /partner/duty {onDuty}
POST /partner/scan {token}          # ASSIGNED → OUT_FOR_DELIVERY, or opens handover when OUT_FOR_DELIVERY
POST /partner/orders/{id}/deliver {token, otp}
POST /partner/orders/{id}/attempt-failed {reasonCode, note}

# deploy/nginx/admin.conf (excerpt)
server {
  server_name admin.pazhakadai.in;
  client_max_body_size 6m;
  location /api/     { proxy_pass http://127.0.0.1:5000; include proxy_params; }
  location /hubs/    { proxy_pass http://127.0.0.1:5000;
                       proxy_http_version 1.1;
                       proxy_set_header Upgrade $http_upgrade;
                       proxy_set_header Connection "upgrade";
                       proxy_read_timeout 1h; }
  location /uploads/ { alias /srv/pazhakadai/uploads/; expires 30d; add_header X-Content-Type-Options nosniff; }
  location /         { proxy_pass http://127.0.0.1:3001; include proxy_params; }
}

CI/CD (GitHub Actions)

1. On pull request: build and test API (including Testcontainers MySQL), lint and build both Next.js apps, flutter analyze and tests.
2. On merge to main: build artefacts, rsync to staging over SSH, apply EF migrations (efbundle), restart services, smoke-test /health.
3. Production: same job, triggered manually after staging is checked. Take a database dump immediately before migrating.

Off-server target: any S3-compatible bucket (e.g. Backblaze B2, Cloudflare R2) or Google Drive through rclone, encrypted with rclone crypt. Keep 30 days.

• Serilog to rolling JSON files (14 days) and journald. Every request logs a correlation id; webhook handling logs event id, order, outcome.
• Never log passwords, tokens, OTPs or full card or UPI data. Mask mobile numbers to the last 4 digits.
• /health checks MySQL connectivity and disk free space. An external uptime monitor polls it every minute and alerts by email or Telegram.
• Alert on: webhook signature failures, HoldExpiry worker not running for 5 minutes, disk over 80%, backup job failure.