LostFound Guard - High Level Design (HLD) Document

1. System Overview

LostFound Guard is a distributed, scalable, cloud-based platform designed to facilitate the recovery of lost items through NFC, QR codes, and numerical identification combined with an intelligent courier logistics network.

1.1 System Objectives

• Enable quick discovery and notification when items are lost
• Facilitate direct communication between finders and owners
• Provide integrated courier service for long-distance item recovery
• Process secure payments between stakeholders
• Maintain data integrity and user privacy

1.2 System Scope

• In Scope: Web app, mobile app, backend APIs, payment processing, courier integration
• Out of Scope: Physical product manufacturing, courier service operation, insurance

---

2. Architecture Overview

2.1 Multi-Tier Architecture

┌─────────────────────────────────────────────────────────────┐
│                     PRESENTATION LAYER                      │
│  ┌────────────────────┐  ┌────────────────────────────────┐│
│  │   Web Frontend     │  │     Mobile Frontend (iOS/AND)  ││
│  │  Next.js + React   │  │  React Native / Flutter        ││
│  │  - Dashboard       │  │  - QR Scanner                  ││
│  │  - Admin Panel     │  │  - NFC Tap                     ││
│  │  - Payments UI     │  │  - Real-time Chat              ││
│  └────────────────────┘  └────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              ↓ (REST/WebSocket)
┌─────────────────────────────────────────────────────────────┐
│                   API GATEWAY & LOAD BALANCER               │
│        (AWS API Gateway / Nginx with SSL/TLS)               │
│  - Rate limiting, Request validation, Logging               │
│  - Authentication routing, CORS handling                    │
└─────────────────────────────────────────────────────────────┘
                              ↓ (REST/gRPC)
┌─────────────────────────────────────────────────────────────┐
│                    BUSINESS LOGIC LAYER                     │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ Auth Service     │  │ Product Service              │   │
│  │ - JWT handling   │  │ - Registration               │   │
│  │ - Refresh tokens │  │ - QR/NFC generation          │   │
│  │ - OAuth flows    │  │ - Status tracking            │   │
│  │ - MFA            │  │ - Unique code generation     │   │
│  └──────────────────┘  └──────────────────────────────┘   │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ Recovery Service │  │ Messaging Service            │   │
│  │ - Discovery log  │  │ - WebSocket connections      │   │
│  │ - Status updates │  │ - Message persistence        │   │
│  │ - Notifications  │  │ - Real-time delivery         │   │
│  │ - Event handling │  │ - Typing indicators          │   │
│  └──────────────────┘  └──────────────────────────────┘   │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ Payment Service  │  │ Courier Service              │   │
│  │ - Payment init   │  │ - Partner integration        │   │
│  │ - Webhook verify │  │ - Shipment creation          │   │
│  │ - Settlement     │  │ - Tracking aggregation       │   │
│  │ - Refunds        │  │ - Cost calculation           │   │
│  └──────────────────┘  └──────────────────────────────┘   │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ User Service     │  │ Notification Service         │   │
│  │ - Profile mgmt   │  │ - Push notifications         │   │
│  │ - Preferences    │  │ - Email dispatch             │   │
│  │ - Verification   │  │ - SMS delivery               │   │
│  │ - Analytics      │  │ - Notification queue         │   │
│  └──────────────────┘  └──────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓ (SQL/Cache protocols)
┌─────────────────────────────────────────────────────────────┐
│                      DATA ACCESS LAYER                      │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ User Repository  │  │ Product Repository           │   │
│  │ - CRUD ops       │  │ - Query optimization         │   │
│  │ - Indexing       │  │ - Full-text search           │   │
│  │ - Caching        │  │ - Geospatial queries         │   │
│  └──────────────────┘  └──────────────────────────────┘   │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ Recovery Repo    │  │ Payment Repository           │   │
│  │ - Event logs     │  │ - Transaction tracking       │   │
│  │ - Status queries │  │ - Invoice generation         │   │
│  │ - Geolocation    │  │ - Audit trail                │   │
│  └──────────────────┘  └──────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    DATA PERSISTENCE LAYER                   │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ PostgreSQL DB    │  │ Redis Cache                  │   │
│  │ - Primary store  │  │ - Session store              │   │
│  │ - Transactions   │  │ - Rate limiting              │   │
│  │ - ACID ops       │  │ - Real-time subscriptions    │   │
│  │ - Backups        │  │ - Message queue              │   │
│  └──────────────────┘  └──────────────────────────────┘   │
│  ┌──────────────────┐  ┌──────────────────────────────┐   │
│  │ AWS S3 Storage   │  │ Elasticsearch (Optional)     │   │
│  │ - File uploads   │  │ - Search indexing            │   │
│  │ - QR images      │  │ - Analytics queries          │   │
│  │ - Backups        │  │ - Log aggregation            │   │
│  │ - CDN delivery   │  │ - Performance tracking       │   │
│  └──────────────────┘  └──────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

