Local Setup & Demo Guide

Complete guide to set up MediPact locally, verify all components, and run end-to-end demonstrations.

Prerequisites

Required Software

Node.js 20+ - Download
npm - Comes with Node.js
Git - Download
Hedera Testnet Account - Get Free Account

Verify Prerequisites

1# Check Node.js version (should be 20+)
2node -v
3
4# Check npm version
5npm -v
6
7# Check Git version
8git --version

Step 1: Clone & Install

1.1 Clone Repository

1git clone git@github.com:najuna-brian/medipact.git
2cd medipact

1.2 Install All Dependencies

1# Install backend dependencies
2cd backend
3npm install
4
5# Install frontend dependencies
6cd ../frontend
7npm install
8
9# Install adapter dependencies
10cd ../backend/adapter
11npm install
12
13# Install contract dependencies
14cd ../../contracts
15npm install
16
17# Return to root
18cd ..

This installs all required packages for backend, frontend, adapter, and smart contracts.

Step 2: Environment Configuration

2.1 Backend Environment

Create backend/.env file:

1# Hedera Configuration
2OPERATOR_ID="0.0.xxxxx"              # Your Hedera account ID
3OPERATOR_KEY="0x..."                  # Your Hedera private key (ECDSA, HEX)
4HEDERA_NETWORK="testnet"              # Network: testnet or mainnet
5
6# Server Configuration
7PORT=8080
8NODE_ENV=development
9
10# Database (SQLite for local dev)
11DATABASE_PATH="./data/medipact.db"
12
13# JWT Secret (generate a random string)
14JWT_SECRET="your-secret-key-here"
15
16# Admin Configuration
17ADMIN_EMAIL="admin@medipact.com"
18ADMIN_PASSWORD="your-secure-password"
19
20# Smart Contracts (optional, deploy first)
21CONSENT_MANAGER_ADDRESS="0x..."
22REVENUE_SPLITTER_ADDRESS="0x..."
23
24# Exchange Rate (auto-updated)
25EXCHANGE_RATE_API_KEY=""              # Optional: CoinGecko API key

2.2 Frontend Environment

Create frontend/.env.local file:

1NEXT_PUBLIC_API_URL="http://localhost:8080"
2NEXT_PUBLIC_HEDERA_NETWORK="testnet"

2.3 Adapter Environment

Create backend/adapter/.env file:

1# Hedera Configuration
2OPERATOR_ID="0.0.xxxxx"
3OPERATOR_KEY="0x..."
4HEDERA_NETWORK="testnet"
5
6# Hospital Configuration
7HOSPITAL_COUNTRY="Uganda"
8HOSPITAL_LOCATION="Kampala"
9
10# Optional: Smart Contracts
11CONSENT_MANAGER_ADDRESS="0x..."
12REVENUE_SPLITTER_ADDRESS="0x..."

💡 Getting Hedera Testnet Credentials

Visit Hedera Portal
Create a free testnet account
Copy your Account ID (format: 0.0.xxxxx)
Export your private key (ECDSA format, hex string starting with 0x)
Fund your account with test HBAR from the faucet

Step 3: Deploy Smart Contracts

3.1 Deploy to Testnet

1cd contracts
2
3# Deploy ConsentManager and RevenueSplitter
4npm run deploy:testnet

This will deploy both smart contracts to Hedera testnet. Save the contract addresses and add them to your .env files.

3.2 Verify Deployment

1# Run contract tests
2npm test
3
4# Check deployment info
5cat deployment-info.json

Step 4: Initialize Backend

4.1 Start Backend Server

1cd backend
2npm start

Backend will start on http://localhost:8080. The server will:

Initialize database tables
Create default admin account
Start background jobs (cleanup, withdrawals, exchange rates)
Initialize Hedera client

4.2 Verify Backend Health

1# In a new terminal, test health endpoint
2curl http://localhost:8080/health
3
4# Expected response:
5# {"status":"healthy","timestamp":"...","service":"MediPact Backend API","database":"connected"}

4.3 Setup Admin Account

1# Create admin account (if not auto-created)
2cd backend
3npm run setup-admin

Default admin credentials are created automatically. Check your .env for ADMIN_EMAIL and ADMIN_PASSWORD.

