[WIP] MVP Architecture

[!note] Document Purpose: Comprehensive technical architecture documentation for the AarogyaDost MVP platform

Audience: Developers, architects, technical stakeholders Related: [[README|MVP Overview]] | [[aws-infrastructure-report|AWS Infrastructure]] | [[DEPLOYMENT_STATUS|Deployment Status]]

---

🎯 Architecture Principles

Design Philosophy

1. Separation of Concerns: Frontend, backend, and infrastructure are independently deployable

2. API-First: RESTful API design with comprehensive documentation

3. Cloud-Native: Leverages AWS managed services for scalability and reliability

4. Mobile-Ready: Responsive web design + native mobile app support

5. Developer Experience: Fast local development, automated deployments

6. Cost-Effective: Optimized for AWS Free Tier and startup budgets

Key Architectural Decisions

Decision	Choice	Rationale
Frontend Framework	React + TypeScript	Modern, type-safe, large ecosystem
Build Tool	Vite	Fast dev server, optimized builds
Backend Framework	FastAPI (Python)	Fast, async, auto-generated API docs
Deployment	AWS Amplify + Elastic Beanstalk	Managed services, auto-scaling, low ops
Data Storage	In-memory (MVP)	Fast prototyping, future: PostgreSQL/DynamoDB
Authentication	Planned (OAuth 2.0 + JWT)	Industry standard, secure
Mobile	React Native + Expo	Code reuse, rapid development

---

