tayebbb/valore-parfums

1. The repository is a two-app monorepo split by responsibility. frontend/ is the customer-facing storefront plus admin UI, deployed on Netlify. backend/ is an API-only Next.js app deployed on Render. The frontend does not talk to Firestore directly; it forwards all /api/* traffic to the backend.

2. The main runtime boundary is “browser → frontend → backend → Firebase/third parties.” The frontend serves SSR/ISR pages, while the backend owns all mutable business operations: authentication, product CRUD, orders, pricing, finance, uploads, and notifications. This separation is central to any architecture diagram.

3. Firestore is the primary system of record, accessed only through the Firebase Admin SDK on the backend. Client Firestore rules deny all reads/writes. Collections are organized around commerce and operations: perfumes, orders, users, settings, decantSizes, bottles, vouchers, notifications, requests, stockRequests, wishlists, ownerAccounts, profitTransactions, auditLogs, and others.

4. Authentication is custom session-based. Email/password signup and login are handled server-side with PBKDF2 hashing and an HMAC-signed cookie (vp-session). Google sign-in uses Firebase client SDK on the frontend to obtain an ID token, which the backend verifies before creating the same session cookie. Admin access is enforced both in API routes and in the admin layout redirect logic.

5. The storefront is a classic commerce flow: browse homepage/shop/category/brand pages, view SEO-optimized product details, add items to a client-side cart, and check out. The cart lives in Zustand/localStorage on the frontend, but order creation is server-side, where the backend validates the cart, calculates pricing, deducts stock, stores the order snapshot, and triggers email plus admin alert hooks.

6. Pricing and finance are a separate subsystem, not embedded in the UI. Selling prices are derived from market price per ml, tier-based margin rules, bottle cost, and packaging cost, then rounded psychologically. Orders store immutable financial snapshots in minor units, and item-level profit is computed separately. This enables reporting, owner balance tracking, and later reconciliation.

7. Fulfillment supports two business paths: customer orders and sourcing requests. Standard orders can be delivery or pickup, with manual payment methods for bKash/bank transfer or COD. Separate request flows capture customer sourcing requests and full-bottle leads. Admin-created stock requests can also become sourcing-driven order records.

8. The admin panel is a second major UI surface, protected by role checks. It manages the catalogue, stock, bottle inventory, decant sizes, vouchers, pickup locations, notifications, store settings, requests, orders, exports, and reports. Dashboard charts and KPIs are fed by backend aggregates, including owner balances and low-stock signals.

9. Media and messaging are handled by external services. Product and QR images upload to Cloudinary, then their URLs are stored in Firestore. Emails are sent via Nodemailer over Gmail SMTP, with different templates for order confirmation, payment confirmation, dispatch, delivery, cancellation, and pickup events.

10. The frontend has a substantial SEO/content subsystem. It renders product pages with canonical URLs, JSON-LD schema, sitemap generation, robots directives, blog content, and six programmatic landing pages. There is also a Google Shopping-style merchant feed exposed from the backend, though it is not a primary user-facing path.

11. Cross-cutting concerns are implemented in shared server libraries: input validation, rate limiting, audit logging, order status configuration, image helpers, and cached reads for high-traffic endpoints. Some caches are in-memory per process, so they are not shared across instances; that matters for any deployment diagram showing horizontal scaling.

12. There are also maintenance and operational scripts in backend/scripts/ and duplicated in frontend/scripts/. These are one-off data repair and audit tools for stock, margins, decant sizes, perfumes, and finances. They are not runtime components, but they reflect that the backend is the authoritative place where operational data corrections happen.