[WIP] Technical Requirements

Purpose

This document provides technical specifications and architecture guidelines for building the AarogyaDost MVP.

Updated: Based on [[product/research/opensource-tools-to-use|research on open source tools]], this document recommends tech stack optimized for local-first, privacy-focused health data management.

Related: [[mvp-prd]] | [[mvp-metrics-framework]] | [[product/research/opensource-tools-to-use]]

---

Architecture Principles

1. Local-First

• Data stored on user's device by default

• App works fully offline

• No dependency on cloud services for core features

• Optional cloud backup (post-MVP)

2. Privacy by Design

• End-to-end encryption

• No data leaves device without explicit consent

• Anonymized analytics only

• Zero-knowledge architecture

3. Performance-First

• Fast app launch (<3s)

• Smooth UI interactions (60fps)

• Efficient data processing

• Minimal resource usage

4. Simple & Maintainable

• Clear separation of concerns

• Well-documented code

• Automated testing

• Easy to debug

---

Tech Stack Recommendations

Option A: Electron + React (Recommended for MVP)

Pros:

• ✅ Cross-platform (macOS, Windows, Linux) with single codebase

• ✅ Fast development (web technologies)

• ✅ Rich ecosystem (npm packages)

• ✅ Easy to hire developers (React common)

• ✅ Hot reload for fast iteration

Cons:

• ❌ Larger app size (~150MB+)

• ❌ Higher memory usage

• ❌ Slower startup time

Stack:

Frontend: React 18 + TypeScript
State Management: Zustand or Jotai
UI Library: shadcn/ui or Chakra UI
Desktop Framework: Electron
Database: better-sqlite3 (SQLite)
Charts: Recharts or Chart.js
Analytics: PostHog

Option B: Tauri + React (Better Performance)

Pros:

• ✅ Smaller app size (~5-10MB)

• ✅ Lower memory usage

• ✅ Faster startup

• ✅ Better security (Rust backend)

Cons:

• ❌ Newer framework (smaller community)

• ❌ Steeper learning curve (Rust)

• ❌ Fewer libraries/plugins

Stack:

Frontend: React 18 + TypeScript
Backend: Rust (Tauri)
Database: rusqlite (SQLite)
Charts: Recharts
Analytics: PostHog

Option C: Native Apps (Best Performance, Slower Development)

Pros:

• ✅ Best performance and UX

• ✅ Smallest app size

• ✅ Platform-native feel

Cons:

