Lb1/docs/ARCHITECTURE.md

🏛️ Luxe Platform - Backend Architecture Blueprint

System Overview

Luxe Platform is an enterprise classified marketplace designed for high availability, zero-downtime deployment, horizontal scale, and millions of concurrent users & listings.

The backend is built following Clean Architecture as a Microservice-Ready Monorepo.

                           +------------------------+
                           |  Cloudflare WAF / CDN  |
                           +-----------+------------+
                                       |
                                       v
                           +------------------------+
                           |   Fastify API Gateway  |
                           +-----------+------------+
                                       |
       +-------------------------------+-------------------------------+
       |                               |                               |
       v                               v                               v
+--------------+               +---------------+               +---------------+
| Identity &   |               | Listing &     |               | Wallet &      |
| Auth Service |               | Search Service|               | Ledger Service|
+--------------+               +---------------+               +---------------+
       |                               |                               |
       +-------------------------------+-------------------------------+
                                       |
                                       v
                        +----------------------------+
                        |  PostgreSQL 16 (Primary)   |
                        |  Redis 7 (Cache & BullMQ)  |
                        |  MinIO / Cloudflare R2     |
                        +----------------------------+

---

Workspace Structure

• packages/database: Central Prisma ORM data layer with PostgreSQL schemas, soft deletes, GIN/B-tree indexing, and seeder scripts.
• packages/shared: Enterprise core utilities, standard HTTP response wrappers, Argon2 password hashing, JWT token rotation, Zod request schemas, and dynamic RBAC policies.
• services/gateway: High-performance Fastify API Gateway handling TLS termination, rate limiting, request validation, authentication hooks, Swagger UI docs, and Socket.IO real-time websockets.
• services/notification-service: Async background worker powered by BullMQ processing multi-channel notifications (Email, SMS, WhatsApp, Telegram).

---

Clean Architecture Layers

1. Domain Layer: Entity models defined in Prisma & TypeScript schemas.
2. Use-Case / Service Layer: Business logic for verification queues, immutable wallet ledgers, coupon processing, and search filters.
3. Interface Adapters: Fastify routes, controllers, and socket handlers.
4. Infrastructure Layer: PostgreSQL, Redis, MinIO S3, Prometheus, Grafana, and Docker/Kubernetes orchestrators.