3. Component Design

3.1 Frontend Layer Components

Web Application (Next.js)

next-app/
├── app/
│   ├── (auth)/
│   │   ├── login/
│   │   ├── register/
│   │   └── forgot-password/
│   ├── (dashboard)/
│   │   ├── dashboard/
│   │   ├── products/
│   │   ├── recoveries/
│   │   ├── messages/
│   │   └── payments/
│   ├── (public)/
│   │   ├── found/[productId]/
│   │   ├── profile/[userId]/
│   │   └── about/
│   └── api/ (API routes)
├── components/
│   ├── Auth/
│   ├── Product/
│   ├── Recovery/
│   ├── Chat/
│   └── Payment/
├── lib/
│   ├── api-client/
│   ├── socket-client/
│   └── utils/
└── styles/
    └── globals.css (Tailwind)

Mobile Application (React Native)

mobile-app/
├── screens/
│   ├── Auth/ (Login, Register)
│   ├── Home/ (Dashboard, Products)
│   ├── Scanner/ (QR + NFC)
│   ├── Chat/ (Messaging)
│   └── Account/ (Profile)
├── components/
│   ├── QRScanner/
│   ├── NFCReader/
│   └── LocationShare/
├── services/
│   ├── api-service/
│   ├── socket-service/
│   └── camera-service/
└── store/ (Redux/Zustand)
    └── reducers/

3.2 Backend Layer Components

API Server (NestJS/Express)

backend/
├── src/
│   ├── modules/
│   │   ├── auth/
│   │   │   ├── auth.controller.ts
│   │   │   ├── auth.service.ts
│   │   │   ├── jwt.strategy.ts
│   │   │   └── auth.guard.ts
│   │   ├── products/
│   │   │   ├── products.controller.ts
│   │   │   ├── products.service.ts
│   │   │   ├── qr-generator.service.ts
│   │   │   └── nfc-handler.service.ts
│   │   ├── recovery/
│   │   │   ├── recovery.controller.ts
│   │   │   ├── recovery.service.ts
│   │   │   └── recovery.gateway.ts (WebSocket)
│   │   ├── messaging/
│   │   │   ├── messaging.gateway.ts
│   │   │   ├── messaging.service.ts
│   │   │   └── message.entity.ts
│   │   ├── payments/
│   │   │   ├── payments.controller.ts
│   │   │   ├── payments.service.ts
│   │   │   ├── stripe.provider.ts
│   │   │   └── webhook.handler.ts
│   │   ├── courier/
│   │   │   ├── courier.controller.ts
│   │   │   ├── courier.service.ts
│   │   │   └── courier-adapters/ (DHL, FedEx, etc.)
│   │   └── users/
│   │       ├── users.controller.ts
│   │       ├── users.service.ts
│   │       └── user.entity.ts
│   ├── common/
│   │   ├── filters/ (Exception handling)
│   │   ├── pipes/ (Validation)
│   │   ├── interceptors/ (Logging, Transform)
│   │   └── decorators/ (Custom)
│   ├── database/
│   │   ├── migrations/
│   │   ├── seeders/
│   │   └── entities/
│   ├── config/
│   │   ├── database.config.ts
│   │   ├── jwt.config.ts
│   │   └── payment.config.ts
│   └── main.ts
├── test/
└── docker/

3.3 Data Access Layer

Entities/Models

User
├─ id: UUID
├─ email: string (unique)
├─ phone: string
├─ password: hashed
├─ profile: JSON
├─ role: OWNER | FINDER | COURIER
├─ isVerified: boolean
├─ preferences: JSON
└─ timestamps