Step 5: Start Frontend

5.1 Start Development Server

1cd frontend
2npm run dev

Frontend will start on http://localhost:3000

5.2 Access Points

Frontend Application

1http://localhost:3000

API Documentation

1http://localhost:8080/api-docs

Documentation Site

1http://localhost:3000/docs

Health Check

1http://localhost:8080/health

Step 6: Core Component Verification

6.1 Database Verification

1# Check database file exists
2ls -lh backend/data/medipact.db
3
4# Verify tables are created (SQLite)
5sqlite3 backend/data/medipact.db ".tables"
6
7# Expected tables:
8# patients, hospitals, researchers, datasets, purchases, 
9# withdrawal_history, balance_history, etc.

6.2 Hedera Connection Test

1# Test Hedera account connection
2cd backend
3node scripts/test-hedera-accounts.js

This verifies your Hedera credentials and account balance.

6.3 Smart Contract Verification

1# Run contract tests
2cd contracts
3npm test
4
5# Verify contracts are deployed
6cat deployment-info.json | grep -A 5 "address"

6.4 Backend Services Test

1# Run backend unit tests
2cd backend
3npm test
4
5# Test specific services
6npm test -- tests/unit/services.test.js
7npm test -- tests/unit/health.test.js

Step 7: End-to-End Testing

7.1 Complete Data Flow Test

This test verifies the complete flow: Hospital Upload → Processing → Storage → Researcher Query → Export

1# From project root
2./scripts/test-complete-data-flow.sh
3
4# Or using Node.js script
5node scripts/test-complete-data-flow.js

What this tests:

Hospital registration and authentication
Patient data upload (FHIR format)
Data anonymization and storage
Dataset creation and pricing
Researcher registration and authentication
Dataset query and purchase
Revenue distribution (60/25/15 split)
Data export (CSV/API)

7.2 Revenue Flow Test

1# Test revenue distribution
2node scripts/test-revenue-flow.js
3
4# Detailed revenue test
5node scripts/test-revenue-flow-detailed.js

Verifies the 60% patient, 25% hospital, 15% platform revenue split.

7.3 Payment & Withdrawal Test

1# Test payment and withdrawal flow
2export RESEARCHER_ID="RES-XXX"  # Use actual researcher ID
3node scripts/test-payment-payout-flow.js

Tests the complete payment flow from purchase to withdrawal.

7.4 Registration Flows Test

1# Test all registration endpoints
2./scripts/test-registration-flows.sh
3
4# Test hospital registration
5./scripts/test-registration-api.sh
6
7# Test researcher registration
8./scripts/test-researcher-registration.sh

7.5 Adapter Integration Test

1# Test adapter-backend integration
2./scripts/test-adapter-backend-integration.sh
3
4# Or test adapter CSV processing
5cd backend/adapter
6npm run start:legacy

Tests CSV to FHIR conversion, anonymization, and HCS submission.

Step 8: Demo Data Setup

8.1 Populate Demo Data

1# Populate demo data (hospitals, patients, datasets)
2cd backend
3npm run demo:populate
4
5# Create demo datasets
6npm run demo:datasets
7
8# Create MVP datasets
9npm run demo:mvp

8.2 Fund Test Accounts

1# Fund existing Hedera accounts with test HBAR
2cd backend
3npm run hedera:fund

Ensures all test accounts have sufficient HBAR for transactions.

Step 9: Manual Demo Walkthrough

Demo Flow Overview

Follow this sequence to demonstrate all core features:

Hospital Registration - Register a hospital account
Patient Data Upload - Upload FHIR-compliant patient data
Data Processing - Show anonymization and HCS proofs
Dataset Creation - Create queryable datasets
Researcher Registration - Register a researcher account
Dataset Query - Query available datasets
Purchase Dataset - Purchase and download data
Revenue Distribution - Show automatic revenue split
Patient Wallet - Show patient earnings and withdrawals
HashScan Verification - Verify transactions on Hedera

9.1 Hospital Portal Demo

