Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Required Software

SoftwareVersionPurpose
Node.js18+Frontend and backend runtime
npm or yarnLatestPackage management
GitLatestVersion control
Leo CLILatestAleo smart contract development
  • VS Code with TypeScript extension
  • Aleo Wallet (Leo Wallet or Shield Wallet)
  • Postman or curl for API testing

​
Installation Steps

1

Install Node.js

Download and install Node.js 18+ from nodejs.org
# Verify installation
node --version  # Should be v18 or higher
npm --version
2

Install Leo CLI (for contract development)

Install the Leo programming language CLI:
curl -sSf https://install.leo-lang.org/ | sh

# Verify installation
leo --version
Only required if you plan to work on smart contracts. Frontend/backend developers can skip this.
3

Clone the Repository

git clone <repository-url>
cd Salud
Project Structure:
Salud/
├── backend/                 # Node.js API server
├── frontend/                # React + Vite frontend
├── salud_health_records/    # Aleo Leo contract
└── README.md
4

Install Backend Dependencies

cd backend
npm install
Key Dependencies:
  • @provablehq/sdk - Aleo blockchain SDK
  • express - Web server framework
  • cors - Cross-origin resource sharing
  • dotenv - Environment configuration
5

Install Frontend Dependencies

cd ../frontend
npm install
Key Dependencies:
  • react & react-dom - UI framework
  • @provablehq/aleo-wallet-adaptor-* - Wallet integration
  • vite - Build tool and dev server
  • typescript - Type safety
  • tailwindcss - Styling
6

Configure Environment Variables

Create environment files for both frontend and backend.Backend (backend/.env):
PORT=3001
ALEO_API_URL=https://api.explorer.provable.com/v1
PROGRAM_ID=salud_health_records_v2.aleo
DEMO_MODE=false
Frontend (frontend/.env):
VITE_API_URL=http://localhost:3001/api

​
Development Workflows

​
Frontend Development

cd frontend
npm run dev

# Server starts at http://localhost:5173
# Hot Module Replacement (HMR) enabled
# Changes reflect instantly
Development Tips:
  • HMR: Changes auto-reload without full page refresh
  • Port: Default is 5173, configurable in vite.config.ts
  • TypeScript: Errors show in terminal and browser
  • Network Access: Use --host flag for mobile testing

​
Backend Development

cd backend
npm run dev

# Uses nodemon for auto-restart on changes
# Server runs on http://localhost:3001
Backend Endpoints:
MethodEndpointDescription
GET/api/healthHealth check
POST/api/wallet/connectConnect with private key
POST/api/wallet/generateGenerate new account
GET/api/wallet/balance/:sessionIdGet wallet balance
POST/api/records/createCreate medical record
GET/api/records/fetch/:sessionIdFetch user records
POST/api/access/grantGrant doctor access

​
Smart Contract Development

cd salud_health_records
leo build

# Compiles Leo to Aleo instructions
# Output in build/ directory
Contract Files: 
salud_health_records/
├── program.json              # Project configuration
├── src/
│   └── main.leo              # Main contract (~470 lines)
├── tests/
│   └── test_salud_health_records.leo
├── build/                    # Compiled output
│   ├── main.aleo
│   └── program.json
└── ARCHITECTURE.md           # Contract documentation

​
Full Stack Development

To run the complete application:
1

Start Backend

# Terminal 1
cd backend
npm run dev
Wait for: Server running on port 3001
2

Start Frontend

# Terminal 2
cd frontend
npm run dev
Wait for: Local: http://localhost:5173
3

Access Application

Open your browser to http://localhost:5173The frontend will communicate with the backend at localhost:3001

​
Development with Demo Mode

For testing without blockchain transactions: 
# backend/.env
DEMO_MODE=true
Demo Mode Features: ✅ Works:
  • All UI features function normally
  • Records stored in localStorage
  • Access grants simulated
  • QR code generation/scanning
  • Wallet connection flow
⚠️ Limitations:
  • No real blockchain transactions
  • Records don’t persist across devices
  • No actual on-chain verification
  • Perfect for UI/UX development

​
Common Development Tasks

​
Adding a New Frontend Component

# Create component file
touch frontend/src/components/NewComponent.tsx

// NewComponent.tsx
import React from 'react';

interface NewComponentProps {
  title: string;
}

export const NewComponent: React.FC<NewComponentProps> = ({ title }) => {
  return (
    <div className="new-component">
      <h2>{title}</h2>
    </div>
  );
};

​
Adding a New Backend Endpoint

// backend/server.js
app.post('/api/new-endpoint', async (req, res) => {
  try {
    const { param } = req.body;
    
    // Your logic here
    
    res.json({ success: true, data: result });
  } catch (error) {
    res.status(500).json({ 
      success: false, 
      error: error.message 
    });
  }
});

​
Adding a New Contract Transition

// salud_health_records/src/main.leo
transition new_transition(
    param1: field,
    param2: u8
) -> field {
    // Validate inputs
    assert(param2 > 0u8);
    
    // Your logic
    
    return result;
}

​
Troubleshooting

​
Backend Issues

Symptoms: Frontend shows connection errorsSolutions:
  • Ensure backend is running on port 3001
  • Check VITE_API_URL in frontend .env
  • Verify no firewall blocking port 3001
  • Check backend console for startup errors
Symptoms: Wallet connection failsSolutions:
  • Private key must start with APrivateKey1...
  • Must be exactly 59 characters
  • Use “Generate New” to create test account
  • Export key from Leo/Shield Wallet if using existing account
Symptoms: Import errors in backendSolutions:
cd backend
rm -rf node_modules package-lock.json
npm install

​
Frontend Issues

Symptoms: Type errors in terminal/browserSolutions:
  • Check tsconfig.json configuration
  • Ensure all dependencies are installed
  • Restart TypeScript server in VS Code
  • Run npm run build to see all errors
Symptoms: Build errors during npm run buildSolutions:
cd frontend
rm -rf node_modules package-lock.json dist
npm install
npm run build
Symptoms: Wallet connection issuesSolutions:
  • Clear browser cache and localStorage
  • Check wallet extension is installed
  • Verify wallet adapter dependencies versions match
  • Try different wallet (Leo vs Shield)

​
Contract Issues

Symptoms: Compilation errorsSolutions:
  • Check Leo version: leo --version
  • Ensure syntax matches Leo 2.x
  • Run leo clean then leo build
  • Check for syntax errors in main.leo
Symptoms: leo test shows failuresSolutions:
  • Read test output carefully
  • Check test assertions in tests/ directory
  • Verify contract logic matches test expectations
  • Run individual tests for debugging

​
Development Tools

  • TypeScript: Built-in, enable suggestions
  • ESLint: JavaScript/TypeScript linting
  • Tailwind CSS IntelliSense: CSS class autocomplete
  • Leo: Syntax highlighting for Leo files (if available)

​
Browser DevTools

For Frontend Debugging:
  • Console: View errors and logs
  • Network: Monitor API calls
  • Application: Inspect localStorage (demo mode)
  • React DevTools: Component inspection

​
API Testing Tools

Test Backend Endpoints:
  • curl: Command-line requests
  • Postman: GUI for API testing
  • Thunder Client: VS Code extension

​
Next Steps

Testing Guide

Learn how to run tests and ensure code quality

Contributing

Submit your first contribution

Architecture

Understand the system architecture

API Reference

Explore the API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us