# sidth3dr3amer/medora_sandbocx architecture

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

- Interactive diagram: https://gitdiagram.com/sidth3dr3amer/medora_sandbocx
- Repository: https://github.com/sidth3dr3amer/medora_sandbocx

## Overview

##### Project Type and Purpose
- This is a full-stack decentralized application (“dApp”) for managing patient documents and consent on a blockchain.
- Frontend: React (Vite) SPA that interacts with users and MetaMask.
- Backend: Node.js/Express API that handles authentication, audit logs, consent, document metadata, patient records, and orchestrates blockchain/IPFS interactions.
- Smart Contracts: Solidity code managed by Hardhat (in contracts/, artifacts/, cache/).
- Data stores: MongoDB (configured in backend/src/config/db.js) for off-chain data; IPFS for file storage; Ethereum (Hardhat or testnet) for on-chain consent and audit.

##### File Structure Highlights
- Top level:
- contracts/, artifacts/, cache/ — smart contract sources, compiled ABIs, build caches.
- backend/ — Express service organized by routes, controllers, services, models, middlewares.
- medora-frontend/ — React/Vite app with components, pages, API client, contexts, utility modules.
- scripts/deploy.js — contract deployment.
- test/medora.test.js — integration or contract tests.
- Backend layers:
- routes → controllers → services → models → database/blockchain.
- services/blockchainService.js, ipfsService.js, hashService.js.
- Frontend layers:
- pages (Dashboard, Upload, Login)
- components (Navbar, ProtectedRoute)
- API client (axios.js)
- MetaMask utilities and cryptographic helpers.

##### Core Components
a. Presentation Layer
- User’s Web Browser
- React SPA (medora-frontend)
- MetaMask extension (interacts with Web3 provider)
b. API Layer
- Express.js server (backend/src/server.js)
- REST endpoints: /auth, /patients, /documents, /consent, /audit
c. Business Logic & Services
- Auth, Consent, Patient, Document, Audit Controllers & Services
- blockchainService (ethers.js/web3)
- ipfsService (file upload/retrieval)
- hashService (document hashing)
d. Data Stores
- MongoDB (collections: Users, Patients, Documents, Consents, Audits)
- IPFS (file storage)
- Ethereum Blockchain (smart contracts deployed via Hardhat)
e. Smart Contracts
- ConsentContract.sol, DocumentRegistry.sol, etc. (in contracts/)
- Deployment via scripts/deploy.js
- ABIs consumed by both backend and frontend (backend/src/abis, artifacts/)

##### Relationships & Data Flows
- User ↔ React SPA
- React SPA → Express API (Axios calls) → Controllers → Services → MongoDB
- React SPA → MetaMask → Ethereum node → Smart Contracts
- API (blockchainService) → Ethereum node → Smart Contracts
- API (ipfsService) → IPFS network
- Smart Contracts emit events → backend listeners or frontend subscriptions
- Tests (test/medora.test.js) validate end-to-end behavior and contracts

