Capstone - System Architecture

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        CDN (CloudFlare)                         │
│                    Static Assets + DDoS Protection              │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────────────┐
│                      Load Balancer (AWS ALB)                     │
│                    SSL Termination + Rate Limiting               │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────────────┐
│                     Application Layer                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │ Web Node │  │ Web Node │  │ Web Node │  │ Web Node │       │
│  │    1     │  │    2     │  │    3     │  │    N     │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       └──────────────┼──────────────┼──────────────┘             │
│                      │              │                            │
│              ┌───────┴──────────────┴───────┐                   │
│              │      Magento 2 Application     │                   │
│              │  ┌──────────┐  ┌──────────┐   │                   │
│              │  │ PHP-FPM  │  │ Nginx    │   │                   │
│              │  └──────────┘  └──────────┘   │                   │
│              └───────────────────────────────┘                   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────────────┐
│                       Data Layer                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │    MySQL     │  │    Redis     │  │   Varnish    │          │
│  │   Primary    │  │   Cluster    │  │   Cache      │          │
│  │      +       │  │  (Sentinel)  │  │  (FPC)       │          │
│  │  2 Replicas  │  │              │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  OpenSearch  │  │  RabbitMQ    │  │    S3        │          │
│  │  (3 nodes)   │  │  (Cluster)   │  │  (Media)     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────────────┐
│                    External Services                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │  ERP     │  │ Payment  │  │ Shipping │  │ Email    │       │
│  │ (SAP)    │  │(Stripe)  │  │ (FedEx)  │  │ (SES)    │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└─────────────────────────────────────────────────────────────────┘

Technology Stack

Layer              │ Technology          │ Purpose
───────────────────┼─────────────────────┼─────────────────────────
Frontend           │ Hyvä Theme          │ Performance-optimized
Web Server         │ Nginx               │ Reverse proxy, static
Application        │ PHP 8.2 + PHP-FPM   │ Magento runtime
Cache (Page)       │ Varnish 7.x         │ Full page cache
Cache (Data)       │ Redis 7.x           │ Session, config, block
Search             │ OpenSearch 2.x      │ Catalog search
Queue              │ RabbitMQ 3.x        │ Async processing
Database           │ MySQL 8.0           │ Primary data store
Media Storage      │ AWS S3              │ Product images, assets
CDN                │ CloudFlare          │ Static assets, DDoS
Monitoring         │ Prometheus + Grafana│ Metrics and dashboards
Logging            │ ELK Stack           │ Centralized logging
CI/CD              │ GitHub Actions      │ Automated pipeline

Component Responsibilities

Component          │ Responsibility                    │ Scaling Strategy
───────────────────┼───────────────────────────────────┼──────────────────
Nginx              │ SSL, routing, static serving      │ Horizontal
PHP-FPM            │ Application logic                 │ Horizontal
Varnish            │ FPC, cache invalidation           │ Horizontal
Redis              │ Session, cache, locks             │ Cluster + Sentinel
MySQL              │ Data persistence                  │ Read replicas + Sharding
OpenSearch         │ Search indexing, queries           │ Add data nodes
RabbitMQ           │ Message queuing, consumers         │ Cluster mode
S3                 │ Media file storage                 │ Auto-scaled

Scalability Architecture

Vertical Scaling (Scale Up):
  MySQL: 8vCPU → 16vCPU → 32vCPU
  Redis: 16GB → 32GB → 64GB
  PHP-FPM: 4 workers → 16 workers

Horizontal Scaling (Scale Out):
  Web Nodes: 2 → 4 → 8 → 16
  Read Replicas: 1 → 2 → 3
  OpenSearch: 3 → 6 → 9 nodes
  RabbitMQ: 1 → 3 (cluster)

Auto-Scaling Triggers:
  CPU > 60% → Add web node
  Queue > 5000 → Add consumer
  DB Connections > 80% → Add replica
  Latency > 2s → Add node

ADR Template

# ADR-[Number]: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Date
[YYYY-MM-DD]