Product
├─ id: UUID
├─ ownerId: UUID (FK)
├─ type: CARD | STICKER
├─ itemDetails: JSON
├─ uniqueCode: string (unique)
├─ qrCodeImage: URL
├─ nfcChipId: string
├─ status: ACTIVE | LOST | RECOVERED | INACTIVE
└─ timestamps

Recovery
├─ id: UUID
├─ productId: UUID (FK)
├─ finderId: UUID (FK)
├─ ownerId: UUID (FK)
├─ foundLocation: GeoPoint
├─ recoveryType: DIRECT | COURIER
├─ status: PENDING | IN_PROGRESS | COMPLETED
└─ timestamps

Message
├─ id: UUID
├─ recoveryId: UUID (FK)
├─ senderId: UUID (FK)
├─ content: string
├─ type: TEXT | LOCATION | IMAGE
└─ timestamps

Shipment
├─ id: UUID
├─ recoveryId: UUID (FK)
├─ courierId: UUID (FK)
├─ trackingNumber: string
├─ status: PENDING | PICKED | SHIPPED | DELIVERED
└─ timestamps

Payment
├─ id: UUID
├─ recoveryId: UUID (FK)
├─ fromUser: UUID (FK)
├─ toUser: UUID (FK)
├─ amount: decimal
├─ status: PENDING | SUCCESS | FAILED
└─ timestamps

---

4. Data Flow Diagrams

4.1 Product Registration Flow

START: User logs in
  ↓
User fills registration form
  ↓
SELECT Product Type (Card or Sticker)
  ↓
IF Card:
  ├─ Generate NFC payload
  ├─ Generate QR code
  └─ Generate 8-digit code
    ↓
IF Sticker:
  └─ Generate QR code only
    ↓
Store product in Database
  ├─ PostgreSQL: Product record
  ├─ S3: QR image
  └─ Memory: Product ID
    ↓
Encode data to physical medium (Manufacturing)
  ├─ NFC card encoding (offline)
  ├─ Print QR code
  └─ Print 8-digit number
    ↓
Activate product (link physical to digital)
  ├─ Scan QR or tap NFC
  ├─ Confirm activation
  └─ Status: ACTIVE
    ↓
User receives product
  ├─ Email with instructions
  ├─ Push notification
  └─ Dashboard update
    ↓
END: Product ready for use

4.2 Discovery Flow (Item Found)

START: Finder discovers lost item
  ↓
CHOOSE Discovery Method:
  │
  ├─ Method 1: Tap NFC card with smartphone
  │   ├─ NFC API triggers
  │   ├─ Extract product ID from NFC payload
  │   └─ Jump to "Fetch Owner Details"
  │
  ├─ Method 2: Scan QR code with phone camera
  │   ├─ Open camera/QR app
  │   ├─ Extract product ID from QR data
  │   └─ Jump to "Fetch Owner Details"
  │
  └─ Method 3: Manual entry of 8-digit code
      ├─ Open app
      ├─ Navigate to "Enter Code"
      ├─ Input 8-digit number
      └─ Jump to "Fetch Owner Details"
        ↓
Fetch Owner Details
  ├─ Query product database
  ├─ Fetch owner profile
  ├─ Extract owner location (for show)
  └─ Check if owner notification enabled
        ↓
Send Notifications to Owner
  ├─ Push notification: "Your [item] was found!"
  ├─ Email notification
  ├─ SMS notification (if opted)
  └─ Create in-app notification
        ↓
Create Recovery Record
  ├─ Recovery ID generated
  ├─ Finder ID recorded
  ├─ Found location (GPS)
  ├─ Timestamp
  └─ Status: PENDING
        ↓
Display Finder Interface
  ├─ Show: "Item found! Tell the owner"
  ├─ Show owner's public profile
  ├─ Show message input
  ├─ Show location sharing option
  └─ Show courier option button
        ↓
Finder Sends Message
  ├─ "I found your [item] at [location]"
  ├─ Message stored in DB
  ├─ Owner gets notification
  └─ Owner sees message in app
        ↓
END: Recovery process initiated

4.3 Courier Service Flow

START: Finder decides to courier item
  ↓
SELECT: Courier service partner
  ├─ Auto-select nearest courier
  ├─ Show available courier options
  └─ Finder selects one
        ↓
