abdelrahman-aboalkhair/full-stack-e-commerce-platform

1. This is a monorepo with two primary runtime boundaries: src/client is the Next.js storefront/admin UI, and src/server is the Express API. The shared top-level files, Docker Compose, and Postman collections support local integration, but the application architecture is split cleanly into frontend, backend, and infrastructure.

2. The client is organized around Next.js App Router with route groups for public, auth, private, and dashboard experiences. Public pages cover catalog browsing, product detail, cart, and success screens; private pages cover user orders, profile, payment result screens, support, and real-time chat; dashboard pages cover admin operations such as products, inventory, attributes, analytics, reports, logs, users, transactions, and chats.

3. The UI layer is heavily componentized into atoms, molecules, organisms, templates, layout components, and feature-specific screens. This matters architecturally because the dashboard and storefront share generic building blocks, while each domain page composes its own localized feature components rather than relying on a single monolithic app shell.

4. Client-side data access is split between Redux Toolkit state and RTK Query API slices under src/client/app/store/apis. Those slices map to the server’s functional domains such as auth, products, cart, orders, checkout, analytics, logs, reports, chats, and users. There is also an Apollo client and GraphQL query layer for parts of the product/dashboard experience that use GraphQL instead of REST.

5. A notable frontend boundary is demo mode. When NEXT_PUBLIC_DEMO_MODE=true, the app can run fully in-browser without the backend, using mock catalog/session/store logic under src/client/app/lib/demo. The hosted demo uses this path, which means browse, auth, cart, checkout, orders, and even dashboard interactions can be simulated without network dependencies. If the API is unavailable and demo mode is off, the client can still fall back to static catalog data for browse-only pages.

6. The backend is a modular Express application built as feature folders under src/server/src/modules. Most domains follow the same internal shape: controller, service, repository, factory, routes, DTOs, and types. That pattern is repeated across auth, product, category, cart, order, payment, checkout, user, review, shipment, logs, reports, analytics, attributes, chat, section, variant, webhook, and address.

7. The server exposes both REST and GraphQL. REST is organized under versioned route trees (/api/v1, /api/v2) and includes the majority of CRUD and workflow endpoints. GraphQL is used selectively for product, transaction, and analytics subdomains, with a dedicated analytics GraphQL schema/resolver set for dashboard reporting.

8. Data persistence is centered on Prisma and PostgreSQL. Prisma schema and a long migration history define the evolving commerce model, including products, variants, attributes, orders, transactions, inventory/restock, and user relationships. This database is the main system of record for the store, admin, and analytics features.

9. Redis is a second backend dependency and is used for short-lived state and auth-related support. The presence of Redis utilities, token helpers, and a Redis infra layer suggests it acts as a cache/session/token store rather than a primary datastore. This makes Redis a supporting boundary for authentication and realtime-adjacent workflows, not the source of truth.

10. Real-time chat is a distinct subsystem spanning both client and server. The server has Socket.IO infrastructure plus a chat module, while the client has chat-specific hooks, container components, message rendering, audio/call UI, and socket connection hooks. This creates a separate event-driven data flow from the normal request/response API: browser socket events → server socket handlers → persisted or relayed chat data.

11. Checkout and payments are integrated through Stripe. The checkout module initiates payment flows, the payment module tracks outcomes, and the webhook module handles asynchronous provider callbacks. That means payment completion is not determined only by the browser redirect; the backend webhook is the authoritative confirmation path.

12. Analytics, reporting, and exports form another server-side read-heavy subsystem. Analytics has both REST and GraphQL layers plus shared aggregation utilities, while reports and transaction domains expose business summaries for the dashboard. Export utilities can produce CSV, PDF, and XLSX outputs, so reporting is designed as a downstream consumer of transactional and analytic data rather than a separate store.

13. Cross-cutting concerns are centralized in shared middleware, errors, logging, and utility layers on the server. Authentication/authorization, role hierarchy checks, DTO validation, upload handling, request logging, and error normalization sit outside domain modules. On the client, similar concerns are centralized through providers, guards, hooks, and layout templates.

14. Operationally, the repo is built for local self-hosting with Docker Compose, seeded data, and environment starter files. Swagger is exposed at /api-docs, Postman collections exist for each domain, and the client/server each have Dockerfiles. That makes the architecture suitable for diagramming as a locally runnable full-stack commerce system with external integrations for Stripe, Cloudinary, Redis, and optional OAuth/auth providers.