## Context
[What is the issue that we're seeing that motivates this decision?]

## Decision
[What is the change that we're proposing and/or doing?]

## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Drawback 1]
- [Drawback 2]

### Risks
- [Risk 1]
- [Risk 2]

## Alternatives Considered
1. **[Alternative 1]** - [Why rejected]
2. **[Alternative 2]** - [Why rejected]
3. **[Alternative 3]** - [Why rejected]

## References
- [Link to relevant docs]

Key ADRs

# ADR-001: Use Hyvä Theme

## Status
Accepted

## Context
We need a performant frontend theme that improves Core Web Vitals while maintaining Magento compatibility.

## Decision
We will use Hyvä theme instead of Luma or custom React storefront.

## Consequences
### Positive
- 90%+ Lighthouse scores out of the box
- Compatible with most Magento extensions
- Reduced JavaScript bundle size
- Better mobile performance

### Negative
- Requires Hyvä-compatible extensions
- Learning curve for Tailwind CSS
- Some extensions may need compatibility modules

## Alternatives Considered
1. **Luma Theme** - Rejected: Poor performance, heavy JS
2. **PWA Studio** - Rejected: Limited extension compatibility
3. **React Storefront** - Rejected: Higher development cost

---

# ADR-002: Use Message Queues for Order Processing

## Status
Accepted

## Context
During flash sales, order processing can bottleneck synchronous requests, causing timeouts and failed orders.

## Decision
We will use RabbitMQ with Magento's message queue framework for async order processing.

## Consequences
### Positive
- Non-blocking order placement
- Better fault tolerance
- Scalable consumer count
- Retry capability

### Negative
- Eventual consistency
- Additional infrastructure complexity
- Harder debugging

## Alternatives Considered
1. **Synchronous processing** - Rejected: Performance bottleneck
2. **Database polling** - Rejected: Scalability limitations
3. **Redis queues** - Rejected: No persistence guarantees

Trade-off Analysis Framework

## Trade-off Matrix

| Approach          | Performance | Scalability | Complexity | Cost  | Maintainability |
|-------------------|-------------|-------------|------------|-------|------------------|
| Monolith          | Medium      | Low         | Low        | Low   | High             |
| Microservices     | High        | High        | High       | High  | Medium           |
| Modular Monolith  | High        | Medium      | Medium     | Medium| High             |
| Headless          | Very High   | Very High   | Very High  | High  | Medium           |

## Decision: Modular Monolith

### Why?
- Balance of performance and maintainability
- Lower operational complexity than microservices
- Can evolve to microservices if needed
- Better team productivity

### Implementation
- Domain-driven module boundaries
- Service contracts for inter-module communication
- Event-driven loose coupling
- Independent deployment per module

Database Design

-- Core Schema Design

-- Product Catalog
CREATE TABLE catalog_product_entity (
    entity_id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    attribute_set_id INT UNSIGNED NOT NULL DEFAULT 4,
    type_id VARCHAR(32) NOT NULL DEFAULT 'simple',
    sku VARCHAR(64) NOT NULL,
    has_options SMALLINT NOT NULL DEFAULT 0,
    required_options SMALLINT NOT NULL DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY UK_SKU (sku),
    INDEX IDX_ATTR_SET (attribute_set_id),
    INDEX IDX_TYPE (type_id)
) ENGINE=innodb DEFAULT CHARSET=utf8mb4;

-- Custom Module: Warranty
CREATE TABLE vendor_warranty (
    entity_id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    order_increment_id VARCHAR(32) NOT NULL,
    product_sku VARCHAR(64) NOT NULL,
    customer_email VARCHAR(255) NOT NULL,
    customer_id INT UNSIGNED NULL,
    status ENUM('active','expired','claimed') NOT NULL DEFAULT 'active',
    expiry_date DATE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX IDX_ORDER (order_increment_id),
    INDEX IDX_SKU (product_sku),
    INDEX IDX_CUSTOMER (customer_id),
    INDEX IDX_STATUS (status),
    INDEX IDX_EXPIRY (expiry_date)
) ENGINE=innodb DEFAULT CHARSET=utf8mb4;

-- Inventory Sync Log
CREATE TABLE vendor_inventory_sync_log (
    log_id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    source_code VARCHAR(64) NOT NULL,
    sku VARCHAR(64) NOT NULL,
    quantity DECIMAL(12,4) NOT NULL,
    status ENUM('success','failed','pending') NOT NULL,
    error_message TEXT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX IDX_SKU (sku),
    INDEX IDX_STATUS (status),
    INDEX IDX_CREATED (created_at)
) ENGINE=innodb DEFAULT CHARSET=utf8mb4;

Indexing Strategy

-- Performance Indexes

-- Product Search
CREATE FULLTEXT INDEX FT_SEARCH ON catalog_product_entity (sku);

-- Order Lookup
CREATE INDEX IDX_ORDER_DATE ON sales_order (created_at);
CREATE INDEX IDX_ORDER_STATUS ON sales_order (status);
CREATE INDEX IDX_ORDER_CUSTOMER ON sales_order (customer_id);

-- Inventory Queries
CREATE INDEX IDX_INV_SKU_SOURCE ON inventory_source_item (sku, source_code);
CREATE INDEX IDX_INV_STOCK ON inventory_source_item (stock_id, sku);

-- Search Log Analytics
CREATE INDEX IDX_SEARCH_LOG_QUERY ON catalogsearch_query (query_text);
CREATE INDEX IDX_SEARCH_LOG_DATE ON catalogsearch_query (created_at);

Connection Pooling

<?php
// app/etc/env.php database configuration
'db' => [
    'table_prefix' => '',
    'connection' => [
        'default' => [
            'host' => 'mysql-primary',
            'dbname' => 'magento2',
            'username' => 'magento',
            'password' => 'password',
            'model' => 'mysql4',
            'engine' => 'innodb',
            'initStatements' => 'SET NAMES utf8mb4',
            'driver_options' => [
                PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8mb4',
                PDO::MYSQL_ATTR_FOUND_ROWS => true,
                PDO::MYSQL_ATTR_LOCAL_INFILE => true,
            ],
        ],
        'slave' => [
            'host' => 'mysql-replica',
            'username' => 'magento_read',
            'password' => 'password',
        ],
    ],
],

Sharding Strategy

Horizontal Sharding (Future):
  Shard by: customer_id (last digit)
  Shard 0: customers 0, 10, 20...
  Shard 1: customers 1, 11, 21...
  ...
  Shard 9: customers 9, 19, 29...

Vertical Partitioning:
  Hot Data: Product names, prices, stock
  Warm Data: Descriptions, attributes
  Cold Data: Order history, logs

Read/Write Splitting:
  Write: Primary MySQL
  Read: 2-3 Read Replicas
  Analytics: Dedicated replica

Performance Budget

performance_budget:
  metrics:
    LCP: 2.5s
    FID: 100ms
    CLS: 0.1
    TTFB: 800ms
    Total_Weight: 500KB

  resource_budgets:
    HTML: 50KB
    CSS: 100KB
    JavaScript: 200KB
    Images: 150KB
    Fonts: 50KB

  page_load_targets:
    homepage: 2.0s
    category_page: 2.5s
    product_page: 3.0s
    search_results: 2.5s
    checkout: 3.0s

Caching Architecture

Cache Hierarchy:

Browser Cache:
  Static assets: 1 year
  HTML: No-cache (dynamic)

CDN (CloudFlare):
  Static assets: 7 days
  API responses: 5 minutes

Varnish (FPC):
  Product pages: 24 hours
  Category pages: 1 hour
  CMS pages: 24 hours
  Cart/Checkout: No-cache

Redis:
  Session: 24 hours
  Config: Permanent
  Block cache: 1 hour
  Full page cache: 1 hour
  Search results: 5 minutes

MySQL Query Cache:
  Disabled (MySQL 8.0)
  Use Redis for query caching

Security Architecture

Security Layers:

1. Network Security:
   - WAF (CloudFlare)
   - DDoS protection
   - Rate limiting
   - IP whitelisting for admin

2. Application Security:
   - CSRF tokens on all forms
   - XSS prevention (output escaping)
   - SQL injection prevention (prepared statements)
   - Content Security Policy headers
   - HTTP Strict Transport Security

3. Authentication:
   - Admin: 2FA + IP restriction
   - API: OAuth 2.0 / Bearer tokens
   - Customer: Email + password + optional 2FA

4. Data Security:
   - Encryption at rest (AES-256)
   - Encryption in transit (TLS 1.3)
   - PCI DSS compliance for payments
   - GDPR compliance for customer data

5. Monitoring:
   - Security event logging
   - Intrusion detection
n   - Vulnerability scanning
   - Penetration testing

Monitoring Architecture

monitoring_stack:
  metrics:
    tool: Prometheus
    retention: 30 days
    scrape_interval: 15s
    alerts:
      - name: HighErrorRate
        threshold: >1%
      - name: HighLatency
        threshold: >2s
      - name: LowCacheHitRate
        threshold: <70%

  visualization:
    tool: Grafana
    dashboards:
      - name: Application Overview
      - name: Database Performance
      - name: Cache Statistics
      - name: Queue Monitoring

  logging:
    tool: ELK Stack
    retention: 90 days
    levels: [error, warning, info]
    structured: true

  tracing:
    tool: Jaeger
    sample_rate: 0.1%
    services: [web, api, queue]

Disaster Recovery

## DR Plan

### RPO (Recovery Point Objective): 1 hour
- Database backups every hour
- Binary logs streamed to S3
- Redis AOF persistence

### RTO (Recovery Time Objective): 30 minutes
- Automated failover for MySQL (Orchestrator)
- Redis Sentinel automatic failover
- Load balancer health checks every 30s

### Backup Strategy
- Full backup: Daily at 2 AM
- Incremental: Every hour
- WAL/Binlog: Continuous streaming
- Retention: 30 days local, 1 year S3

### Failover Procedure
1. Detect failure (health check fail)
2. Alert on-call engineer
3. Promote read replica to primary
4. Update DNS/connection strings
5. Verify application functionality
6. Investigate root cause
7. Rebuild failed component