Finder Provides Courier Details
  ├─ Item condition
  ├─ Item weight/dimensions
  ├─ Receiver's city
  └─ Estimated cost calculated
        ↓
Create Shipment Record
  ├─ Shipment ID generated
  ├─ Recovery linked to shipment
  ├─ Courier assignment
  ├─ Cost calculated from courier API
  └─ Status: PENDING_PICKUP
        ↓
Notify Owner
  ├─ "Your item can be couriered"
  ├─ Show cost breakdown:
  │   ├─ Courier fee: X
  │   ├─ Service fee: Y
  │   └─ Total: Z
  ├─ Owner accepts/declines
  └─ If accepts → Create payment intent
        ↓
Payment Processing
  ├─ Owner selects payment method
  ├─ Stripe/Razorpay payment form
  ├─ Process payment
  ├─ On success: Payment record created
  ├─ Notify finder: "Payment received!"
  └─ Generate shipment on courier API
        ↓
Courier Integration
  ├─ Call courier API
  ├─ Create shipment with:
  │   ├─ Pickup address (finder)
  │   ├─ Delivery address (owner)
  │   ├─ Item description
  │   └─ Weight/dimensions
  ├─ Receive tracking number
  └─ Store in database
        ↓
Update Status
  ├─ Recovery status: IN_PROGRESS
  ├─ Shipment status: CONFIRMED
  ├─ Notify all parties
  └─ Send tracking link
        ↓
Tracking Updates
  ├─ Courier webhook sends updates:
  │   ├─ Item picked up
  │   ├─ Item in transit
  │   └─ Item delivered
  ├─ Update shipment status
  ├─ Notify owner & finder
  └─ Update tracking page
        ↓
Delivery Confirmation
  ├─ Owner receives item
  ├─ Owner confirms delivery in app
  ├─ Recovery status: COMPLETED
  └─ Finder payment initiated
        ↓
Settlement
  ├─ Calculate finder reward:
  │   ├─ Courier fee minus service fee
  │   └─ Add optional owner reward
  ├─ Transfer to finder wallet
  ├─ Settlement notification sent
  └─ Invoice generated
        ↓
END: Recovery completed successfully

4.4 Real-time Messaging Flow

START: Recovery conversation initiated
  ↓
Client A initiates WebSocket connection
  ├─ Socket.io client connects
  ├─ Authentication with JWT
  ├─ Subscribe to recovery room
  └─ Send "joined" event
        ↓
Backend receives connection
  ├─ Validate token
  ├─ Check recovery permissions
  ├─ Load message history
  ├─ Emit history to client
  └─ Mark as CONNECTED
        ↓
Client A sends message
  ├─ "I found your bag at the hotel"
  ├─ Message with metadata:
  │   ├─ sender ID
  │   ├─ recovery ID
  │   ├─ timestamp
  │   ├─ location (optional)
  │   └─ image (optional)
  └─ Emit to backend via WebSocket
        ↓
Backend processes message
  ├─ Validate message
  ├─ Store in database (Messages table)
  ├─ Mark status: DELIVERED
  ├─ Emit to other clients in room
  ├─ Send push notification to recipient
  └─ Update last_message_at
        ↓
Client B receives message
  ├─ WebSocket emits new message event
  ├─ UI updates with message
  ├─ Show typing indicator cleared
  ├─ Play notification sound
  └─ Update conversation timestamp
        ↓
Client B sees typing indicator
  ├─ A types response message
  ├─ Client emits "typing" event
  ├─ Backend broadcasts typing event
  ├─ Client B shows "User typing..."
  └─ After 3s of no input → hide indicator
        ↓
Client B sends response message
  ├─ Same flow as Client A
  └─ Message stored and delivered
        ↓
Message acknowledgment
  ├─ Recipient client emits "message_read"
  ├─ Backend updates Message.read_at
  ├─ Both clients show read status
  └─ Update recovery conversation
        ↓
REPEAT: Until recovery is completed
  ↓
END: Conversation history saved

---

5. API Gateway Design

5.1 Request Flow Through API Gateway

Client Request
      ↓
