Overview

A training project focused on exploring the architecture of a modern e-commerce site. Built to evolve, it will be improved iteratively and adapted to various tech stacks.

We will adopt Clean Architecture for this project, which is an excellent testing ground for this type of architecture This project will adopt Clean Architecture, serving as an excellent playground to explore its principles in practice. It will allow us to clearly see the benefits and trade-offs compared to more traditional architectures such as layered or monolithic designs.

Features

B2C Area

MVP features

• Product catalog
• Product detail page
• Cart management
• Simple search (name, category)
• Filtering and sorting (price, popularity, newness)
• Stock indicator (visual)
• Accessibility (ARIA), i18n (FR/EN)

Additional features

• Customer account creation (email + password, optional OAuth)
• Customer account management (profile, multiple addresses)
• Shipping and payment (simulated / sandbox flow)
• Order tracking (statuses)
• Order history
• Notifications (email/simulations, notification center)
• Basic recommendations (similar products)

Advanced features

• Multi-currency (display), basic taxes (simulated VAT)
• Shopping lists / gift lists
• Digital products (licenses, download links)
• Product reviews and ratings (admin-side moderation)
• Loyalty program (points, tiers, rewards)
• Subscriptions / auto-replenishment (simulated subscriptions)
• Product customization (options, simple configurator)
• Author and brand pages
• Scoring-based recommendations (client-side) and A/B testing for storefronts
• Advanced search (facets: price, brand, rating, availability)
• Multi-warehouse / inventory (simulated aggregated view)
• Advanced shipping (weight/zone rules, simulated pick-up point)
• Advanced payments (delayed capture, simulated 3-DS)

Admin features

• Management accounts and roles/permissions (admin, manager, support)
• Dynamic product catalog management (CRUD, CSV import/export)
• Aisles / product categories, attributes and variants (size, color)
• Customer support management (simple tickets, response macros)
• Shipping and order status management (preparation, shipped, delivered, cancelled)
• Returns (RMA) and refunds management (full/partial)
• Coupons / promo codes, pricing rules (by category/product)
• Mini-CMS (legal pages, T&Cs, FAQ, lightweight blog)
• Analytics dashboard (sales, conversion, product views, returns)
• Audit log (back-office actions)

B2B Area

MVP features

• Seller account creation (guided onboarding)
• Catalog management (product CRUD)
• Sales and revenue tracking (mini dashboard)
• Storefront customization (logo, banner, description)

Complementary features

• CSV or Excel import/export for products
• Sales statistics (by period, by product)
• Seller promotions management (specific discounts)
• Internal messaging (customer ↔ seller or seller ↔ support)
• Custom return policy

Advanced features

• External API integration (ERP, logistics, payments)
• Multi-store (one seller = several brands)
• Margins, commissions, and automated payouts management
• “Premium seller” label or public rating

Admin features

• Manual or automatic validation of new sellers
• Account suspension / deletion
• Product page moderation
• Seller performance reports
• Multi-channel support (tickets, email, chat)

Technical Stack

B2C Node.js Stack

Frontend

• Frameworks: React, Vue, Angular
  • Routing: React Router / Vue Router / Angular Router
  • SSR/SSG (optional): Next.js / Nuxt / Angular Universal
• State:
  • React: Context API → Redux Toolkit
  • Vue: Pinia + TanStack Query (server state)
  • Angular: NgRx (store/effects) or Signals + Query libs (RxJS), per-feature façade
• Forms & Validation:
  • React: React Hook Form
  • Vue: VeeValidate + Zod
  • Angular: Reactive Forms, Validators, Formly (optional)
• UI/Styles:
  • React: TailwindCSS + shadcn/ui (React)
  • Vue: PrimeVue
  • Angular: Angular Material (MDC) or Taiga UI / PrimeNG / NG-ZORRO
• i18n & A11y:
  • i18next (React/Vue)
  • Angular i18n or ngx-translate (Angular), ARIA, dark mode
• Build/Tooling:
  • Vite (React/Vue)
  • Angular CLI (Vite under the hood), SWC/TS, ESLint + Prettier, angular-eslint
• Monorepo (optional):
  • Nx (React/Vue/Angular apps + Node in the same repo)
• Mocking & Design System (option):
  • MSW (API)
  • Storybook (React/Vue/Angular)

Backend

• Runtime: Node
• Framework: NestJS (modules, DI)
• Language: Strict TypeScript (base tsconfig + paths)
• API: REST + OpenAPI/Swagger (zod-to-openapi or @nestjs/swagger)
• Security: Helmet, CORS, rate-limit, compression, CSRF (if cookies)
• Auth: JWT (access+refresh, HttpOnly cookies), optional OAuth2 (Google/GitHub)
• Validation: Zod (input schemas + env parsing)
• Logs: pino (JSON), pino-http, pino-pretty (dev)
• Cache/Session: Redis (guest cart, sessions, rate-limit)
• Files: Signed upload to S3/MinIO (product images), sharp (thumbnails)
• Email: nodemailer + MailHog in dev
• Payments (sandbox): Stripe (test), simulated webhook
• Search: Meilisearch (facets, typo tolerance) — optional
• Messaging: RabbitMQ/Redpanda (optional: orders, returns)

