NapAchte Docs
Technical documentation — Backend, Architecture & Advice
1. BACKEND GUIDE
stripeConfig
Purpose: Returns the Stripe publishable key to the frontend so it can initialize Stripe.js securely.
Inputs: None (authenticated user request)
Output: { publishable_key: string }
Edge cases: Should never expose the secret key. Always read from STRIPE_PUBLISHABLE_KEY env var.stripeCreatePayment
Purpose: Creates a Stripe PaymentIntent + an Order record in escrow status.
Inputs: listing_id, listing_title, listing_photo, seller_email, seller_name, amount_htg, notes
Output: { client_secret, order_id, amount_usd }
Behavior: Converts HTG→USD at 0.0075. Calculates 5% platform fee. Creates Order with status "pending_payment".
Edge cases: Buyer must not be the seller. Amount must be >$0.50 USD (Stripe minimum).stripeVerifyPayment
Purpose: Confirms a payment succeeded and moves Order to paid_in_escrow.
Inputs: { payment_intent_id, order_id }
Output: { success: true, order_id }
Behavior: Checks PaymentIntent status with Stripe. If succeeded, updates Order. Idempotent.
Edge cases: If already paid_in_escrow, return success without re-processing.stripeConfirmDelivery
Purpose: Buyer confirms receipt → releases escrow payout to seller.
Inputs: { order_id }
Output: { success: true }
Behavior: Updates delivery_confirmed_by_buyer: true, status: "completed", payout_released: true. Triggers Stripe transfer.
Edge cases: Only the buyer can confirm. Order must be in paid_in_escrow state.stripeDisputeOrder
Purpose: Buyer opens a dispute on an order.
Inputs: { order_id, reason }
Output: { success: true }
Behavior: Sets order status: "disputed", saves dispute_reason. Notifies admin.
Edge cases: Only works on paid_in_escrow orders. Prevents payout until resolved.stripeSellerOnboard
Purpose: Creates or retrieves a Stripe Connect account for a seller, returns onboarding URL.
Inputs: None (uses authenticated user email)
Output: { onboarding_url, account_id }
Behavior: Creates SellerAccount record if none exists. Uses Stripe Connect Express.
Edge cases: If already onboarded, return existing account link.stripeWebhook
Purpose: Handles Stripe webhook events server-side. Inputs: Raw HTTP body + Stripe-Signature header Behavior: Validates signature using STRIPE_WEBHOOK_SECRET. Handles payment_intent.succeeded, transfer.created, etc. Critical: Must use stripe.webhooks.constructEventAsync() (Deno async crypto). Validate via Stripe signature only — no user auth.
moncashCreatePayment
Purpose: Initiates a MonCash payment for Haitian mobile money users.
Inputs: listing_id, listing_title, listing_photo, seller_email, amount_htg, notes
Output: { redirect_url, order_id }
Behavior: Creates Order record. Calls MonCash API. Returns redirect URL.
Edge cases: Use MONCASH_MODE to toggle sandbox/production. Handle MonCash token expiration.moncashReturn
Purpose: MonCash redirects here after payment. Verifies and updates order. Inputs: Query params from MonCash redirect (transactionId, etc.) Output: Redirect to /moncash/success?order_id=... Edge cases: Verify the transaction with MonCash API before marking as paid.
deleteAccount
Purpose: Allows a user to permanently delete their account and all associated data. Inputs: Authenticated user session Behavior: Deletes listings, favorites, conversations, messages, orders. Then deletes User record.
2. APP NARRATIVE & FEATURES
What is NapAchte?
"NapAchtel" means "We Buy" in Haitian Creole. It is a Haitian marketplace platform — the Craigslist/Facebook Marketplace of Haiti, built specifically for Port-au-Prince and surroundings.
It solves a critical trust problem in informal Haitian commerce: buyers send money and never receive goods, or sellers get scammed. NapAchte introduces escrow-based payments so funds are held securely until the buyer confirms delivery.
The platform also includes a SharkTank-style investment module ("Requin Kapital") where Haitian entrepreneurs can pitch projects and attract local investors.Feature Breakdown
• Browse & Search — Filter by category, neighborhood, price, condition • Post a Listing — Upload photos/video, set price in HTG • Escrow Checkout — 3-step: delivery info → payment method → payment • Stripe Payments — USD card payments via Stripe Connect (5% platform fee) • MonCash Payments — HTG mobile money for Haitian users • Messaging — Real-time buyer-seller chat with file/audio attachments • Favorites — Save listings for later • Seller Profiles — Public profile with ratings, store info, all listings • Reviews — Star ratings + comments on sellers • Admin Approval — Listings go through moderation before going live • SharkTank — Entrepreneurs pitch projects, investors back them • Seller Onboarding — Stripe Connect KYC for sellers to receive payouts • My Orders — Track purchases, confirm delivery, dispute orders • Multilingual — French / Creole / English toggle • Multi-currency — HTG / USD display toggle • PWA-ready — Mobile app feel, safe-area support, Android back button
Connection Map
USER (Browser / Mobile WebView)
└─► FRONTEND (React + Vite)
├─► Entities (DB): Listing, Order, Favorite, Conversation, Message, Review, Project, SellerAccount, PayoutRequest, User
└─► Backend Functions (Deno Deploy)
├─► STRIPE API (PaymentIntents, Connect Accounts, Transfers, Webhooks)
└─► MONCASH API (Create payment, Verify transaction, Sandbox/Prod)
Authentication Flow:
AuthProvider → isAuthenticated?
No → Public pages (Home, Browse, ListingDetail)
Yes → Check user_type → No user_type → /onboarding
→ Has user_type → Full app access
Protected routes: PostListing, Messages, MyFavorites, MyListings, MyOrders, Profile
Admin-only routes: /admin/approval, /admin/migrationPayment Data Flow
Stripe path: stripeConfig() → get publishable key stripeCreatePayment() → create PaymentIntent + Order (pending_payment) Stripe.js renders card form → stripe.confirmPayment() stripeVerifyPayment() → Order updated to paid_in_escrow [Buyer confirms delivery] → stripeConfirmDelivery() → payout to seller MonCash path: moncashCreatePayment() → create Order + MonCash token Redirect to MonCash portal MonCash redirects to moncashReturn() Order updated → /moncash/success
3. LAST ADVICE FOR THE BACKEND
Architectural Considerations
• Escrow is the core trust layer — never release funds without explicit buyer confirmation. The Order state machine (pending_payment → paid_in_escrow → completed/disputed/refunded) must have server-side state transition guards. • Stripe webhooks are your source of truth — don't rely only on frontend stripeVerifyPayment calls. The webhook handler should also handle payment_intent.succeeded. • MonCash is async — always verify transactions server-side on the return handler, never trust query params alone. • HTG/USD conversion is hardcoded at 0.0075 — consider making this a configurable admin setting if the gourde rate changes.
Pitfalls to Avoid
• Stripe sync crypto in Deno → always use constructEventAsync() • Buyer = Seller checkout → check server-side too, not just frontend • Releasing payout without delivery confirm → state machine guard in stripeConfirmDelivery • MonCash sandbox in production → validate MONCASH_MODE env var on deploy • Large file uploads in entity fields → always use UploadFile integration, store only URL • Missing seller_email on old listings → migration function exists, run once on deploy • Admin routes without role check → every admin function checks user.role === "admin"
Monitoring & Observability
• Log all payment events with order_id, amount_usd, user_email, and status at every state transition • Log Stripe webhook events with event type and processing result • Alert on disputed orders — these need manual admin intervention • Track MonCash failures separately — the API is less reliable than Stripe • Monitor listing approval queue — listings stuck in "pending" cause seller frustration
Security Best Practices
• Never expose STRIPE_SECRET_KEY to the frontend — backend functions only • Validate webhook signatures on every Stripe/MonCash callback • Use service role sparingly — only after verifying authenticated user OR webhook signature • RLS on sensitive entities — Orders, Messages, Favorites scoped to created_by • Rate limit payment functions — prevent >10 PaymentIntents per user per hour • Sanitize delivery notes — stored in Order notes and sent to sellers
Scaling Considerations
• Listing enrichment is N+1 — each ListingCard fetches seller data separately. Cache seller profiles in the listing record itself as the catalog grows. • Messages use real-time subscriptions — archive old conversations to keep the active dataset small. • Image uploads go through Base44 CDN — consider compressing images client-side before upload. • SharkTank projects can be paginated using the same usePaginatedListings pattern as the browse page.