┌─────────────────────────────┐
│ AWS API Gateway / Nginx     │
├─────────────────────────────┤
│ 1. HTTPS/TLS validation     │
│ 2. Request logging          │
│ 3. API key validation       │
│ 4. Rate limiting check      │
│ 5. CORS validation          │
│ 6. Request transformation   │
│ 7. Authentication check     │
└─────────────────────────────┘
      ↓
  Route to appropriate backend service
      ↓
┌─────────────────────────────┐
│ Load Balancer (ALB)         │
├─────────────────────────────┤
│ 1. Health check             │
│ 2. Connection pooling       │
│ 3. Sticky sessions          │
│ 4. SSL termination          │
└─────────────────────────────┘
      ↓
  Distribute to backend instances
      ↓
Backend Service Processing
      ↓
Response sent back through gateway
      ↓
┌─────────────────────────────┐
│ Response Processing         │
├─────────────────────────────┤
│ 1. Compression (gzip)       │
│ 2. Caching headers          │
│ 3. Security headers         │
│ 4. Response logging         │
└─────────────────────────────┘
      ↓
Response to Client

5.2 Rate Limiting Strategy

Endpoint: /api/products/by-code/:code

Rate Limits (per user):
├─ Authenticated user: 100 requests/minute
├─ Anonymous user: 10 requests/minute
└─ API key holder: 1000 requests/minute

Rate Limit Headers:
├─ X-RateLimit-Limit: 100
├─ X-RateLimit-Remaining: 95
├─ X-RateLimit-Reset: 1702000000
└─ Retry-After: 60

Storage: Redis
├─ Key: ratelimit:user:{userId}:{endpoint}
├─ Value: request_count
└─ TTL: 60 seconds

Throttling Algorithm: Token Bucket
├─ Initial tokens: Rate limit per minute
├─ Add tokens: 1 per second
├─ Request cost: 1 token
└─ Reject if: tokens < 1

---

6. Security Architecture

6.1 Authentication Flow

User Login Flow:
  ↓
POST /auth/login
├─ Email & password
├─ Validate credentials
├─ Generate JWT tokens:
│   ├─ Access token (15 min expiry)
│   ├─ Refresh token (7 days expiry)
│   └─ ID token (with user claims)
├─ Store refresh token in Redis
├─ Return tokens in response
└─ Set HTTPOnly cookie with refresh token
  ↓
Access protected resource:
  ├─ Send request with Authorization header
  ├─ Include: Bearer {accessToken}
  ├─ API validates JWT signature
  ├─ Extract user claims
  ├─ Verify token expiry
  └─ Grant access if valid
  ↓
Token expiry handling:
  ├─ If access token expires:
  │   ├─ Return 401 Unauthorized
  │   ├─ Client receives error
  │   └─ Client calls /auth/refresh-token
  │
  ├─ POST /auth/refresh-token
  │   ├─ Send refresh token
  │   ├─ Validate refresh token
  │   ├─ Generate new access token
  │   └─ Return new token
  │
  └─ Retry original request with new token

6.2 Data Encryption Strategy

At Rest:
├─ Database encryption (AWS RDS encryption)
├─ S3 bucket encryption (AES-256)
├─ Sensitive fields encrypted:
│   ├─ payment_methods (PCI compliance)
│   ├─ phone numbers (masked)
│   ├─ addresses (optional)
│   └─ sensitive user data
│
In Transit:
├─ TLS 1.3 for all communications
├─ HTTPS enforcement (HSTS)
├─ Certificate pinning (mobile apps)
├─ Signed API requests
│
In Memory:
├─ Secrets in environment variables
├─ Credentials in AWS Secrets Manager
├─ Payment tokens in Stripe Vault
└─ No logging of sensitive data

6.3 API Security

Request Validation:
├─ Schema validation (Zod/Joi)
├─ Input sanitization
├─ SQL injection prevention (parameterized queries)
├─ XSS prevention (Content Security Policy)
└─ CSRF protection (SameSite cookies)

Response Security:
├─ Security headers:
│   ├─ X-Frame-Options: DENY
│   ├─ X-Content-Type-Options: nosniff
│   ├─ Strict-Transport-Security: max-age=31536000
│   └─ Content-Security-Policy: ...
├─ PII redaction in logs
├─ Error message sanitization
└─ Sensitive data removal from responses

---

7. Scalability Considerations

7.1 Horizontal Scaling