Database

• DB: PostgreSQL, Redis
• ORM: Prisma (migrations, seed), (Drizzle as an alternative)
• Migrations/Seed: prisma migrate, prisma db seed + realistic fixture files
• Indexing: SQL indexes on search/sort fields

Tests & Quality

• Unit:
  • Vitest + Testing Library (React/Vue)
  • Jest + @testing-library/angular (Angular)
• Integration:
  • Supertest (Express/Nest)
  • Testcontainers Node (Postgres/Redis/Meili)
• E2E: Playwright (or Cypress if preferred)
• Quality: ESLint, Prettier, commitlint + lint-staged, Husky (pre-commit)

DevOps

• Docker: Docker Compose (Postgres, PgAdmin, Redis, Kafka, MailHog, Meilisearch, MinIO)
• CI/CD: GitHub Actions (lint, type-check, tests, build)
• Images: Multi-stage Node builds, or Bun for fast tooling (optional)
• Config: .env + zod to type environment variables
• Observability: Prometheus metrics (express-prom-bundle), OpenTelemetry traces (optional)
• CDN: static cache (images, assets) — simulated locally

Patterns & Structure

• Architecture: services/repositories + controllers, light ports/adapters
• Feature Folders: catalog/, cart/, account/, orders/, vendor/
• Errors: typed error objects (ZodError → 422), global mapping
• Perf: cursor-based pagination, ETag/If-None-Match, client-side caching

B2B Java Stack

Frontend

