System Architecture Diagram

# E-Commerce Platform Architecture

**System Design Document v2.0**

*Last Updated: November 2, 2024*

---

## Overview

This document describes the high-level architecture of our e-commerce platform, built to handle 100,000+ concurrent users with 99.99% uptime. The system uses a microservices architecture with event-driven communication.

## System Architecture

The following diagram illustrates the main components and their interactions:

```mermaid
graph TB
    Client[Web/Mobile Client]
    CDN[CDN - CloudFront]
    LB[Load Balancer]

    API[API Gateway]
    Auth[Authentication Service]

    Products[Product Service]
    Cart[Shopping Cart Service]
    Orders[Order Service]
    Payment[Payment Service]
    Inventory[Inventory Service]

    ProductDB[(Product DB<br/>PostgreSQL)]
    UserDB[(User DB<br/>PostgreSQL)]
    OrderDB[(Order DB<br/>PostgreSQL)]

    Redis[(Redis Cache)]
    Queue[Message Queue<br/>RabbitMQ]

    Search[Search Service<br/>Elasticsearch]
    Analytics[Analytics Service]

    Client --> CDN
    CDN --> LB
    LB --> API

    API --> Auth
    API --> Products
    API --> Cart
    API --> Orders
    API --> Search

    Auth --> UserDB
    Products --> ProductDB
    Products --> Redis
    Cart --> Redis
    Orders --> OrderDB
    Orders --> Queue

    Queue --> Payment
    Queue --> Inventory
    Queue --> Analytics

    Payment --> OrderDB
    Inventory --> ProductDB

    Products --> Search

    style Client fill:#e1f5ff
    style API fill:#fff4e1
    style Auth fill:#ffe1e1
    style Queue fill:#e1ffe1
    style Redis fill:#ffe1f5
```

## User Registration Flow

The following sequence diagram shows how new users register in the system:

```mermaid
sequenceDiagram
    participant User
    participant Client
    participant API
    participant Auth
    participant DB
    participant Email

    User->>Client: Fill registration form
    Client->>API: POST /api/auth/register
    API->>Auth: Validate & create user

    Auth->>DB: Check if email exists
    DB-->>Auth: Email available

    Auth->>Auth: Hash password
    Auth->>DB: INSERT user record
    DB-->>Auth: User created (ID: 12345)

    Auth->>Email: Send verification email
    Email-->>User: Welcome email with link

    Auth-->>API: Return JWT token
    API-->>Client: 201 Created + token
    Client-->>User: Show success message

    Note over User,Email: User is now registered<br/>but not verified
```

## Order Processing State Machine

Orders go through multiple states from creation to fulfillment:

```mermaid
stateDiagram-v2
    [*] --> Created: User places order

    Created --> PaymentPending: Initialize payment
    PaymentPending --> PaymentFailed: Payment declined
    PaymentPending --> Paid: Payment successful

    PaymentFailed --> Cancelled: Cancel order

    Paid --> Processing: Validate inventory
    Processing --> InventoryFailed: Out of stock
    Processing --> Confirmed: Items reserved

    InventoryFailed --> Refunded: Refund payment

    Confirmed --> Shipped: Items dispatched
    Shipped --> InTransit: Tracking active
    InTransit --> Delivered: Customer receives

    Delivered --> Completed: No issues
    Delivered --> ReturnRequested: Customer returns

    ReturnRequested --> Returned: Return processed
    Returned --> Refunded

    Cancelled --> [*]
    Refunded --> [*]
    Completed --> [*]

    note right of PaymentPending
        Timeout: 15 minutes
        Auto-cancel if not paid
    end note

    note right of Processing
        Inventory check
        Fraud detection
        Address validation
    end note
```

## Component Descriptions

### Frontend Layer

**Web Client (React)**
- Single-page application
- Server-side rendering for SEO
- Progressive web app capabilities
- Responsive design (mobile-first)

**Mobile App (React Native)**
- Native iOS and Android apps
- Offline shopping cart
- Push notifications
- Biometric authentication

### API Layer

**API Gateway (Kong)**
- Rate limiting: 1000 req/min per user
- Authentication via JWT
- Request routing and transformation
- Circuit breaker pattern

**Authentication Service**
- JWT token generation and validation
- OAuth 2.0 support (Google, Facebook)
- Two-factor authentication
- Session management

### Core Services

**Product Service**
- Product catalog management
- Category and tag management
- Price and promotion engine
- Inventory integration
- Caching layer (Redis)

**Shopping Cart Service**
- Stateless cart (Redis-backed)
- Cart persistence across devices
- Abandoned cart recovery
- Real-time price updates

**Order Service**
- Order creation and management
- Order status tracking
- Invoice generation
- Shipping integration

**Payment Service**
- Multiple payment gateways (Stripe, PayPal)
- PCI DSS compliant
- Fraud detection
- Refund processing

**Inventory Service**
- Real-time stock tracking
- Warehouse management
- Stock reservation
- Low-stock alerts

### Data Layer

**PostgreSQL Databases**
- Separate DBs per service
- Master-replica replication
- Automated backups (hourly)
- Connection pooling (PgBouncer)

**Redis Cache**
- Product catalog caching
- Session storage
- Shopping cart data
- Rate limiting counters

**Elasticsearch**
- Product search (full-text)
- Autocomplete suggestions
- Faceted filtering
- Search analytics

### Message Queue

**RabbitMQ**
- Asynchronous order processing
- Email notifications
- Inventory updates
- Analytics events