🏗️ System Architecture Diagram

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           CLIENT LAYER                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐    │
│  │   Web Browser   │  │  Mobile (iOS)   │  │ Mobile (Android)│    │
│  │                 │  │                 │  │                 │    │
│  │  • Chrome       │  │  • Expo Go      │  │  • Expo Go      │    │
│  │  • Safari       │  │  • React Native │  │  • React Native │    │
│  │  • Firefox      │  │                 │  │                 │    │
│  │  • Edge         │  │                 │  │                 │    │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘    │
│           │                    │                     │             │
│           │         HTTPS (SSL/TLS)                 │             │
│           └──────────────┬──────────────────────────┘             │
│                          │                                         │
├──────────────────────────┼─────────────────────────────────────────┤
│                          │    PRESENTATION LAYER                   │
├──────────────────────────┼─────────────────────────────────────────┤
│                          │                                         │
│  ┌───────────────────────▼──────────────────────────┐              │
│  │        Web Frontend (React + TypeScript)         │              │
│  │                                                   │              │
│  │  • React 18 (Hooks, Concurrent Features)        │              │
│  │  • TypeScript (Type Safety)                     │              │
│  │  • Vite (Build Tool, Dev Server)                │              │
│  │  • Tailwind CSS (Styling)                       │              │
│  │  • shadcn/ui (UI Components)                    │              │
│  │  • React Query (Data Fetching, Caching)         │              │
│  │  • React Router (Client-side Routing)           │              │
│  │                                                   │              │
│  │  Deployment: AWS Amplify                         │              │
│  │  Domains: m.arogyadost.in, m2.arogyadost.in     │              │
│  └───────────────────┬───────────────────────────────┘              │
│                      │                                              │
│  ┌───────────────────▼──────────────────────────┐                  │
│  │    Mobile Frontend (React Native + Expo)     │                  │
│  │                                               │                  │
│  │  • React Native (Cross-platform)             │                  │
│  │  • Expo SDK (Development Tools)              │                  │
│  │  • React Navigation (Bottom Tabs + Stack)    │                  │
│  │  • React Query (State Management)            │                  │
│  │  • Expo Voice (Voice Input)                  │                  │
│  │  • Ionicons (Icons)                          │                  │
│  │                                               │                  │
│  │  Status: 🔄 In Development                   │                  │
│  │  Platforms: iOS, Android                     │                  │
│  └───────────────────┬───────────────────────────┘                  │
│                      │                                              │
│           HTTPS (RESTful API Calls)                                │
│                      │                                              │
├──────────────────────┼──────────────────────────────────────────────┤
│                      │    APPLICATION LAYER                         │
├──────────────────────┼──────────────────────────────────────────────┤
│                      │                                              │
│  ┌───────────────────▼──────────────────────────┐                  │
│  │         Backend API (FastAPI + Python)       │                  │
│  │                                               │                  │
│  │  ┌─────────────────────────────────────────┐ │                  │
│  │  │         API Routes / Endpoints          │ │                  │
│  │  │                                         │ │                  │
│  │  │  • /api/health/*  - Health Data        │ │                  │
│  │  │  • /api/chat/*    - AI Assistant       │ │                  │
│  │  │  • /api/doctors/* - Healthcare Providers│ │                  │
│  │  │  • /api/labs/*    - Lab Services       │ │                  │
│  │  │  • /api/files/*   - Medical Files      │ │                  │
│  │  │  • /docs          - Swagger UI         │ │                  │
│  │  │  • /redoc         - ReDoc API Docs     │ │                  │
│  │  └─────────────────────────────────────────┘ │                  │
│  │                                               │                  │
│  │  ┌─────────────────────────────────────────┐ │                  │
│  │  │         Business Logic Layer            │ │                  │
│  │  │                                         │ │                  │
│  │  │  • Health Score Calculation            │ │                  │
│  │  │  • Biomarker Analysis                  │ │                  │
│  │  │  • Recommendation Engine               │ │                  │
│  │  │  • AI Chat Processing (Future: LLM)    │ │                  │
│  │  │  • Medical File Management             │ │                  │
│  │  └─────────────────────────────────────────┘ │                  │
│  │                                               │                  │
│  │  ┌─────────────────────────────────────────┐ │                  │
│  │  │         Data Access Layer               │ │                  │
│  │  │                                         │ │                  │
│  │  │  • In-Memory Data Store (MVP)          │ │                  │
│  │  │  • Mock Data Providers                 │ │                  │
│  │  │  • Future: Database ORM                │ │                  │
│  │  └─────────────────────────────────────────┘ │                  │
│  │                                               │                  │
│  │  Framework: FastAPI (async, type hints)      │                  │
│  │  Python Version: 3.11                        │                  │
│  │  Deployment: AWS Elastic Beanstalk          │                  │
│  │  Instances: 2x t3.micro (dev, prod)         │                  │
│  │  Domains: api.arogyadost.in, api-dev.arogyadost.in             │
│  └───────────────────────────────────────────────┘                  │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│                      INFRASTRUCTURE LAYER (AWS)                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                    AWS ap-south-1 (Mumbai)                    │  │
│  │                                                               │  │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │  │
│  │  │  AWS Amplify    │  │ Elastic Beanstalk│  │  Amazon S3  │ │  │
│  │  │                 │  │                 │  │             │ │  │
│  │  │ • Web Hosting   │  │ • API Hosting   │  │ • Static    │ │  │
│  │  │ • Auto Deploy   │  │ • Auto Scaling  │  │   Assets    │ │  │
│  │  │ • Custom Domain │  │ • Load Balancer │  │ • Artifacts │ │  │
│  │  │ • SSL Cert      │  │ • Health Checks │  │ • Backups   │ │  │
│  │  │                 │  │                 │  │             │ │  │
│  │  │ 2 Apps          │  │ 2 Environments  │  │ 11 Buckets  │ │  │
│  │  │ (prod, dev)     │  │ (prod, dev)     │  │             │ │  │
│  │  └─────────────────┘  └─────────────────┘  └──────────────┘ │  │
│  │                                                               │  │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │  │
│  │  │  Route 53       │  │  Certificate    │  │ CloudWatch   │ │  │
│  │  │                 │  │  Manager        │  │              │ │  │
│  │  │ • DNS           │  │                 │  │ • Monitoring │ │  │
│  │  │ • arogyadost.in │  │ • SSL/TLS Certs │  │ • Logs       │ │  │
│  │  │ • Subdomains    │  │ • Wildcard Cert │  │ • Alarms     │ │  │
│  │  └─────────────────┘  └─────────────────┘  └──────────────┘ │  │
│  │                                                               │  │
│  │  ┌─────────────────────────────────────────────────────────┐ │  │
│  │  │                   EC2 Instances                          │ │  │
│  │  │                                                          │ │  │
│  │  │  • i-02aa976a8c2c2e590 (t3.micro, prod, ap-south-1b)   │ │  │
│  │  │  • i-0a5faa07649a9432d (t3.micro, dev, ap-south-1c)    │ │  │
│  │  └─────────────────────────────────────────────────────────┘ │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                         CI/CD PIPELINE                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐        │
│  │   Git    │ → │  GitHub  │ → │  Build   │ → │  Deploy  │        │
│  │   Push   │   │  Actions │   │          │   │          │        │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘        │
│                                                                      │
│  Frontend: Git → Amplify (auto-detect, build, deploy)              │
│  Backend:  Git → GitHub Actions → Docker → Elastic Beanstalk       │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

🔄 Data Flow Architecture

User Request Flow

1. User Action (Click/Tap/Voice)
   ↓
2. Frontend Component (React/React Native)
   ↓
3. React Query Hook (Data Fetching)
   ↓
4. API Client (HTTP Request via Axios/Fetch)
   ↓
5. HTTPS (SSL/TLS Encryption)
   ↓
6. AWS Load Balancer / Amplify Edge
   ↓
7. Backend API Endpoint (FastAPI Route)
   ↓
8. Request Validation (Pydantic Models)
   ↓
9. Business Logic Processing
   ↓
10. Data Retrieval (In-memory Store / Future: Database)
    ↓
11. Response Serialization (JSON)
    ↓
12. HTTPS Response
    ↓
13. React Query Cache Update
    ↓
14. Component Re-render (UI Update)
    ↓
15. User Sees Result

Health Dashboard Flow (Example)

User Opens Dashboard
   ↓
[Frontend] Insights.tsx component mounts
   ↓
[Frontend] useQuery('biomarkers', fetchBiomarkers)
   ↓
[API Call] GET https://api.arogyadost.in/api/health/biomarkers
   ↓
[Backend] /api/health/biomarkers endpoint
   ↓
[Backend] get_health_biomarkers() function
   ↓
[Backend] Calculate scores (Cardiovascular, Metabolic, etc.)
   ↓
[Backend] Return JSON response
   ↓
[Frontend] React Query receives data
   ↓
[Frontend] Cache data (5-minute stale time)
   ↓
[Frontend] Render BiomarkerCard components
   ↓
User sees 6 health categories with scores

---

🗄️ Data Models

Health Data Models

Biomarker Category

interface BiomarkerCategory {
  id: string;
  name: string;
  score: number;         // 0-100
  status: 'excellent' | 'good' | 'fair' | 'needs-improvement';
  icon: string;
  color: string;
  description: string;
}

Health Metric

interface HealthMetric {
  id: string;
  name: string;
  value: number | string;
  unit: string;
  status: 'normal' | 'warning' | 'critical';
  trend: 'up' | 'down' | 'stable';
  reference_range: string;
}

AI Chat Message

interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: Date;
  thread_id?: string;
}

Healthcare Provider

interface Doctor {
  id: string;
  name: string;
  specialty: string;
  experience: string;
  location: string;
  rating: number;
  available_slots: string[];
}

Medical File

interface MedicalFile {
  id: string;
  name: string;
  type: 'lab-report' | 'prescription' | 'imaging' | 'consultation';
  date: Date;
  provider: string;
  url: string;
  metadata: Record<string, any>;
}

---

🔌 API Architecture

RESTful API Design

Base URLs:

• Production: https://api.arogyadost.in

• Development: https://api-dev.arogyadost.in

API Endpoints Structure:

/api/
├── health/
│   ├── biomarkers          [GET]  - Health categories with scores
│   ├── recommendations     [GET]  - Personalized health actions
│   ├── metrics             [GET]  - Detailed health metrics
│   └── status              [GET]  - Overall health status
│
├── chat/
│   ├── threads             [GET, POST] - Conversation threads
│   ├── message             [POST] - Send message to AI
│   └── history/{thread_id} [GET]  - Thread message history
│
├── doctors/
│   ├── /                   [GET]  - List all doctors
│   └── /{id}               [GET]  - Doctor details
│
├── labs/
│   ├── /                   [GET]  - List all labs
│   └── /{id}               [GET]  - Lab details
│
├── files/
│   ├── /                   [GET, POST] - Medical files CRUD
│   ├── /{id}               [GET, PUT, DELETE]
│   └── upload              [POST] - File upload
│
└── biomarkers/
    └── /{id}               [GET]  - Detailed biomarker data

API Request/Response Format

Standard Response Envelope:

{
  "success": true,
  "data": { ... },
  "message": "Success",
  "timestamp": "2025-12-29T10:30:00Z"
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": { ... }
  },
  "timestamp": "2025-12-29T10:30:00Z"
}

API Documentation

• Swagger UI: /docs - Interactive API explorer

• ReDoc: /redoc - Clean API reference

• OpenAPI Spec: Auto-generated from FastAPI type hints

---

🔐 Security Architecture

Authentication & Authorization (Planned)

┌─────────────────────────────────────────┐
│         Authentication Flow              │
├─────────────────────────────────────────┤
│                                          │
│  1. User Login (Email/Phone + OTP)      │
│     ↓                                    │
│  2. OAuth 2.0 / JWT Token Generation    │
│     ↓                                    │
│  3. Token Storage (Secure HTTP-only)    │
│     ↓                                    │
│  4. API Requests (Authorization Header) │
│     ↓                                    │
│  5. Token Validation (Backend)          │
│     ↓                                    │
│  6. Access Granted / Denied             │
│                                          │
└─────────────────────────────────────────┘

Current Security Measures

Layer	Security Feature	Status
Transport	HTTPS/TLS 1.3	✅ Implemented
API	CORS Configuration	✅ Implemented
Infrastructure	VPC, Security Groups	✅ Implemented
Secrets	Environment Variables	✅ Implemented
Authentication	OAuth 2.0 + JWT	🔄 Planned
Data Encryption	At-rest encryption	🔄 Planned
Rate Limiting	API throttling	🔄 Planned
Audit Logs	User activity logging	🔄 Planned

CORS Configuration

Allowed Origins:

origins = [
    "https://m.arogyadost.in",
    "https://m2.arogyadost.in",
    "https://main.dpkvrxcu2ycyl.amplifyapp.com",
    "https://dev.dpkvrxcu2ycyl.amplifyapp.com",
    "http://localhost:5173",  # Local development
    "http://localhost:3000",  # Local mobile
]

Allowed Methods: GET, POST, PUT, DELETE, OPTIONS Allowed Headers: Content-Type, Authorization, Accept

---

📊 State Management Architecture

Frontend State Management

React Query (TanStack Query)

┌─────────────────────────────────────────┐
│      React Query State Management        │
├─────────────────────────────────────────┤
│                                          │
│  • Server State (API Data)              │
│    - Automatic caching                   │
│    - Background refetching               │
│    - Stale-while-revalidate              │
│    - Optimistic updates                  │
│                                          │
│  • Client State (UI State)              │
│    - React useState/useReducer           │
│    - Component-local state               │
│    - Form state (React Hook Form)       │
│                                          │
└─────────────────────────────────────────┘

Cache Strategy:

• Stale Time: 5 minutes (health data)

• Cache Time: 10 minutes (inactive data)

• Retry: 3 attempts with exponential backoff

• Refetch: On window focus, network reconnect

Backend State Management

In-Memory Store (MVP)

• Biomarker data: Preloaded static data

• Chat history: In-memory dict (ephemeral)

• Medical files: Mock data

• Future: Migrate to PostgreSQL/DynamoDB

---

🚀 Deployment Architecture

Frontend Deployment (AWS Amplify)

Git Push → Amplify Webhook → Build Process → Deploy
                                    ↓
                            ┌───────┴───────┐
                            │ Build Steps:  │
                            │ 1. npm install│
                            │ 2. npm build  │
                            │ 3. Optimize   │
                            │ 4. CDN Deploy │
                            └───────────────┘

Build Settings:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm install
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

Backend Deployment (Elastic Beanstalk)

Git Push → GitHub Actions → Docker Build → EB Deploy
                                    ↓
                            ┌───────┴───────┐
                            │ Deploy Steps: │
                            │ 1. Build Image│
                            │ 2. Push to ECR│
                            │ 3. EB Update  │
                            │ 4. Health Check│
                            └───────────────┘

Deployment Configuration:

• Platform: Python 3.11 on Amazon Linux 2023

• Instance: t3.micro (1 vCPU, 1 GB RAM)

• Auto-scaling: Single instance (MVP), scalable to multiple

• Health check: /api/health/status endpoint

• Rolling deployment: Zero-downtime updates

---

📈 Scalability Considerations

Current Architecture (MVP)

Component	Current	Capacity	Bottleneck
Frontend	Amplify CDN	~1M requests/month	None (CDN scales)
Backend	2x t3.micro	~100 concurrent users	Single instance
Database	In-memory	~1K records	Memory size
Storage	S3	Unlimited	None

Future Scaling Strategy

Phase 1 (0-1K Users)

• Current architecture sufficient

• Monitor performance metrics

• Add database (PostgreSQL RDS)

Phase 2 (1K-10K Users)

• Auto-scaling group (2-4 t3.small instances)

• Application Load Balancer

• Redis cache layer

• Database read replicas

Phase 3 (10K-100K Users)

• Microservices architecture

• Separate services for health, chat, files

• ElastiCache for session management

• CloudFront CDN for static assets

• DynamoDB for high-throughput data

Phase 4 (100K+ Users)

• Multi-region deployment

• Event-driven architecture (SQS, SNS)

• ML model serving (SageMaker)

• Real-time analytics (Kinesis)

---

🔍 Monitoring & Observability

Current Monitoring

Metric	Tool	Status
Application Logs	CloudWatch Logs	✅
Infrastructure Metrics	CloudWatch Metrics	✅
API Health	Custom scripts	✅
Uptime	Manual checks	✅
Costs	AWS Cost Explorer	✅

Planned Monitoring

• Application Performance Monitoring (APM)

• Real User Monitoring (RUM)

• Error Tracking (Sentry)

• Custom Dashboards (CloudWatch/Grafana)

• Alerting (PagerDuty/SNS)

• Analytics (Google Analytics, Mixpanel)

---

🔗 Integration Points

Planned Integrations

ABDM (Ayushman Bharat Digital Mission)

• Health ID creation and verification

• PHR (Personal Health Record) linking

• Hospital/clinic data exchange

• Lab report ingestion

Wearable Devices

• Apple Health / Google Fit integration

• Real-time vitals syncing

• Activity data import

Telemedicine Platforms

• Video consultation integration

• Prescription management

• Follow-up scheduling

Payment Gateways

• Razorpay / Stripe integration

• Subscription management

• Healthcare provider payments

---

📝 Technical Debt & Future Work

Known Limitations (MVP)

1. In-memory data storage - Not persistent across restarts

2. No authentication - All data publicly accessible

3. Mock data - Not real user data

4. Single instance - No high availability

5. No analytics - No usage tracking

6. Limited error handling - Basic error responses

Planned Improvements

Short-term (Next 3 Months)

• Add PostgreSQL database

• Implement user authentication

• Add unit tests (80%+ coverage)

• Set up error tracking

• Add usage analytics

Mid-term (3-6 Months)

• Auto-scaling configuration

• Caching layer (Redis)

• CI/CD improvements (automated tests)

• ABDM integration

• Mobile app launch

Long-term (6-12 Months)

• Microservices architecture

• Real-time features (WebSocket)

• ML model deployment

• Multi-region deployment

• Advanced security (HIPAA compliance)

---

🔗 Related Documentation

• [[README|MVP Overview]] - High-level overview and getting started

• [[DEPLOYMENT_STATUS|Deployment Status]] - Current deployment health

• [[aws-infrastructure-report|AWS Infrastructure]] - Detailed AWS resources and costs

• [[arogyadost-backend/API_ARCHITECTURE|Backend Architecture]] - Backend-specific architecture

• [[arogyadost-web/WEBSITE_ARCHITECTURE_SUMMARY|Web Architecture]] - Frontend architecture details

---

Created: 2025-12-29 Last Updated: 2025-12-29 Version: 1.0 Maintained By: Technical Team

[[README|← Back to MVP Overview]]