• Framework :
  • Spring Boot 3.3+ (Spring MVC classique pour l'e-commerce)
  • Spring Security
  • Spring Data JPA
• Validation: Jakarta Validation (Bean Validation)
• Mapping: MapStruct

Backend

• JDK: Eclipse Temurin 21 LTS (OpenJDK)
• Build: Gradle (Kotlin DSL) + Version Catalogs
• Auth: JWT (stateless); Keycloak (optional) for advanced SSO/RBAC
• Payments (sandbox): Stripe test mode
• Mail: MailHog (dev)

Database

• DB: PostgreSQL (OLTP), Redis (sessions/cart/cache)
• Migrations: Flyway

Tests & Quality

• Tests: JUnit 5, Testcontainers (Postgres, Redis, Keycloak), REST-assured, WireMock
• Quality: Spotless (format), Checkstyle/ErrorProne (optional), OWASP Dependency Check

DevOps

• Observability: Micrometer + Prometheus + OpenTelemetry (traces), Logback JSON
• Packaging: Jib (build Docker images without a Dockerfile)
• Messaging (optional): RabbitMQ (orders/returns), or Kafka/Redpanda for event-driven
• Search (optional): Meilisearch (facets/typo tolerance) or OpenSearch
• File storage: MinIO (S3-compatible)

B2C Architecture

Principles

• Clear separation:
  • Presentation
  • Application (use cases)
  • Domain (model)
  • Infrastructure (adapters)
• Functional domains:
  • Discovery (home, categories, search)
  • Catalog & Product
  • Cart
  • Checkout
  • Account & Addresses
  • Orders
  • Reviews
  • CMS content
• Extensibility: extension points to become a marketplace (multi-seller) without breaking B2C.

Layers

• Presentation: SPA/SSR (Web), public/private routes, i18n & a11y, minimal local UI state.
• Application (use cases): business orchestration (e.g., AddItemToCart, PlaceOrder, SubmitReview).
• Domain: entities and rules (Product, Price, Cart, Order, Customer, Address, Review).
• Infrastructure: persistence (DB), cache, files (images), messaging, search engines, payment/shipping gateways.

Contexts & boundaries

• Discovery: list pages, search, facets → reads from Catalog and Search.
• Catalog & Product: optimized read, variants/attributes, indicative availability.
• Cart: Cart aggregate (lines, quantity, totals) — tolerant to temporary inconsistencies (price/stock revalidated at checkout).
• Checkout: address validation, shipping fees, taxes, payment → order created (idempotency).
• Account: profile, addresses, preferences.
• Orders: status tracking; timeline-oriented read (events).
• Reviews: creation/moderation; aggregated calculations on read.
• CMS: legal/FAQ pages; agnostic to core e-commerce.

Major flows

• Purchase journey: Discovery → Product → Cart → Checkout → Confirmation → Order tracking.
• Price/stock sync: “best-effort” read in catalog, strict re-validation at payment.
• Reviews: after delivery → creation → moderation → publication.

API & BFF

• Resource-centric public API (REST):
  • GET /products
  • POST /cart/items
  • POST /orders
  • GET /orders/{id}
• BFF (optional) to aggregate multi-source data and tailor to front needs (anti-corruption layer to B2B/third parties).

Data & read/write

• Strict writes (local transactions) for cart/order/account.
• Optimized reads: pagination, sorting, facets, “product card” projections.
• Cache: CDN/images, app cache (catalog), ETags/If-None-Match for lists.

Security & compliance

• Customer auth (session/JWT), simple RBAC (USER/ADMIN).
• Protect critical actions (checkout): idempotency key, rate limiting, strong validation.
• GDPR: data minimization, account export/deletion, cookie consent.

Observability

• Product metrics (views, cart→order conversion)
• Correlated logs (traceId)
• Basic alerts (payment failure rate)
• Multi-channel
• Web-first, ready for mobile / PWA (offline cart), and for a showcase channel (affiliates/embeds) via secure read API.

Technical architecture

• Front: choose SSR/CSR (SEO vs speed), routing by functional domains.
• Back: REST API with a clear application layer, documented contracts (OpenAPI).
• Search: dedicated index (facets/typo tolerance) for discovery.
• Files: object storage (product images), async derivatives (thumbnails).
• Messaging (optional): OrderPlaced, ReviewSubmitted events for analytics and emails.

Infrastructure

• Dev: dockerized environment (DB, cache, mail, search).
• Prod: immutable images, secret variables, DB backups, media CDN.
• Scalability: horizontal reads (catalog/search), protected writes (checkout), queues for non-critical jobs.

B2B Architecture

Principles

• Marketplace centric: the customer buys from multiple sellers through a unified experience.
• Separation of responsibilities:
  • Seller portal (operations)
  • Admin portal (governance)
  • Restricted public API
• Bounded contexts:
  • Seller
  • Seller Catalog
  • Orders & Fulfillment
  • Returns/RMA
  • Payouts & Settlement
  • Support
• Local consistency, event-based coordination:
  • Per-context transactions
  • Saga orchestration for cross-flows (order → shipment → payout).
• Multi-tenant: strict data isolation by sellerId (access policies + data segmentation).

Layers

• Presentation: Seller portal (storefront, products, orders), Admin (validation, moderation, finance).
• Application (use cases): per-context orchestration rules (e.g., SubmitProductForReview, AcceptOrder, MarkAsShipped, CreatePayout).
• Domain: stable aggregates (Seller, Product, Order, RMA, Payout) and invariants (commissions, statuses).
• Infrastructure: persistence, search index, file storage, event messaging, payment/logistics integrations.

Contexts & boundaries

• Seller: onboarding, status (PENDING/ACTIVE/SUSPENDED), team & roles, storefront/policies.
• Seller Catalog: products, variants, pricing, inventory; workflow Draft → Review → Published (moderation).
• Orders & Fulfillment: orders “split” per seller, preparation, shipping (tracking), disputes.
• Returns/RMA: requests, approval, receipt, refund, stock reintegration.
• Payouts & Settlement: commission calculation, period close, payout, supporting documents.
• Support: tickets, messages, SLAs, admin escalation.

Major flows

• Seller onboarding: registration → checks → activation → default commission plan assigned.
• Product publication: draft creation → submission → admin validation → publication & search indexing.
• Multi-seller order: customer order → split by seller → acceptance → preparation → shipping → completion.
• Return & refund: customer request → approval → receipt → refund → order & stock update.
• Payouts: period close → commission calculation → payout generation → payment → settlement report.

API & Portals

• Seller API (authenticated): limited to the seller’s perimeter (products, orders, returns, stats).
• Admin API: seller/product validation, moderation, finance.
• Public API: “marketplace showcase” read (published products, visible sellers) — no sensitive data.
• BFF (optional): multi-source data adaptation for portals.

Data & multi-tenant

• Ownership by context: a seller owns their catalog and their “seller share” of orders.
• Isolation: sellerId key everywhere (indexing, access filters), correlated logs/audits.
• Optimized reads: projections for lists (products, orders) and dashboards.

Security & compliance

• RBAC/ABAC:
  • roles per seller (admin/agent),
  • marketplace roles (market_admin/support);
  • policies “resource.sellerId == principal.sellerId”.
• Auditability: log sensitive actions (publication, refund, payout).
• Protection: idempotency keys (payment/refund), rate limits, strong validation.
• GDPR: minimization on the seller side (customer data limited to the strictly necessary).

Observability & SLAs

• Key metrics:
  • Order acceptance rate,
  • Preparation/shipping lead times,
  • Return rate,
  • Payout delay.
• Traceability: cross-context correlation (traceId), per-seller and global marketplace dashboards.

Extensibility & integrations

• Modular integrations: payments, carriers, search, KYC — swappable via adapters.
• Evolution:
  • Add multi-brand per seller,
  • Enterprise quotes/POs,
  • Seller webhooks API without breaking the core.

Technical architecture

• Dedicated portals (Seller/Admin) separated from B2C front; documented API contracts.
• Search index for seller catalogs & filters.
• Event messaging for sagas (order, return, payout).
• Object storage for product media & attachments (RMA, supporting docs).

Infrastructure

• Dev: context-isolated environments (DB, cache, mail, search).
• Prod: per-seller access policies, backups/legal archiving, tamper-proof audit logs.
• Scalability: horizontal scaling for portals & reads, queues for long-running jobs (exports, indexing).

Backlog

Click the story number to open GitHub.
Click the status to view the demo when available.

B2C MVP

B2B MVP