TrueID

Decentralized Biometric Identity System

Secure biometric authentication backed by blockchain — tamper-proof, privacy-first, and built for scale.

---

Overview

TrueID combines biometric authentication with blockchain technology to create a tamper-proof, decentralized identity management system. Users register once, verify with their face, and carry a cryptographically-secured identity that no central authority can alter or revoke.

---

📑 Table of Contents

• Overview
• Features
• Architecture
• Getting Started
• Security
• Development
• Contributing
• Support

🌟 Key Features

Biometric Auth Secure face recognition	Blockchain Immutable records	Privacy End-to-end encryption
Mobile App Cross-platform	Gov Portal Admin dashboard	Security Multi-factor auth

📋 System Overview

TrueID combines blockchain technology with biometric authentication to create a tamper-proof identity management system. The system consists of the following components:

📱 1. Android Mobile App

• 📝 User Registration: Streamlined onboarding process
• 🔍 Biometric Auth: ML Kit Face Detection integration
• 📊 Identity Management: Professional profile versioning
• 💎 Blockchain Wallet: Secure transaction verification
• 🔒 Data Security: Encrypted storage
• 📡 Offline Mode: Authentication without internet
• 📱 QR Codes: Easy identity sharing
• 📸 CameraX: Advanced camera features
• 🔄 Retrofit: Efficient API communication

🖥️ 2. Backend Server

• 🌐 RESTful API: Node.js/Express.js endpoints
• 🔑 Auth System: JWT with refresh tokens
• ⛓️ Blockchain: Ethers.js integration
• 💾 Database: PostgreSQL operations
• 🔐 Biometric: SHA-256 hashing
• 🛡️ Security: Rate limiting & validation
• 🔔 Webhooks: Event notifications
• 🛡️ Helmet: Enhanced security headers
• 📝 Morgan: Request logging

⛓️ 3. Blockchain Layer

• 📜 Smart Contracts: Avalanche Fuji deployment
• ✍️ Multi-sig: Identity verification
• 📚 History: Immutable records
• ⏱️ Audit Trail: Timestamp verification
• 👥 Access Control: Role-based permissions
• 💰 Gas Optimization: Cost-effective transactions

🌐 4. Frontend Web Application

• ⚛️ React.js: Modern UI with Material UI
• 📱 Responsive: All device support
• 🔗 Web3: Blockchain integration
• 🔐 Auth: Secure token management
• 🎨 UI/UX: User-friendly interface
• 🔄 Real-time: Polling updates

🏛️ 5. Government Portal

• ⚛️ React.js: Tailwind CSS dashboard
• 👥 RBAC: Administrative hierarchy
• 📋 Identity: Detailed user profiles
• 🔍 Records: Search & filtering
• 📊 Analytics: Audit trail viewing
• 📈 Stats: Real-time visualization
• 🛠️ Dev Mode: Testing tools
• ♿ Accessibility: Headless UI
• ✨ Animations: Framer Motion

🔧 6. C Client

• ⚡ Lightweight: Embedded systems
• 🔌 API Client: Backend integration
• 📦 Minimal: Few dependencies

🏗️ Architecture

_{TrueID System Architecture}

📁 Project Structure

TrueID/
├── 📱 android-app/         # Mobile application
│   ├── 📂 app/            # Android source
│   │   ├── 📂 src/        # Source code
│   │   └── 📄 build.gradle # Build config
│   └── 📂 gradle/         # Gradle wrapper
├── 🖥️ backend/            # Node.js server
│   ├── ⛓️ blockchain/     # Smart contracts
│   ├── ⚙️ config/         # Config files
│   ├── 🎮 controllers/    # API controllers
│   ├── 🔌 middleware/     # Express middleware
│   ├── 📊 models/         # Database models
│   ├── 🛣️ routes/         # API routes
│   ├── 🛠️ services/       # Business logic
│   └── 🧰 utils/          # Utilities
├── 🔧 c-client/           # C implementation
├── 💾 database/           # DB schemas
├── 🌐 frontend/           # React web app
├── 🏛️ government-portal/  # Admin dashboard
│   ├── 📂 public/         # Static assets
│   ├── 📂 src/            # React components
│   └── 📄 package.json    # Dependencies
└── 📜 scripts/            # Utilities

🚀 Getting Started

