ShopHub

Multi-Tenant Marketplace Architecture

Execution Profile: Containerized (ECS / Docker Compose)

Cost Guardrail:Disposable Staging · TTL Managed

Problem Statement & Investigation

Multi-vendor platforms require strict tenant data isolation, ACID compliance for financial checkout, and high-volume unconstrained query flexibility for product reviews and clickstream analytics.

Architectural Hypothesis

A polyglot persistence architecture combining PostgreSQL (for ACID transactions and multi-tenant catalog) with MongoDB (for dynamic telemetry and product attributes) provides the optimal balance between consistency and ingestion throughput.

System Runtime Flow

11. Ingress & Reverse Proxy

Requests are balanced across Docker containers with Traefik reverse proxy handling SSL termination and tenant host-header routing.

22. FastAPI Async Processing

Python 3.12 FastAPI ASGI workers handle asynchronous non-blocking I/O for concurrent database pooling.

33. Relational Storage

PostgreSQL manages tenant-partitioned tables, customer accounts, and Stripe transaction webhooks.

44. Document Telemetry

MongoDB stores flexible product variants, ratings, customer reviews, and unstructured audit trails.

Architecture Decision Records (ADRs)

ADR-001: Hybrid PostgreSQL + MongoDB PersistenceACCEPTED

Decision: Split database responsibilities: relational ACID data in PostgreSQL, unstructured attributes in MongoDB.

Alternatives Evaluated: Pure PostgreSQL with JSONB; Pure MongoDB; DynamoDB.

Consequences: Clean separation of concerns and optimized query indexing; requires managing dual database connection pools.

ADR-002: Asynchronous FastAPI ASGI over Flask/DjangoACCEPTED

Decision: Adopt FastAPI with SQLAlchemy 2.0 async engine.

Alternatives Evaluated: Django REST Framework, Flask, Go Gin.

Consequences: High concurrency handling with native Pydantic OpenAPI documentation generation.

Failure-Mode & Resilience Analysis

Scenario: Database Connection Pool Exhaustion

Observed Behavior: Surge of concurrent requests exceeds database max connections.

Architectural Mitigation: PgBouncer connection pooling and SQLAlchemy async session timeouts reject excess queues gracefully.

Scenario: Payment Webhook Re-delivery

Observed Behavior: Stripe retries webhook events up to 72 hours.

Architectural Mitigation: Webhook handler checks unique transaction event IDs in PostgreSQL before applying balance credits.

Key Engineering Takeaways

Schema-per-tenant works well up to ~50 tenants; beyond that, shared tables with tenant_id indexes are vastly more maintainable.
Async SQLAlchemy 2.0 provides substantial performance improvements over synchronous drivers under concurrent load.

Empirical Benchmarks

Throughput Capacity3,200 req/s

Benchmarked across 4 containerized FastAPI workers

Database p95 Read4.8ms

Tenant-indexed PostgreSQL catalog queries

Checkout Latency42ms

End-to-end checkout with Stripe sandbox transaction validation

Memory Footprint145MB

Base memory usage per FastAPI async worker container

Technology Primitives

frontend: React 18 + Vite + Tailwind
backend: FastAPI + SQLAlchemy
database: PostgreSQL + MongoDB
infra: Terraform + EC2 + Docker Compose

Architecture Tags

FastAPIReact 18PostgreSQLMongoDBStripeDockerTerraform

Security Notice

Public Live Demo · Detailed Architecture & Deploy Keys Secured. Operational lifecycle commands (Deploy, Scale, Destroy) and raw cloud credentials remain sealed in the private control plane.