1# 1. Register Hospital
2POST http://localhost:8080/api/hospital/register
3{
4  "name": "Demo Hospital",
5  "contactEmail": "hospital@demo.com",
6  "country": "Uganda",
7  "location": "Kampala"
8}
9
10# 2. Login and get API key
11POST http://localhost:8080/api/hospital/login
12{
13  "email": "hospital@demo.com",
14  "password": "password"
15}
16
17# 3. Upload patient data
18POST http://localhost:8080/api/hospital/patients/upload
19Headers: X-Hospital-ID: HOSP-XXX, X-API-Key: xxx
20Body: FHIR Bundle JSON

9.2 Researcher Portal Demo

1# 1. Register Researcher
2POST http://localhost:8080/api/researcher/register
3{
4  "name": "Dr. Researcher",
5  "email": "researcher@demo.com",
6  "organization": "Research Institute",
7  "country": "USA"
8}
9
10# 2. Login
11POST http://localhost:8080/api/researcher/login
12{
13  "email": "researcher@demo.com",
14  "password": "password"
15}
16
17# 3. Query datasets
18GET http://localhost:8080/api/marketplace/datasets?country=Uganda&condition=Diabetes
19
20# 4. Purchase dataset
21POST http://localhost:8080/api/marketplace/purchase
22Headers: X-Researcher-ID: RES-XXX, Authorization: Bearer xxx
23{
24  "datasetId": "DS-XXX",
25  "query": {...}
26}

9.3 Patient Portal Demo

1# 1. Patient login (using UPI from hospital upload)
2GET http://localhost:8080/api/patient/login?upi=PID-XXX
3
4# 2. View balance
5GET http://localhost:8080/api/wallet/balance?upi=PID-XXX
6
7# 3. View earnings history
8GET http://localhost:8080/api/wallet/earnings?upi=PID-XXX
9
10# 4. Configure withdrawal method
11POST http://localhost:8080/api/payment-method
12{
13  "upi": "PID-XXX",
14  "paymentMethod": "bank",
15  "bankAccountNumber": "1234567890"
16}
17
18# 5. Initiate withdrawal
19POST http://localhost:8080/api/wallet/withdraw
20{
21  "upi": "PID-XXX",
22  "amountUSD": 10.00
23}

Step 10: Verification Checklist

System Health Checks

1# Backend health
2curl http://localhost:8080/health
3
4# Frontend accessible
5curl http://localhost:3000
6
7# API docs accessible
8curl http://localhost:8080/api-docs
9
10# Database connected
11sqlite3 backend/data/medipact.db "SELECT COUNT(*) FROM patients;"
12
13# Hedera connection
14cd backend && node scripts/test-hedera-accounts.js

✅ Complete Verification Checklist

Infrastructure

☐ Backend server running (port 8080)
☐ Frontend server running (port 3000)
☐ Database initialized and connected
☐ Hedera testnet connection working
☐ Smart contracts deployed

Core Features

☐ Hospital registration works
☐ Patient data upload works
☐ Data anonymization works
☐ HCS proofs submitted
☐ Dataset creation works

Marketplace

☐ Researcher registration works
☐ Dataset query works
☐ Dataset purchase works
☐ Data export works (CSV/API)
☐ Revenue distribution works

Wallet & Payments

☐ Patient balance visible
☐ Earnings history visible
☐ Withdrawal configuration works
☐ Withdrawal initiation works
☐ Exchange rate updates

Troubleshooting

Common Issues

Port Already in Use

1# Find process using port 8080
2lsof -i :8080
3
4# Kill process
5kill -9 <PID>
6
7# Or change port in backend/.env
8PORT=8081

Database Locked

1# Check if backend is running
2ps aux | grep "node.*server.js"
3
4# Stop backend, then restart
5# Or delete database and let it recreate
6rm backend/data/medipact.db

Hedera Connection Failed

1# Verify credentials in .env
2cat backend/.env | grep OPERATOR
3
4# Test connection
5cd backend
6node scripts/test-hedera-accounts.js
7
8# Check account balance
9# Visit https://hashscan.io/testnet and search your account ID

Module Import Errors

1# Clear node_modules and reinstall
2rm -rf node_modules package-lock.json
3npm install
4
5# Check Node.js version (must be 20+)
6node -v

Next Steps

Explore Documentation

API Documentation

Interactive API documentation is available at http://localhost:8080/api-docs

Use this to explore all available endpoints, test requests, and view response schemas.