# kushagraagarwal525/medilocker architecture

> Architecture diagram of the GitHub repository kushagraagarwal525/medilocker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kushagraagarwal525/medilocker
- Repository: https://github.com/kushagraagarwal525/medilocker

## Overview

##### Project Type & Purpose
- Full-stack web application for secure medical records management
- Frontend: React + TypeScript (Vite, Tailwind, Radix UI)
- Backend: Node.js + Express.js API server
- Key features: end-to-end encryption, blockchain verification on Polygon, AI-powered analysis (Gemini), Firebase/Firestore storage

##### Main Components
a. Frontend
- React App (src/main.tsx, App.tsx, components/)
- UI library (src/components/ui/*)
- Client-side encryption (src/lib/crypto.ts, Web Crypto API)
b. Backend API
- Express server (server.js)
- Routes (routes/users.js, routes/reports.js)
- Business logic modules (ignition/modules/module.ts)
- Configuration (config/firebase.js, blockchain.js, gemini.js)
c. Data Layer
- Firebase Firestore (via Admin SDK, serviceAccountKey.json)
d. Blockchain Layer
- Smart contracts (backend/contracts/)
- Ethers.js + Hardhat (hardhat.config.js) interacting with Polygon network
e. AI Service
- Google Gemini API (via config/gemini.js)
f. External Actors
- Patients & Doctors (UI users)
- Admin/Dev (deployment, Hardhat scripts)

##### Data Flows & Interactions
- Frontend → Backend API (HTTPS/JSON) for login, report upload/download
- Frontend: encrypts/decrypts medical reports before sending/after receiving
- Backend → Firestore: store/retrieve encrypted blobs & metadata
- Backend → Smart Contracts via Ethers.js: anchor report hashes on Polygon
- Backend → Google Gemini API: send decrypted reports for AI analysis, receive insights
- Config modules supply credentials/endpoints to backend services

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation (UI), API, Data, External Services
- Separation of concerns: route handlers, service modules, config abstraction
- Secure-by-design: E2E encryption, .env for secrets, strict .gitignore
- Modular UI: reusable Radix-based components under src/components/ui

##### Detail & Clarity
- UI components under one block to avoid clutter, but call out the crypto/lib module separately
- Every major directory (frontend/src, backend/routes, backend/contracts) maps to a visual component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        MainTS["main.tsx"]:::frontend
        AppTS["App.tsx"]:::frontend
        UIlib["UI Component Library"]:::frontend
        LoginPage["LoginPage.tsx"]:::frontend
        WelcomePage["WelcomePage.tsx"]:::frontend
        Crypto["crypto.ts"]:::frontend
        FrontendConfig["config.ts"]:::frontend
        Vite["Vite Build"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        ExpressServer["Express API Server"]:::backend
        UsersRoute["users.js"]:::backend
        ReportsRoute["reports.js"]:::backend
        BusinessLogic["module.ts"]:::backend
        FirebaseConfig["firebase.js"]:::backend
        BlockchainConfig["blockchain.js"]:::backend
        GeminiConfig["gemini.js"]:::backend
        ServiceAccount["serviceAccountKey.json.example"]:::backend
        HardhatConfig["hardhat.config.js"]:::backend
        Contracts["Smart Contracts"]:::backend
        GeminiScript["list_gemini_models.py"]:::backend
        Nodemon["nodemon/npm scripts"]:::backend
    end

    %% External Data Layer
    FirestoreDB["Firebase Firestore"]:::database

    %% External Services
    BlockchainCloud["Polygon Network"]:::blockchain
    GeminiCloud["Google Gemini AI"]:::ai

    %% Actors
    Patients["Patients & Doctors"]:::actor
    AdminDev["Admin/Dev"]:::actor

    %% Environment
    EnvFile[".env"]:::config

    %% Connections
    Patients -->|"Uses UI"| MainTS
    MainTS --> AppTS
    AppTS --> UIlib
    AppTS --> LoginPage
    AppTS --> WelcomePage
    AppTS --> Crypto
    AppTS --> FrontendConfig
    AppTS --> Vite
    AppTS -->|"Encrypt/Decrypt (Web Crypto API)"| Crypto
    AppTS -->|"HTTPS/JSON"| ExpressServer

    ExpressServer --> UsersRoute
    ExpressServer --> ReportsRoute
    ExpressServer --> BusinessLogic
    ExpressServer --> FirebaseConfig
    ExpressServer --> BlockchainConfig
    ExpressServer --> GeminiConfig
    ExpressServer --> ServiceAccount
    ExpressServer --> HardhatConfig
    ExpressServer --> Contracts
    ExpressServer --> GeminiScript
    ExpressServer --> Nodemon

    ExpressServer -->|"Firestore SDK"| FirestoreDB
    ExpressServer -->|"Ethers.js JSON-RPC"| BlockchainCloud
    ExpressServer -->|"REST/HTTP"| GeminiCloud

    FirebaseConfig -.-> EnvFile
    BlockchainConfig -.-> EnvFile
    GeminiConfig -.-> EnvFile
    HardhatConfig -.-> EnvFile

    AdminDev --> HardhatConfig
    AdminDev --> Contracts
    AdminDev --> GeminiScript

    %% Click Events
    click MainTS "https://github.com/kushagraagarwal525/medilocker/blob/main/frontend/src/main.tsx"
    click AppTS "https://github.com/kushagraagarwal525/medilocker/blob/main/frontend/src/App.tsx"
    click UIlib "https://github.com/kushagraagarwal525/medilocker/tree/main/frontend/src/components/ui/"
    click LoginPage "https://github.com/kushagraagarwal525/medilocker/blob/main/frontend/src/components/LoginPage.tsx"
    click WelcomePage "https://github.com/kushagraagarwal525/medilocker/blob/main/frontend/src/components/WelcomePage.tsx"
    click Crypto "https://github.com/kushagraagarwal525/medilocker/blob/main/frontend/src/lib/crypto.ts"
    click FrontendConfig "https://github.com/kushagraagarwal525/medilocker/blob/main/frontend/src/lib/config.ts"
    click ExpressServer "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/server.js"
    click UsersRoute "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/routes/users.js"
    click ReportsRoute "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/routes/reports.js"
    click BusinessLogic "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/ignition/modules/module.ts"
    click FirebaseConfig "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/config/firebase.js"
    click ServiceAccount "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/serviceAccountKey.json.example"
    click BlockchainConfig "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/config/blockchain.js"
    click Contracts "https://github.com/kushagraagarwal525/medilocker/tree/main/backend/contracts/"
    click HardhatConfig "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/hardhat.config.js"
    click GeminiConfig "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/config/gemini.js"
    click GeminiScript "https://github.com/kushagraagarwal525/medilocker/blob/main/backend/list_gemini_models.py"

    %% Styles
    classDef frontend fill:#C3DDF9,stroke:#034694,color:#000;
    classDef backend fill:#D0F0C0,stroke:#267326,color:#000;
    classDef database fill:#E0C3F9,stroke:#622569,color:#000;
    classDef blockchain fill:#FFD9A6,stroke:#C46A00,color:#000;
    classDef ai fill:#FFF3B0,stroke:#CCAC00,color:#000;
    classDef actor fill:#F0F0F0,stroke:#888,color:#000,stroke-dasharray: 2 2;
    classDef config fill:#F5E1A4,stroke:#A67C00,color:#000;
```