📋 Prerequisites

Node.js v14+	PostgreSQL v13+	Android Studio
JDK 8+	Metamask	Avalanche Fuji

⚙️ Installation

1. Clone git clone https://github.com/notcaliper/TrueID.git	2. Backend cd backend && npm install	3. Database cd database && npm run migrate
4. Frontend cd frontend && npm install	5. Portal cd government-portal && npm install	6. Deploy cd backend && npm run blockchain:deploy:fuji

⚙️ Configuration

🔐 Environment Variables

Backend (.env)

# Server Configuration
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

# Database Configuration
DB_USER=your_db_user
DB_HOST=localhost
DB_NAME=trueid_db
DB_PASSWORD=your_db_password
DB_PORT=5432

# Authentication
JWT_SECRET=your_jwt_secret
JWT_EXPIRATION=1h
REFRESH_TOKEN_SECRET=your_refresh_token_secret
REFRESH_TOKEN_EXPIRATION=7d

# Blockchain
BLOCKCHAIN_RPC_URL=https://api.avax-test.network/ext/bc/C/rpc
CONTRACT_ADDRESS=your_contract_address
ADMIN_WALLET_PRIVATE_KEY=your_private_key

Frontend (.env)

# API Configuration
REACT_APP_API_URL=http://localhost:5000

# Blockchain Configuration
REACT_APP_AVALANCHE_CONTRACT_ADDRESS=your_contract_address
REACT_APP_AVALANCHE_NETWORK=fuji
REACT_APP_AVALANCHE_RPC_URL=https://api.avax-test.network/ext/bc/C/rpc

Government Portal (.env)

# Server Configuration
PORT=8000

# API Configuration
REACT_APP_API_URL=http://localhost:5000
REACT_APP_AVALANCHE_CONTRACT_ADDRESS=your_contract_address

🏃‍♂️ Running the System

Backend cd backend && npm run dev	Frontend cd frontend && npm start	Portal cd government-portal && npm start
Dev Mode cd government-portal && npm run dev:mock	Android cd android-app && ./gradlew assembleDebug	Tests npm run test

🛡️ Security Features

🔒 Data Protection Biometric hashing End-to-end encryption	🔐 Authentication JWT with refresh Multi-factor auth	⛓️ Blockchain Immutable records Smart contracts
🛡️ Access Control Role-based permissions Rate limiting	📜 Compliance Data protection Security audits	🔍 Monitoring Audit trails Activity logging

👨‍💻 Development Guidelines

📝 Code Style

🎨 Formatting ESLint & Prettier	📚 Style Guide Airbnb JavaScript	📘 TypeScript Type safety
✅ Testing Unit tests	📖 Documentation API docs	🔍 Code Review Peer review

🔄 Git Workflow

🌿 Branches Feature branches

👥 Reviews PR reviews

📝 Commits Conventional

🧪 Testing

🧪 Unit Jest	🔄 Integration Supertest	🌐 E2E Cypress
📱 Mobile Espresso	⛓️ Smart Contracts Hardhat	📊 Coverage Reports

🤝 Contributing

1. 🍴 Fork Clone the repo	2. 🌿 Branch Create feature branch	3. 💾 Commit Make changes
4. 📤 Push To your branch	5. 🔄 PR Create pull request	6. ✅ Review Address feedback

💬 Support

GitHub Issues

Email Support

---

🛠️ Backend Interactive Setup Tool

TrueID provides an interactive setup wizard to simplify backend configuration, database setup, blockchain contract deployment, and admin creation.

🚀 Quickstart (Recommended)

cd backend
npm run setup
# or
node setup.js

What the setup tool does:

• Installs all backend dependencies (if needed)
• Asks for PostgreSQL connection info and tests the connection
• Creates the database if it doesn't exist
• Runs the schema and migrations
• Configures JWT secrets (auto-generates or lets you enter your own)
• Asks for Avalanche wallet private key and derives the address
• Optionally deploys the smart contract to Avalanche Fuji testnet
• Creates the initial admin account (argon2-hashed password)
• Writes the complete .env file (backs up old one if present)
• Prints a summary and next steps

You can re-run the setup tool any time to update your configuration.

---

Made with ❤️ by Akshay

_{Copyright © 2026 TrueID. All rights reserved.}