## Deployment Architecture

The system runs on AWS with the following setup:

```mermaid
graph LR
    Internet((Internet))

    subgraph AWS Region: us-east-1
        subgraph VPC
            subgraph Public Subnets
                ALB[Application<br/>Load Balancer]
                NAT[NAT Gateway]
            end

            subgraph Private Subnets - AZ1
                API1[API Servers]
                App1[App Servers]
                Redis1[(Redis<br/>Primary)]
            end

            subgraph Private Subnets - AZ2
                API2[API Servers]
                App2[App Servers]
                Redis2[(Redis<br/>Replica)]
            end

            subgraph Data Layer
                RDS[(RDS PostgreSQL<br/>Multi-AZ)]
                ES[(ElastiCache<br/>Redis)]
            end
        end
    end

    S3[S3 Bucket<br/>Static Assets]
    CloudFront[CloudFront CDN]

    Internet --> CloudFront
    CloudFront --> S3
    CloudFront --> ALB

    ALB --> API1
    ALB --> API2

    API1 --> App1
    API2 --> App2

    App1 --> RDS
    App2 --> RDS

    App1 --> Redis1
    App2 --> Redis2

    Redis1 -.Replication.-> Redis2

    App1 --> NAT
    App2 --> NAT

    style Internet fill:#e1f5ff
    style CloudFront fill:#ff9999
    style S3 fill:#99ff99
    style RDS fill:#ffcc99
```

## Data Flow Example: Place Order

Here's how data flows when a user places an order:

1. **User clicks "Place Order"** → Client sends POST to API Gateway
2. **API Gateway** → Validates JWT, routes to Order Service
3. **Order Service** → Creates order record in database (status: CREATED)
4. **Order Service** → Publishes "OrderCreated" event to RabbitMQ
5. **Payment Service** (subscriber) → Processes payment via Stripe
6. **Payment Service** → Updates order (status: PAID) and publishes "PaymentCompleted"
7. **Inventory Service** (subscriber) → Reserves items, updates stock
8. **Inventory Service** → Publishes "InventoryReserved" event
9. **Order Service** → Updates order (status: CONFIRMED)
10. **Email Service** → Sends order confirmation to customer
11. **Analytics Service** → Records order event for reporting

## Scalability Features

### Horizontal Scaling
- All services are stateless (except databases)
- Auto-scaling groups based on CPU/memory
- Min: 2 instances per service
- Max: 20 instances per service

### Caching Strategy
- **L1 Cache:** In-memory (service-level)
- **L2 Cache:** Redis (shared)
- **L3 Cache:** CloudFront CDN
- Cache TTL: 5 minutes (products), 30 seconds (prices)

### Database Optimization
- Read replicas for reporting queries
- Materialized views for complex aggregations
- Partitioning for orders table (by month)
- Indexes on frequently queried columns

## Performance Targets

| Metric | Target | Current |
|--------|--------|---------|
| API Response Time (P95) | < 200ms | 145ms |
| API Response Time (P99) | < 500ms | 320ms |
| Database Query Time | < 50ms | 32ms |
| Cache Hit Rate | > 90% | 94% |
| Uptime | 99.99% | 99.97% |
| Concurrent Users | 100,000 | 85,000 |
| Orders per Second | 1,000 | 650 |

## Security Measures

- **Encryption:** TLS 1.3 for all traffic, AES-256 for data at rest
- **Authentication:** JWT with 1-hour expiry, refresh tokens
- **Authorization:** Role-based access control (RBAC)
- **Input Validation:** All inputs sanitized and validated
- **Rate Limiting:** Per-user and per-IP limits
- **DDoS Protection:** AWS Shield + CloudFlare
- **Security Scanning:** Automated vulnerability scans (weekly)
- **Penetration Testing:** Annual third-party audits

## Monitoring & Alerting

**Monitoring Stack:**
- CloudWatch for AWS metrics
- Prometheus for application metrics
- Grafana for dashboards
- ELK stack for log aggregation

**Alerts:**
- Error rate > 1% → PagerDuty alert
- Response time > 1s → Slack notification
- Database connections > 80% → Email alert
- Disk usage > 85% → PagerDuty alert

## Disaster Recovery

**Backup Strategy:**
- Database: Automated daily backups, 30-day retention
- Files: S3 versioning enabled, cross-region replication
- Configuration: GitOps with version control

**Recovery Objectives:**
- Recovery Time Objective (RTO): < 4 hours
- Recovery Point Objective (RPO): < 1 hour

## Future Improvements

1. **Kubernetes Migration** - Move from EC2 to EKS for better orchestration
2. **Service Mesh** - Implement Istio for advanced traffic management
3. **GraphQL API** - Add GraphQL layer for flexible queries
4. **Machine Learning** - Product recommendations and fraud detection
5. **Multi-Region** - Deploy to EU region for GDPR compliance

---

## Appendix

### Technology Stack

- **Frontend:** React 18, Next.js, TailwindCSS
- **Backend:** Node.js, Express, TypeScript
- **Databases:** PostgreSQL 15, Redis 7
- **Search:** Elasticsearch 8
- **Queue:** RabbitMQ 3.12
- **Infrastructure:** AWS, Terraform
- **CI/CD:** GitHub Actions, ArgoCD
- **Monitoring:** Prometheus, Grafana, ELK

### Team Contacts

- **Architecture:** arch-team@company.com
- **DevOps:** devops@company.com
- **Security:** security@company.com