Load Distribution:
├─ Multiple backend instances (Auto-scaling group)
├─ Stateless services (easy to scale)
├─ Sticky sessions via Redis
├─ Database connection pooling
└─ CDN for static assets

Auto-scaling Rules:
├─ Trigger 1: CPU > 70% → Add instance
├─ Trigger 2: Memory > 75% → Add instance
├─ Trigger 3: CPU < 30% → Remove instance
├─ Min instances: 2
├─ Max instances: 10
└─ Scale-down cooldown: 5 minutes

7.2 Database Optimization

Indexing Strategy:
├─ Primary key: id (automatic)
├─ Composite indexes:
│   ├─ (owner_id, status)
│   ├─ (finder_id, created_at)
│   ├─ (product_id, recovery_status)
│   └─ (user_id, created_at)
├─ Full-text search on product descriptions
└─ Geospatial index on found_location (PostGIS)

Query Optimization:
├─ Connection pooling (PgBouncer)
├─ Query caching (Redis)
├─ Lazy loading for related entities
├─ Pagination: 20 items per page
└─ Batch operations where possible

Partitioning Strategy:
├─ Partition Recoveries by year
├─ Partition Messages by recovery_id
├─ Archive old records to cold storage
└─ Keep hot data in SSD

7.3 Caching Strategy

Cache Layers:
├─ Application-level (Redis):
│   ├─ Product details: 1 hour TTL
│   ├─ User profiles: 2 hours TTL
│   ├─ Recovery status: 30 minutes TTL
│   └─ Geolocation results: 1 day TTL
│
├─ CDN-level (CloudFront):
│   ├─ Static assets: 30 days
│   ├─ API responses (public): 5 minutes
│   └─ QR images: 7 days
│
└─ Browser-level:
    ├─ Static JS/CSS: 30 days
    ├─ User data: No cache (private)
    └─ API responses: Vary based on endpoint

Cache Invalidation:
├─ TTL-based (automatic expiry)
├─ Event-based (on data change):
│   ├─ Product updated → Invalidate product cache
│   ├─ Recovery status changed → Invalidate recovery cache
│   └─ User profile updated → Invalidate user cache
└─ Manual invalidation (admin panel)

---

8. Monitoring & Observability

8.1 Metrics to Track

Application Metrics:
├─ Request count (by endpoint)
├─ Response time (p50, p95, p99)
├─ Error rate (5xx, 4xx)
├─ Database query time
├─ Cache hit/miss ratio
├─ WebSocket connections (active)
├─ Message throughput
└─ Payment success rate

Business Metrics:
├─ New user registrations
├─ Products registered (daily)
├─ Items found & reported (daily)
├─ Recovery success rate
├─ Courier shipments processed
├─ Total payment volume
├─ User retention rate
└─ Average resolution time

Infrastructure Metrics:
├─ CPU utilization
├─ Memory usage
├─ Disk I/O
├─ Network throughput
├─ Database connections
├─ Redis memory usage
└─ S3 storage usage

8.2 Alerting Rules

Alert: High Error Rate
├─ Condition: Error rate > 5% for 5 minutes
├─ Severity: CRITICAL
├─ Notify: On-call engineer + Slack

Alert: Database Connection Pool Exhausted
├─ Condition: Available connections < 10%
├─ Severity: HIGH
├─ Notify: Database team

Alert: Redis Memory Usage High
├─ Condition: Memory > 80% for 10 minutes
├─ Severity: WARNING
├─ Notify: Ops team

Alert: Payment Service Failure
├─ Condition: Stripe API errors > 10
├─ Severity: CRITICAL
├─ Notify: Payment team + CTO

8.3 Logging Strategy

Log Levels:
├─ ERROR: System errors, exceptions
├─ WARN: Degraded performance, retries
├─ INFO: User actions, state changes
├─ DEBUG: Detailed execution flow
└─ TRACE: Very detailed debugging

Log Structure (JSON):
{
  "timestamp": "2024-12-16T10:30:00Z",
  "level": "INFO",
  "service": "payment-service",
  "user_id": "user-123",
  "recovery_id": "rec-456",
  "action": "payment_processed",
  "amount": 500,
  "status": "SUCCESS",
  "duration_ms": 245,
  "trace_id": "trace-789"
}