##### Architectural Patterns & Principles
- Layered MVC-style backend
- Client-server separation
- On-chain/off-chain split: sensitive data off-chain, proofs & consents on-chain
- Service-oriented internal modules (blockchain, IPFS, hashing)
- Stateless REST API behind authentication middleware

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)" 
        BROWSER["React SPA (medora-frontend)"]:::frontend
        App["App.jsx"]:::frontend
        Main["main.jsx"]:::frontend
        Dashboard["Dashboard.jsx"]:::frontend
        Upload["Upload.jsx"]:::frontend
        Login["Login.jsx"]:::frontend
        Navbar["Navbar.jsx"]:::frontend
        Protected["ProtectedRoute.jsx"]:::frontend
        Axios["axios.js"]:::frontend
        AuthContext["AuthContext.jsx"]:::frontend
        MetaMaskUtil["metamask.js"]:::frontend
        CryptoUtil["crypto.js"]:::frontend
    end

    %% Backend API Server
    subgraph "Backend API Server" 
        Server["server.js"]:::backend
        DBConfig["db.js"]:::backend
        subgraph "Routes"
            AuthRoutes["auth.js"]:::backend
            PatientRoutes["patients.js"]:::backend
            DocumentRoutes["documents.js"]:::backend
            ConsentRoutes["consent.js"]:::backend
            AuditRoutes["audit.js"]:::backend
        end
        subgraph "Controllers"
            AuthCtrl["authController.js"]:::backend
            PatientCtrl["patientController.js"]:::backend
            DocumentCtrl["documentController.js"]:::backend
            ConsentCtrl["consentController.js"]:::backend
            AuditCtrl["auditController.js"]:::backend
        end
        subgraph "Services"
            BlockchainSvc["blockchainService.js"]:::backend
            IPFSSvc["ipfsService.js"]:::backend
            HashSvc["hashService.js"]:::backend
        end
        subgraph "Models"
            UserModel["User.js"]:::backend
            PatientModel["Patient.js"]:::backend
            DocumentModel["Document.js"]:::backend
            ConsentModel["Consent.js"]:::backend
            AuditModel["Audit.js"]:::backend
        end
        subgraph "Middlewares"
            JWTAuth["auth.js"]:::backend
            UploadMW["upload.js"]:::backend
        end
        Utils["validators.js"]:::backend
        ABIs["backend/src/abis/contracts"]:::backend
    end

    %% Off-Chain Storage
    subgraph "Off-Chain Storage"
        MongoDB["MongoDB"]:::db
        IPFS["IPFS"]:::ipfs
    end

    %% Blockchain Layer
    subgraph "Blockchain"
        Ethereum["Ethereum Network"]:::blockchain
        Contracts["contracts/"]:::blockchain
        Artifacts["artifacts/"]:::blockchain
        DeployScript["deploy.js"]:::blockchain
    end

    %% Tests
    Test["medora.test.js"]:::backend

    %% Connections: Frontend
    BROWSER -->|renders| App
    App -->|mount| Main
    App -->|uses| Navbar
    App -->|protects routes| Protected
    App -->|routes to| Dashboard
    App -->|routes to| Upload
    App -->|routes to| Login
    App -->|calls API| Axios
    App -->|provides auth| AuthContext
    App -->|calls MetaMask| MetaMaskUtil
    App -->|hash| CryptoUtil

    %% Connections: Frontend to Backend
    Axios -->|REST calls| Server

    %% Connections: Server internals
    Server -->|init| DBConfig
    Server -->|use middleware| JWTAuth
    Server -->|use middleware| UploadMW
    Server -->|use utils| Utils
    Server -->|load routes| AuthRoutes
    Server -->|load routes| PatientRoutes
    Server -->|load routes| DocumentRoutes
    Server -->|load routes| ConsentRoutes
    Server -->|load routes| AuditRoutes

    %% Routes to Controllers
    AuthRoutes -->|calls| AuthCtrl
    PatientRoutes -->|calls| PatientCtrl
    DocumentRoutes -->|calls| DocumentCtrl
    ConsentRoutes -->|calls| ConsentCtrl
    AuditRoutes -->|calls| AuditCtrl

    %% Controllers to Services & Models
    AuthCtrl -->|uses| BlockchainSvc
    PatientCtrl -->|uses model| PatientModel
    DocumentCtrl -->|uses| HashSvc
    DocumentCtrl -->|uses| IPFSSvc
    DocumentCtrl -->|uses model| DocumentModel
    ConsentCtrl -->|uses| BlockchainSvc
    ConsentCtrl -->|uses model| ConsentModel
    AuditCtrl -->|uses| BlockchainSvc
    AuditCtrl -->|uses model| AuditModel

    %% Services to Data Layers
    BlockchainSvc -->|eth_sendTransaction| Ethereum
    IPFSSvc -->|upload/download| IPFS
    HashSvc -->|hashing| CryptoUtil

    %% Models to MongoDB
    UserModel -->|collection Users| MongoDB
    PatientModel -->|collection Patients| MongoDB
    DocumentModel -->|collection Documents| MongoDB
    ConsentModel -->|collection Consents| MongoDB
    AuditModel -->|collection Audits| MongoDB

    %% ABIs and Contracts
    DeployScript -->|deploys| Contracts
    Contracts -->|on-chain logic| Ethereum
    Artifacts -->|compiled| ABIs
    ABIs -->|consumed by| Server
    ABIs -->|consumed by| BROWSER

    %% Tests
    Test -->|validate| Contracts
    Test -->|exercise| Server

    %% Click Events
    click BROWSER "https://github.com/sidth3dr3amer/medora_sandbocx/tree/main/medora-frontend/"
    click App "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/App.jsx"
    click Main "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/main.jsx"
    click Dashboard "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/pages/Dashboard.jsx"
    click Upload "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/pages/Upload.jsx"
    click Login "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/pages/Login.jsx"
    click Navbar "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/components/Navbar.jsx"
    click Protected "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/components/ProtectedRoute.jsx"
    click Axios "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/api/axios.js"
    click AuthContext "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/context/AuthContext.jsx"
    click MetaMaskUtil "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/utils/metamask.js"
    click CryptoUtil "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/medora-frontend/src/utils/crypto.js"
    click Server "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/server.js"
    click DBConfig "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/config/db.js"
    click AuthRoutes "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/routes/auth.js"
    click PatientRoutes "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/routes/patients.js"
    click DocumentRoutes "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/routes/documents.js"
    click ConsentRoutes "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/routes/consent.js"
    click AuditRoutes "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/routes/audit.js"
    click AuthCtrl "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/controllers/authController.js"
    click PatientCtrl "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/controllers/patientController.js"
    click DocumentCtrl "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/controllers/documentController.js"
    click ConsentCtrl "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/controllers/consentController.js"
    click AuditCtrl "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/controllers/auditController.js"
    click BlockchainSvc "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/services/blockchainService.js"
    click IPFSSvc "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/services/ipfsService.js"
    click HashSvc "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/services/hashService.js"
    click UserModel "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/models/User.js"
    click PatientModel "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/models/Patient.js"
    click DocumentModel "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/models/Document.js"
    click ConsentModel "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/models/Consent.js"
    click AuditModel "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/models/Audit.js"
    click JWTAuth "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/middlewares/auth.js"
    click UploadMW "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/middlewares/upload.js"
    click Utils "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/backend/src/utils/validators.js"
    click ABIs "https://github.com/sidth3dr3amer/medora_sandbocx/tree/main/backend/src/abis/contracts"
    click Contracts "https://github.com/sidth3dr3amer/medora_sandbocx/tree/main/contracts/"
    click DeployScript "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/scripts/deploy.js"
    click Test "https://github.com/sidth3dr3amer/medora_sandbocx/blob/main/test/medora.test.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#DFFFD0,stroke:#228B22,stroke-width:1px
    classDef db fill:#FFF5BA,stroke:#C2A900,stroke-width:1px
    classDef blockchain fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef ipfs fill:#E6E6FA,stroke:#9370DB,stroke-width:1px
```