• ❌ Separate codebases (Swift for macOS, Kotlin/C# for Windows)

• ❌ 2-3x development time

• ❌ Harder to maintain

Not recommended for MVP (iterate to native later if needed)

Recommendation: Electron + React

• Best balance of speed-to-market and functionality

• Single codebase for all platforms

• Easy to iterate and add features

• Can migrate to Tauri later if performance becomes issue

---

Application Architecture

High-Level Architecture

┌─────────────────────────────────────┐
│         Presentation Layer          │
│  (React Components, UI, Charts)     │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Application Layer           │
│  (Business Logic, State Management) │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│           Service Layer             │
│  (OCR, Encryption, Analytics)       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│           Data Layer                │
│  (SQLite, File System, Encryption)  │
└─────────────────────────────────────┘

Folder Structure

aarogyadost/
├── src/
│   ├── main/                 # Electron main process
│   │   ├── index.ts          # App entry point
│   │   ├── database.ts       # SQLite setup
│   │   ├── encryption.ts     # Encryption logic
│   │   └── fileSystem.ts     # File management
│   │
│   ├── renderer/             # Electron renderer process (React)
│   │   ├── components/       # React components
│   │   │   ├── Timeline/
│   │   │   ├── Charts/
│   │   │   ├── Upload/
│   │   │   └── Dashboard/
│   │   │
│   │   ├── services/         # Service layer
│   │   │   ├── ocrService.ts
│   │   │   ├── analyticsService.ts
│   │   │   ├── storageService.ts
│   │   │   └── chartService.ts
│   │   │
│   │   ├── store/            # State management (Zustand)
│   │   │   ├── documentsStore.ts
│   │   │   ├── biomarkersStore.ts
│   │   │   └── userStore.ts
│   │   │
│   │   ├── utils/            # Helper functions
│   │   │   ├── dateUtils.ts
│   │   │   ├── validation.ts
│   │   │   └── formatting.ts
│   │   │
│   │   └── App.tsx           # Root component
│   │
│   └── shared/               # Shared types and constants
│       ├── types.ts
│       └── constants.ts
│
├── tests/                    # Unit & integration tests
│   ├── unit/
│   └── integration/
│
├── public/                   # Static assets
├── package.json
└── tsconfig.json

---

Database Schema

SQLite Schema

-- Users Table (single user for MVP, expand later)
CREATE TABLE user_profile (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  name TEXT,
  date_of_birth DATE,
  gender TEXT CHECK(gender IN ('Male', 'Female', 'Other')),
  blood_group TEXT,
  height_cm REAL,
  password_hash TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Documents Table
CREATE TABLE documents (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  user_id TEXT NOT NULL REFERENCES user_profile(id),
  filename TEXT NOT NULL,
  file_path TEXT NOT NULL, -- Relative path to encrypted file
  file_size_bytes INTEGER NOT NULL,
  file_type TEXT NOT NULL, -- pdf, jpg, png
  upload_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  document_date DATE, -- Date of report (extracted or user-entered)
  document_type TEXT, -- lab_report, prescription, imaging, etc.
  lab_name TEXT, -- Thyrocare, Dr. Lal PathLabs, etc.
  doctor_name TEXT,
  hospital_name TEXT,
  ocr_status TEXT CHECK(ocr_status IN ('pending', 'processing', 'completed', 'failed')) DEFAULT 'pending',
  ocr_error TEXT, -- Error message if OCR failed
  thumbnail_path TEXT, -- Path to thumbnail image
  notes TEXT, -- User-added notes
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_documents_user_date ON documents(user_id, document_date DESC);
CREATE INDEX idx_documents_ocr_status ON documents(ocr_status);

-- Biomarkers Table (extracted or manually entered data)
CREATE TABLE biomarkers (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  user_id TEXT NOT NULL REFERENCES user_profile(id),
  document_id TEXT REFERENCES documents(id), -- NULL if manually entered
  test_name TEXT NOT NULL, -- "HbA1c", "Total Cholesterol", etc.
  test_code TEXT, -- LOINC code (future interoperability)
  value REAL NOT NULL, -- Numeric value
  value_text TEXT, -- Original text value (for non-numeric)
  unit TEXT NOT NULL, -- "mg/dL", "%", "g/dL", etc.
  reference_range_low REAL, -- Lower bound of normal range
  reference_range_high REAL, -- Upper bound of normal range
  reference_range_text TEXT, -- Original text (e.g., "4.0 - 5.6")
  test_date DATE NOT NULL,
  is_abnormal BOOLEAN, -- Flagged as abnormal in report
  manually_entered BOOLEAN DEFAULT FALSE,
  manually_corrected BOOLEAN DEFAULT FALSE, -- OCR result corrected by user
  notes TEXT, -- User-added notes
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_biomarkers_user_test ON biomarkers(user_id, test_name, test_date DESC);
CREATE INDEX idx_biomarkers_document ON biomarkers(document_id);

-- Tags Table (user-defined tags for documents)
CREATE TABLE tags (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  user_id TEXT NOT NULL REFERENCES user_profile(id),
  name TEXT NOT NULL UNIQUE,
  color TEXT, -- Hex color for UI
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Document Tags (many-to-many)
CREATE TABLE document_tags (
  document_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
  tag_id TEXT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
  PRIMARY KEY (document_id, tag_id)
);

-- Analytics Events Table (local storage before sending to PostHog)
CREATE TABLE analytics_events (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  event_name TEXT NOT NULL,
  event_properties TEXT, -- JSON string
  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  sent BOOLEAN DEFAULT FALSE -- Track if sent to PostHog
);

CREATE INDEX idx_analytics_sent ON analytics_events(sent, timestamp);

-- App Settings Table
CREATE TABLE app_settings (
  key TEXT PRIMARY KEY,
  value TEXT NOT NULL,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Sample initial settings
INSERT INTO app_settings (key, value) VALUES
  ('analytics_enabled', 'false'),
  ('theme', 'light'),
  ('language', 'en');

---

Core Services

1. OCR Service (Smart OCR for Indian Lab Reports)

Responsibility: Extract structured data from Indian medical documents with multi-language support

Research Context: See [[product/research/opensource-tools-to-use]] for detailed OCR technology evaluation

Indian Lab Report Challenges:

• Multiple formats: Thyrocare, Dr. Lal PathLabs, Apollo, SRL Diagnostics each have unique layouts

• Multi-language content: Hindi, Tamil, Telugu names and headers mixed with English values

• Table structures: Complex nested tables with reference ranges

• Handwritten notes: Doctor annotations and prescriptions

Implementation Options:

Option A: Tesseract OCR (Open-Source)

// ocrService.ts
import { createWorker } from 'tesseract.js';

class OCRService {
  private worker: Tesseract.Worker | null = null;

  async initialize() {
    this.worker = await createWorker('eng');
    // Load additional languages if needed
    await this.worker.loadLanguage('hin'); // Hindi
  }

  async extractText(imagePath: string): Promise<string> {
    if (!this.worker) await this.initialize();
    const { data: { text } } = await this.worker!.recognize(imagePath);
    return text;
  }

  async extractBiomarkers(imagePath: string): Promise<Biomarker[]> {
    const text = await this.extractText(imagePath);
    return this.parseBiomarkers(text);
  }

  private parseBiomarkers(text: string): Biomarker[] {
    // Use regex patterns to extract test name, value, unit, reference range
    // Example patterns for Indian lab reports
    const patterns = {
      testLine: /^([A-Za-z\s]+)\s+([\d\.]+)\s+([a-zA-Z/%]+)\s+([\d\.\-\s]+)$/gm
    };

    const biomarkers: Biomarker[] = [];
    // Parse and extract...
    return biomarkers;
  }
}

Pros: Free, works offline, no API costs Cons: 70-80% accuracy, slower processing

Option B: Cloud OCR API (Google Cloud Vision or AWS Textract)

import vision from '@google-cloud/vision';

class OCRService {
  private client = new vision.ImageAnnotatorClient();

  async extractText(imagePath: string): Promise<string> {
    const [result] = await this.client.textDetection(imagePath);
    return result.fullTextAnnotation?.text || '';
  }

  async extractStructuredData(imagePath: string) {
    const [result] = await this.client.documentTextDetection(imagePath);
    // Returns structured blocks, paragraphs, words
    return result;
  }
}

Pros: 90-95% accuracy, handles tables well Cons: Costs ~$1.50 per 1000 images, requires internet, privacy concern

Option C: Hybrid Approach (Recommended)

• Use Tesseract for initial extraction (free, offline)

• Fall back to Cloud API for failed/low-confidence extractions

• User always reviews and can correct

2. Encryption Service

Responsibility: Encrypt/decrypt user data at rest

// encryptionService.ts
import crypto from 'crypto';

class EncryptionService {
  private algorithm = 'aes-256-gcm';
  private keyLength = 32; // 256 bits

  // Derive encryption key from user password
  deriveKey(password: string, salt: Buffer): Buffer {
    return crypto.pbkdf2Sync(password, salt, 100000, this.keyLength, 'sha512');
  }

  // Encrypt data
  encrypt(plaintext: string, key: Buffer): EncryptedData {
    const iv = crypto.randomBytes(16);
    const cipher = crypto.createCipheriv(this.algorithm, key, iv);

    let encrypted = cipher.update(plaintext, 'utf8', 'hex');
    encrypted += cipher.final('hex');

    const authTag = cipher.getAuthTag();

    return {
      encrypted,
      iv: iv.toString('hex'),
      authTag: authTag.toString('hex')
    };
  }

  // Decrypt data
  decrypt(encryptedData: EncryptedData, key: Buffer): string {
    const decipher = crypto.createDecipheriv(
      this.algorithm,
      key,
      Buffer.from(encryptedData.iv, 'hex')
    );

    decipher.setAuthTag(Buffer.from(encryptedData.authTag, 'hex'));

    let decrypted = decipher.update(encryptedData.encrypted, 'hex', 'utf8');
    decrypted += decipher.final('utf8');

    return decrypted;
  }

  // Encrypt file
  async encryptFile(inputPath: string, outputPath: string, key: Buffer) {
    const input = fs.createReadStream(inputPath);
    const output = fs.createWriteStream(outputPath);

    const iv = crypto.randomBytes(16);
    const cipher = crypto.createCipheriv(this.algorithm, key, iv);

    // Write IV to beginning of file
    output.write(iv);

    input.pipe(cipher).pipe(output);

    return new Promise((resolve, reject) => {
      output.on('finish', resolve);
      output.on('error', reject);
    });
  }
}

3. Chart Service

Responsibility: Generate biomarker trend charts

// chartService.ts
interface ChartData {
  biomarker: string;
  dataPoints: DataPoint[];
  referenceRange: { low: number; high: number };
  timeRange: 'all' | '1y' | '5y' | '10y';
}

class ChartService {
  async getBiomarkerTrend(
    userId: string,
    biomarkerName: string,
    timeRange: string
  ): Promise<ChartData> {
    // Query database for biomarker data
    const dataPoints = await db.query(`
      SELECT test_date, value, unit, reference_range_low, reference_range_high
      FROM biomarkers
      WHERE user_id = ? AND test_name = ?
        AND test_date >= date('now', '-${timeRange}')
      ORDER BY test_date ASC
    `, [userId, biomarkerName]);

    // Format for charting library
    return {
      biomarker: biomarkerName,
      dataPoints: dataPoints.map(dp => ({
        date: dp.test_date,
        value: dp.value,
        unit: dp.unit
      })),
      referenceRange: {
        low: dataPoints[0]?.reference_range_low || 0,
        high: dataPoints[0]?.reference_range_high || 0
      },
      timeRange
    };
  }

  calculateTrend(dataPoints: DataPoint[]): 'improving' | 'declining' | 'stable' {
    if (dataPoints.length < 2) return 'stable';

    // Simple linear regression to determine trend
    // ... implementation
  }
}

---

API Design (IPC for Electron)

Main Process ↔ Renderer Process Communication

// In main process (main/ipc.ts)
import { ipcMain } from 'electron';

// Document upload
ipcMain.handle('document:upload', async (event, filePath: string) => {
  try {
    // 1. Copy file to secure storage
    // 2. Encrypt file
    // 3. Create database record
    // 4. Trigger OCR processing
    return { success: true, documentId: '...' };
  } catch (error) {
    return { success: false, error: error.message };
  }
});

// OCR processing
ipcMain.handle('ocr:process', async (event, documentId: string) => {
  // Process document with OCR
  // Extract biomarkers
  // Save to database
});

// Get biomarkers for chart
ipcMain.handle('biomarkers:gettrend', async (event, params) => {
  // Query database
  // Return chart data
});

// In renderer process (services/ipcService.ts)
import { ipcRenderer } from 'electron';

class IPCService {
  async uploadDocument(filePath: string) {
    return await ipcRenderer.invoke('document:upload', filePath);
  }

  async processOCR(documentId: string) {
    return await ipcRenderer.invoke('ocr:process', documentId);
  }

  async getBiomarkerTrend(userId: string, biomarker: string, timeRange: string) {
    return await ipcRenderer.invoke('biomarkers:getTrend', {
      userId,
      biomarker,
      timeRange
    });
  }
}

---

Performance Requirements

Load Time Targets

Operation	Target	Measurement
App Launch	<3s	Time to render UI
Timeline Load (100 docs)	<2s	Query + render
Chart Render	<1s	Data fetch + draw
Document Upload	<5s	File copy + encrypt + DB write
OCR Processing	<30s	Per document
Search Results	<500ms	Query + render

Optimization Strategies

1. Database Indexing: Index frequently queried fields

2. Lazy Loading: Load documents/charts on-demand

3. Virtualization: Virtualize long lists (react-window)

4. Caching: Cache chart data, thumbnails

5. Background Processing: OCR in worker threads

6. Database Connection Pool: Reuse SQLite connections

---

Security Requirements

1. Password Security

• Use bcrypt or Argon2 for password hashing

• Minimum password length: 8 characters

• Derive encryption key from password using PBKDF2 (100,000 iterations)

2. Data Encryption

• AES-256-GCM for encryption

• Unique IV for each encryption operation

• Store encryption key in OS keychain (not in app)

3. File Storage

• All documents encrypted at rest

• Encrypted files stored in app-specific folder

• Prevent access from other apps

4. Memory Security

• Clear sensitive data from memory after use

• No logging of passwords or encryption keys

5. Network Security

• No network requests in MVP (fully offline)

• When adding cloud backup: TLS 1.3, certificate pinning

---

Testing Strategy

Unit Tests (80% Coverage Target)

// Example test: biomarkerService.test.ts
import { BiomarkerService } from '../services/biomarkerService';

describe('BiomarkerService', () => {
  test('should parse HbA1c from text', () => {
    const text = "HbA1c  5.8  %  4.0 - 5.6";
    const result = BiomarkerService.parseBiomarker(text);

    expect(result.testName).toBe('HbA1c');
    expect(result.value).toBe(5.8);
    expect(result.unit).toBe('%');
    expect(result.referenceRangeLow).toBe(4.0);
    expect(result.referenceRangeHigh).toBe(5.6);
  });
});

Integration Tests

// Example test: documentUpload.test.ts
describe('Document Upload Flow', () => {
  test('should upload, encrypt, and process document', async () => {
    // 1. Upload document
    const result = await uploadDocument('test-report.pdf');
    expect(result.success).toBe(true);

    // 2. Verify encrypted file exists
    const fileExists = await fs.exists(result.encryptedPath);
    expect(fileExists).toBe(true);

    // 3. Verify database record
    const doc = await db.getDocument(result.documentId);
    expect(doc).toBeDefined();
    expect(doc.ocrStatus).toBe('pending');

    // 4. Process OCR
    await processOCR(result.documentId);

    // 5. Verify biomarkers extracted
    const biomarkers = await db.getBiomarkers(result.documentId);
    expect(biomarkers.length).toBeGreaterThan(0);
  });
});

E2E Tests (Critical User Flows)

Use Playwright or Spectron for E2E testing:

1. First-time user onboarding

2. Upload document → View timeline

3. Upload document → View chart

4. Search and filter documents

5. Export data

---

Development Setup

Prerequisites

# Install Node.js 18+
node --version

# Install pnpm (faster than npm)
npm install -g pnpm

Initial Setup

# Clone repo
git clone https://github.com/aarogyadost/aarogyadost.git
cd aarogyadost

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env

# Initialize database
pnpm run db:init

# Run development server
pnpm run dev

Scripts

{
  "scripts": {
    "dev": "electron-vite dev",
    "build": "electron-vite build",
    "build:mac": "electron-builder --mac",
    "build:win": "electron-builder --win",
    "build:linux": "electron-builder --linux",
    "test": "vitest",
    "test:e2e": "playwright test",
    "lint": "eslint src --ext .ts,.tsx",
    "format": "prettier --write src/**/*.{ts,tsx}"
  }
}

---

Deployment & Distribution

Code Signing (Required for macOS/Windows)

macOS:

• Obtain Apple Developer account ($99/year)

• Generate Developer ID certificate

• Sign app with electron-builder

Windows:

• Obtain Code Signing certificate (~$200-500/year)

• Sign with electron-builder

Auto-Updates

Use electron-updater for auto-updates:

import { autoUpdater } from 'electron-updater';

autoUpdater.checkForUpdatesAndNotify();

autoUpdater.on('update-available', () => {
  // Show notification to user
});

autoUpdater.on('update-downloaded', () => {
  // Prompt user to restart
});

Distribution Channels

1. Direct Download (MVP)

   • Host .dmg (macOS) and .exe (Windows) on website

   • Use GitHub Releases for storage

2. App Stores (Post-MVP)

   • Mac App Store

   • Microsoft Store

---

Monitoring & Error Tracking

Sentry Integration

import * as Sentry from '@sentry/electron';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  beforeSend(event) {
    // Remove PII before sending
    return sanitizeEvent(event);
  }
});

Performance Monitoring

// Track performance metrics
Sentry.startTransaction({
  name: 'document-upload',
  op: 'upload'
});

// Track specific operations
const span = Sentry.getCurrentHub().getScope()?.getTransaction()?.startChild({
  op: 'ocr-processing'
});

// ... OCR logic ...

span?.finish();

---

Open Technical Decisions

1. OCR Approach

• Option A: Tesseract only (free, 80% accuracy)

• Option B: Cloud API only (paid, 95% accuracy)

• Option C: Hybrid (Tesseract + Cloud fallback)

Recommendation: Start with Option A (Tesseract), add Cloud API later if accuracy insufficient.

2. UI Framework

• Option A: shadcn/ui (modern, customizable)

• Option B: Chakra UI (batteries-included)

• Option C: Material-UI (comprehensive, heavier)

Recommendation: shadcn/ui for modern, lightweight UI.

3. Chart Library

• Option A: Recharts (React-first, simple)

• Option B: Chart.js (feature-rich, larger)

• Option C: Victory (customizable, complex)

Recommendation: Recharts for simplicity and React integration.

---

Related Documents

• [[mvp-prd]] - Product Requirements

• [[mvp-metrics-framework]] - Metrics & Analytics

• [[memo]] - Product Vision

---

Next Steps

1. Choose tech stack (Electron + React recommended)

2. Set up project with boilerplate

3. Implement database schema and migrations

4. Build core services (OCR, Encryption, Charts)

5. Implement UI components (Timeline, Charts, Upload)

6. Integrate analytics (PostHog)

7. Write tests (unit + integration)

8. Package and distribute (code signing, installers)

Status: Ready for development ✅