Log Destinations:
├─ CloudWatch Logs (AWS)
├─ Elasticsearch (for analysis)
├─ S3 (long-term archival)
└─ DataDog (aggregation + alerts)

Log Retention:
├─ Hot logs: 30 days
├─ Warm logs: 90 days
├─ Cold logs: 1 year (S3)
└─ Audit logs: 3 years (compliance)

---

9. Deployment Architecture

9.1 Infrastructure as Code

Terraform/CloudFormation Structure:
├─ VPC & Networking
│   ├─ Public subnets (ALB)
│   ├─ Private subnets (Backend)
│   ├─ Database subnet group
│   └─ NAT gateways
│
├─ Compute
│   ├─ Auto Scaling Group (Backend)
│   ├─ EC2 instances (t3.large)
│   ├─ Security groups (inbound/outbound rules)
│   └─ IAM roles & policies
│
├─ Database
│   ├─ RDS PostgreSQL (Multi-AZ)
│   ├─ ElastiCache Redis
│   ├─ Database backups
│   └─ Parameter groups
│
├─ Storage
│   ├─ S3 buckets (versioning enabled)
│   ├─ CloudFront distribution
│   ├─ Lifecycle policies
│   └─ CORS configuration
│
├─ Network
│   ├─ Application Load Balancer
│   ├─ Target groups
│   ├─ SSL certificates
│   └─ DNS records
│
└─ Monitoring
    ├─ CloudWatch dashboards
    ├─ SNS topics for alerts
    ├─ CloudTrail logging
    └─ VPC Flow Logs

9.2 Deployment Pipeline

Git Push to main branch
     ↓
GitHub Actions workflow triggered
     ↓
├─ Step 1: Run tests
│   ├─ Unit tests (Jest)
│   ├─ Integration tests
│   └─ E2E tests
│        ↓ [FAIL → Notify & Stop]
│
├─ Step 2: Security scan
│   ├─ SAST (Snyk/SonarQube)
│   ├─ Dependency check
│   └─ OWASP scanning
│        ↓ [FAIL → Notify & Stop]
│
├─ Step 3: Build Docker image
│   ├─ Build backend image
│   ├─ Build frontend image
│   └─ Tag with commit SHA
│        ↓ [FAIL → Notify & Stop]
│
├─ Step 4: Push to ECR
│   ├─ AWS ECR authentication
│   ├─ Push backend image
│   └─ Push frontend image
│        ↓ [FAIL → Notify & Stop]
│
├─ Step 5: Deploy to staging
│   ├─ Update ECS task definition
│   ├─ Deploy new tasks
│   ├─ Wait for health checks
│   └─ Smoke tests
│        ↓ [FAIL → Rollback]
│
├─ Step 6: Run E2E tests on staging
│   ├─ User flows
│   ├─ Payment processing
│   └─ API endpoints
│        ↓ [FAIL → Notify & Stop]
│
└─ Step 7: Manual approval
    ├─ Review staging deployment
    ├─ Approve for production
    └─ Step 8: Deploy to production
        ├─ Blue-Green deployment
        ├─ Health check (5 min)
        ├─ Route traffic gradually
        └─ Full deployment
             ↓
        ├─ Production smoke tests
        ├─ Monitoring verification
        └─ Notify team: Deployment Success

---

10. Disaster Recovery & Business Continuity

10.1 Backup Strategy

Database Backups:
├─ Daily automated snapshots
├─ Retained for 30 days
├─ Multi-region replication
└─ Test restore monthly

Application Backups:
├─ Docker images tagged with version
├─ Infrastructure as Code versioned
├─ Configuration stored in AWS Secrets Manager
└─ Git history for code rollback

Data Backups:
├─ S3 bucket replication (cross-region)
├─ Versioning enabled
├─ Lifecycle policies (archive after 90 days)
└─ Compliance-level encryption

10.2 Recovery Procedures

Scenario 1: Database Failure
├─ Detect: CloudWatch alert
├─ Action 1: Promote read replica
├─ Action 2: Update connection strings
├─ Action 3: Verify application connectivity
├─ RTO: 5 minutes
└─ RPO: 1 minute (automated snapshots)

