DASHBOARD_ARCHITECTURE.md

# Dashboard Module - Architecture Overview

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Mobile App                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ React Native │  │   Flutter    │  │   iOS/Android│          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                  │                  │                   │
│         └──────────────────┴──────────────────┘                  │
│                            │                                      │
│                   Local Cache (30s)                              │
│                            │                                      │
└────────────────────────────┼──────────────────────────────────────┘
                             │
                    HTTPS + JWT Token
                             │
┌────────────────────────────▼──────────────────────────────────────┐
│                      API Gateway / Load Balancer                  │
└────────────────────────────┬──────────────────────────────────────┘
                             │
┌────────────────────────────▼──────────────────────────────────────┐
│                    FastAPI Application                            │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Dashboard Router (/api/v1/dashboard/*)                   │   │
│  │  - GET /summary                                            │   │
│  │  - POST /refresh                                           │   │
│  │  - GET /bookings/stats                                     │   │
│  │  - GET /earnings/stats                                     │   │
│  └────────────────┬─────────────────────────────────────────┘   │
│                   │                                               │
│  ┌────────────────▼─────────────────────────────────────────┐   │
│  │  JWT Authentication Middleware                            │   │
│  │  - Verify token                                            │   │
│  │  - Extract partner_id                                      │   │
│  └────────────────┬─────────────────────────────────────────┘   │
│                   │                                               │
│  ┌────────────────▼─────────────────────────────────────────┐   │
│  │  Dashboard Service                                         │   │
│  │  - get_summary() - Orchestrates all queries               │   │
│  │  - Parallel async execution                               │   │
│  └────────────────┬─────────────────────────────────────────┘   │
│                   │                                               │
└───────────────────┼───────────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐    ┌────────▼────────┐
│  Redis Cache   │    │   PostgreSQL    │
│  (60s TTL)     │    │   Database      │
│                │    │                 │
│  Cache Key:    │    │  Tables:        │
│  dashboard:    │    │  - orders       │
│  summary:      │    │  - wallets      │
│  {partner_id}  │    │  - transactions │
└────────────────┘    └─────────────────┘
```

## Request Flow

### 1. Cache Hit Scenario (95% of requests)

```
Mobile App
    │
    │ 1. GET /dashboard/summary
    │    Authorization: Bearer <token>
    ▼
FastAPI Router
    │
    │ 2. Verify JWT token
    │    Extract partner_id
    ▼
Cache Check
    │
    │ 3. Check Redis
    │    Key: dashboard:summary:{partner_id}
    ▼
Redis Cache
    │
    │ 4. Cache HIT! ✓
    │    Return cached data
    ▼
FastAPI Router
    │
    │ 5. Return JSON response
    │    Time: ~10-20ms
    ▼
Mobile App
    │
    │ 6. Display dashboard
    └─── Done!
```

### 2. Cache Miss Scenario (5% of requests)

```
Mobile App
    │
    │ 1. GET /dashboard/summary
    ▼
FastAPI Router
    │
    │ 2. Verify JWT, extract partner_id
    ▼
Cache Check
    │
    │ 3. Check Redis - MISS ✗
    ▼
Dashboard Service
    │
    │ 4. Execute parallel queries:
    │    ┌─────────────────────────┐
    │    │ Query 1: Booking Stats  │──┐
    │    │ Query 2: Earnings Stats │──┤
    │    │ Query 3: Rating Stats   │──┤ Parallel
    │    │ Query 4: Upcoming Apts  │──┤ Execution
    │    │ Query 5: Recent Ratings │──┤ (asyncio.gather)
    │    │ Query 6: Special Offers │──┘
    │    └─────────────────────────┘
    ▼
PostgreSQL Database
    │
    │ 5. Execute queries with indexes
    │    Time: ~50-100ms total
    ▼
Dashboard Service
    │
    │ 6. Aggregate results
    │    Build DashboardSummary object
    ▼
Redis Cache
    │
    │ 7. Cache result (60s TTL)
    │    Key: dashboard:summary:{partner_id}
    ▼
FastAPI Router
    │
    │ 8. Return JSON response
    │    Time: ~100-200ms
    ▼
Mobile App
    │
    │ 9. Display dashboard
    │    Cache locally (30s)
    └─── Done!
```

## Data Flow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                    Dashboard Summary                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────┐ │
│  │ Booking Stats  │  │ Earnings Stats │  │ Rating Stats │ │
│  ├────────────────┤  ├────────────────┤  ├──────────────┤ │
│  │ Total: 150     │  │ Total: ₹125K   │  │ Avg: 4.5/5   │ │
│  │ Confirmed: 45  │  │ Month: ₹15K    │  │ Total: 120   │ │
│  │ Completed: 95  │  │ Pending: ₹2.5K │  │ 5★: 80       │ │
│  │ Cancelled: 8   │  │ Wallet: ₹8.5K  │  │ 4★: 30       │ │
│  │ Pending: 2     │  │                │  │ 3★: 8        │ │
│  └────────────────┘  └────────────────┘  └──────────────┘ │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Upcoming Appointments (5 max)                        │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ • SPA-2024-001 | ₹2,500 | Approved | Jan 20, 2PM    │  │
│  │ • SPA-2024-002 | ₹3,200 | Packed   | Jan 21, 10AM   │  │
│  │ • SPA-2024-003 | ₹1,800 | Approved | Jan 22, 3PM    │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Recent Ratings (5 max)                               │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ • Jane Smith | 5★ | "Excellent!" | Jan 15           │  │
│  │ • John Doe   | 4★ | "Good work"  | Jan 14           │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Special Offers                                       │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │ • 20% off on spa packages | Valid until Jan 31      │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Database Query Strategy

### Booking Statistics Query
```sql
SELECT 
    COUNT(*) as total,
    SUM(CASE WHEN order_status = 'approved' THEN 1 ELSE 0 END) as confirmed,
    SUM(CASE WHEN order_status = 'delivered' THEN 1 ELSE 0 END) as completed,
    SUM(CASE WHEN order_status = 'cancelled' THEN 1 ELSE 0 END) as cancelled,
    SUM(CASE WHEN order_status IN ('draft', 'placed') THEN 1 ELSE 0 END) as pending
FROM trans.spa_partner_orders
WHERE partner_id = :partner_id;

-- Uses index: idx_spa_orders_partner_status
-- Execution time: ~10-20ms
```

### Earnings Statistics Query
```sql
-- Query 1: Order earnings
SELECT 
    COALESCE(SUM(CASE WHEN order_status = 'delivered' THEN net_amount ELSE 0 END), 0) as total,
    COALESCE(SUM(CASE WHEN order_status = 'delivered' AND created_at >= :month_start THEN net_amount ELSE 0 END), 0) as current_month,
    COALESCE(SUM(CASE WHEN order_status IN ('approved', 'packed', 'dispatched') AND payment_status != 'paid' THEN net_amount ELSE 0 END), 0) as pending
FROM trans.spa_partner_orders
WHERE partner_id = :partner_id;

-- Query 2: Wallet balance
SELECT encrypted_balance 
FROM trans.spa_wallets 
WHERE partner_id = :partner_id;

-- Uses indexes: idx_spa_orders_partner_status, idx_spa_wallets_partner
-- Execution time: ~20-30ms (parallel)
```

### Upcoming Appointments Query
```sql
SELECT order_id, order_number, net_amount, order_status, created_at
FROM trans.spa_partner_orders
WHERE partner_id = :partner_id
    AND order_status IN ('approved', 'packed', 'dispatched')
ORDER BY created_at DESC
LIMIT 5;

-- Uses index: idx_spa_orders_partner_status_created
-- Execution time: ~5-10ms
```

## Caching Strategy

### Cache Layers

```
┌─────────────────────────────────────────────────────────┐
│ Layer 1: Client-Side Cache (Mobile App)                 │
│ - Duration: 30 seconds                                   │
│ - Storage: AsyncStorage / SharedPreferences             │
│ - Benefit: Instant load, offline support                │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│ Layer 2: Server-Side Cache (Redis)                      │
│ - Duration: 60 seconds                                   │
│ - Storage: Redis in-memory                              │
│ - Benefit: Fast API response, reduced DB load           │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│ Layer 3: Database (PostgreSQL)                          │
│ - Duration: Permanent                                    │
│ - Storage: Disk with indexes                            │
│ - Benefit: Source of truth, complex queries             │
└─────────────────────────────────────────────────────────┘
```

### Cache Invalidation

```
Event Occurs
    │
    │ (Order created, status changed, payment received, etc.)
    ▼
Application Code
    │
    │ 1. Perform operation
    │    (create order, update status, etc.)
    ▼
Cache Invalidation
    │
    │ 2. Call invalidate_dashboard_cache(partner_id)
    ▼
Redis
    │
    │ 3. DELETE dashboard:summary:{partner_id}
    ▼
Next Request
    │
    │ 4. Cache miss → Fetch fresh data
    │    5. Cache new data
    └─── Fresh data served
```

## Performance Characteristics

### Response Time Distribution

```
Without Caching:
├─ Database Query: 50-100ms (70%)
├─ Data Processing: 10-20ms  (15%)
├─ Network: 10-30ms          (15%)
└─ Total: 100-200ms

With Redis Cache:
├─ Cache Lookup: 1-5ms       (40%)
├─ Data Processing: 2-5ms    (20%)
├─ Network: 5-15ms           (40%)
└─ Total: 10-20ms

Improvement: 5-10x faster
```

### Scalability

```
Requests per Second (RPS) Capacity:

Without Caching:
├─ Single Server: ~50 RPS
├─ Bottleneck: Database
└─ Scaling: Vertical (bigger DB)

With Redis Caching (95% hit rate):
├─ Single Server: ~1000 RPS
├─ Bottleneck: Network/CPU
└─ Scaling: Horizontal (more servers)

Improvement: 20x capacity increase
```

## Error Handling Flow

```
Request Received
    │
    ▼
┌─────────────────┐
│ JWT Validation  │
└────┬────────────┘
     │
     ├─ Invalid Token → 401 Unauthorized
     │
     ▼
┌─────────────────┐
│ Cache Check     │
└────┬────────────┘
     │
     ├─ Cache Error → Log warning, continue to DB
     │
     ▼
┌─────────────────┐
│ Database Query  │
└────┬────────────┘
     │
     ├─ DB Error → Return empty dashboard with error flag
     │
     ▼
┌─────────────────┐
│ Response        │
└─────────────────┘
```

## Monitoring Points

```
┌──────────────────────────────────────────────────────────┐
│ Metrics Collection Points                                 │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  1. API Gateway                                           │
│     - Request count                                       │
│     - Response time                                       │
│     - Error rate                                          │
│                                                           │
│  2. Application                                           │
│     - Cache hit/miss rate                                 │
│     - Query execution time                                │
│     - Parallel query performance                          │
│                                                           │
│  3. Redis                                                 │
│     - Memory usage                                        │
│     - Eviction count                                      │
│     - Connection count                                    │
│                                                           │
│  4. PostgreSQL                                            │
│     - Query time                                          │
│     - Connection pool usage                               │
│     - Index usage                                         │
│                                                           │
└──────────────────────────────────────────────────────────┘
```

## Security Architecture

```
┌─────────────────────────────────────────────────────────┐
│ Security Layers                                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. Transport Layer                                      │
│     ✓ HTTPS/TLS encryption                              │
│     ✓ Certificate validation                            │
│                                                          │
│  2. Authentication Layer                                 │
│     ✓ JWT token validation                              │
│     ✓ Token expiry check                                │
│     ✓ Signature verification                            │
│                                                          │
│  3. Authorization Layer                                  │
│     ✓ Partner ID extraction                             │
│     ✓ Data isolation (partner_id filter)                │
│     ✓ No cross-partner access                           │
│                                                          │
│  4. Data Layer                                           │
│     ✓ Encrypted wallet balance                          │
│     ✓ SQL injection prevention (ORM)                    │
│     ✓ Prepared statements                               │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

## Summary

The dashboard architecture is designed for:
- **Performance**: <100ms response time with caching
- **Scalability**: 1000+ RPS per server with Redis
- **Reliability**: Graceful degradation on errors
- **Security**: Multi-layer protection
- **Maintainability**: Clean separation of concerns