Scenario 2: Application Server Failure
├─ Detect: Health check failure
├─ Action 1: Auto Scaling Group replaces instance
├─ Action 2: Load Balancer routes traffic away
├─ RTO: <1 minute (automatic)
└─ RPO: N/A (stateless)

Scenario 3: Entire Region Failure
├─ Detect: Multiple infrastructure failures
├─ Action 1: Failover to secondary region
├─ Action 2: Update DNS records
├─ Action 3: Restore from backups
├─ RTO: 30 minutes
└─ RPO: 15 minutes

Scenario 4: Data Corruption
├─ Detect: Data integrity checks
├─ Action 1: Isolate affected data
├─ Action 2: Restore from point-in-time backup
├─ Action 3: Verify data integrity
├─ RTO: 1 hour
└─ RPO: Depends on backup frequency

---

11. Performance Benchmarks

11.1 API Response Times

GET /products/:id
├─ P50: 50ms
├─ P95: 150ms
└─ P99: 500ms

POST /discoveries
├─ P50: 200ms
├─ P95: 500ms
└─ P99: 1500ms

GET /recoveries
├─ P50: 300ms
├─ P95: 800ms
└─ P99: 2000ms (paginated)

POST /payments
├─ P50: 1000ms
├─ P95: 2000ms
└─ P99: 5000ms (includes Stripe API call)

11.2 Concurrent User Capacity

Web Application:
├─ 1000 concurrent users
├─ Average response time: 200ms
├─ Error rate: < 0.1%
└─ Throughput: 500 requests/sec

Real-time Chat:
├─ 500 active WebSocket connections
├─ Message latency: < 500ms
├─ Max 100 messages/sec
└─ Server memory: ~2GB

Database:
├─ 1000 concurrent connections
├─ Query time (average): 50ms
├─ Transactions/sec: 1000
└─ Connection pool size: 100

---

12. Compliance & Legal

12.1 Data Privacy Compliance

GDPR (Europe):
├─ User data export functionality
├─ Right to deletion (data erasure)
├─ Privacy by design
├─ Data breach notification (within 72 hours)
└─ DPA signed with AWS

India (Data Protection):
├─ Data residency in India
├─ PII classification & handling
├─ Encryption standards
└─ Audit trails maintained

Payment Card Industry (PCI-DSS):
├─ Stripe handles payment data
├─ Never store full card details
├─ Tokenized payments
├─ Quarterly security scans
└─ Annual compliance audit

12.2 Terms & Policies

Required Documents:
├─ Terms of Service
├─ Privacy Policy
├─ Acceptable Use Policy
├─ Cookie Policy
├─ GDPR Cookie Consent
└─ Data Processing Addendum (DPA)

Liability Disclaimers:
├─ Limitation of liability
├─ Dispute resolution process
├─ Insurance coverage
├─ Indemnification clauses
└─ Governing law

---

13. Technology Justification

Why These Technologies?

PostgreSQL (Database):
├─ ACID compliance ✓
├─ PostGIS for geolocation ✓
├─ Full-text search ✓
├─ JSON support for flexible data ✓
└─ Enterprise support available ✓

Node.js (Backend Runtime):
├─ JavaScript ecosystem (developers) ✓
├─ Excellent async support ✓
├─ High throughput, low latency ✓
├─ Microservices friendly ✓
└─ Strong community ✓

Next.js (Frontend):
├─ SSR for SEO ✓
├─ TypeScript support ✓
├─ API routes simplify deployment ✓
├─ Performance optimizations built-in ✓
└─ Large ecosystem ✓

React Native (Mobile):
├─ Code sharing between iOS/Android ✓
├─ Near-native performance ✓
├─ Large developer pool ✓
├─ Strong community support ✓
└─ Established ecosystem ✓

AWS (Infrastructure):
├─ Global infrastructure ✓
├─ Managed services reduce ops load ✓
├─ Strong security certifications ✓
├─ Cost-effective scaling ✓
└─ Multi-region support ✓

---

14. Document Metadata

Property	Value
Document Version	1.0
Created	December 16, 2025
Last Updated	December 16, 2025
Status	Ready for Implementation
Author	Architecture Team
Approved By	CTO (Pending)
Next Review	After MVP completion

---

End of HLD Document

This HLD provides a comprehensive blueprint for building the LostFound Guard platform. All components are designed for scalability, security, and user experience.