Blockchain-Based Smart Document Verification and Approval System

A production-ready full-stack application for document verification using blockchain technology. Documents are hashed with SHA-256, stored off-chain in S3-compatible storage, and their hashes are registered on the Ethereum blockchain for immutable verification.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js)                       │
│     React 18 │ TypeScript │ TailwindCSS │ ethers.js │ Zustand   │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Backend API (Spring Boot)                   │
│   Spring Security │ JWT │ web3j │ JPA │ SHA-256 │ S3 Client     │
└─────────────────────────────────────────────────────────────────┘
          │                    │                    │
          ▼                    ▼                    ▼
┌──────────────┐    ┌──────────────┐    ┌───────────────────┐
│  PostgreSQL  │    │ MinIO / S3   │    │ Ethereum Network  │
│   Database   │    │   Storage    │    │  Smart Contract   │
└──────────────┘    └──────────────┘    └───────────────────┘

✨ Features

• Document Upload: Upload PDF documents (max 50MB)
• SHA-256 Hashing: Automatic content hashing for integrity verification
• Blockchain Registration: Hash registered on Ethereum (Sepolia testnet)
• Role-Based Access: User, Approver, and Admin roles with JWT authentication
• Approval Workflow: Multi-step approval process with blockchain recording
• Public Verification: Anyone can verify document authenticity
• MetaMask Integration: Connect wallet for blockchain interactions
• Off-Chain Storage: Documents stored in S3-compatible storage (MinIO)

🛠️ Tech Stack

Backend

• Java 17 with Spring Boot 3.2.2
• Spring Security 6.x with JWT (jjwt 0.12.3)
• Spring Data JPA with PostgreSQL
• web3j 4.10.3 for Ethereum integration
• AWS SDK for S3 storage

Frontend

• Next.js 14.1.0 with React 18
• TypeScript 5.x
• TailwindCSS 3.4.1
• ethers.js 6.9.2 for blockchain
• Zustand for state management
• React Query for data fetching

Blockchain

• Solidity 0.8.20
• Hardhat development environment
• OpenZeppelin contracts 5.x
• Sepolia testnet deployment

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for local development)
• Java 17+ (for local development)
• MetaMask wallet

Using Docker (Recommended)

1. Clone and configure

cd blockchain_project
cp .env.example .env
# Edit .env with your configuration

2. Start all services

docker-compose up -d

3. Access the application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080
• MinIO Console: http://localhost:9001

Local Development

Backend

cd backend
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Frontend

cd frontend
npm install
npm run dev

Smart Contract

cd contracts
npm install
npx hardhat compile

# Deploy to Sepolia
npx hardhat run scripts/deploy.js --network sepolia

📁 Project Structure

blockchain_project/
├── memory-bank/           # Project documentation
│   ├── projectbrief.md
│   ├── productContext.md
│   ├── systemPatterns.md
│   ├── techContext.md
│   ├── activeContext.md
│   └── progress.md
├── backend/               # Spring Boot API
│   ├── src/main/java/com/docverify/
│   │   ├── entity/        # JPA entities
│   │   ├── repository/    # Data repositories
│   │   ├── service/       # Business logic
│   │   ├── controller/    # REST endpoints
│   │   ├── security/      # JWT & auth
│   │   ├── config/        # Configuration
│   │   ├── dto/           # Request/Response DTOs
│   │   └── exception/     # Error handling
│   └── pom.xml
├── frontend/              # Next.js application
│   ├── src/
│   │   ├── app/           # Pages (App Router)
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom hooks
│   │   ├── lib/           # Utilities & API
│   │   └── store/         # Zustand stores
│   └── package.json
├── contracts/             # Solidity smart contracts
│   ├── contracts/
│   │   └── DocumentVerification.sol
│   ├── scripts/
│   │   └── deploy.js
│   └── hardhat.config.js
├── docker-compose.yml
└── README.md

🔐 Authentication

Demo Accounts

Role	Email	Password
Admin	admin@docverify.com	admin123
Approver	approver@docverify.com	approver123
User	user@docverify.com	user123

API Authentication

All protected endpoints require a JWT token in the Authorization header:

Authorization: Bearer <access_token>

📡 API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login and get tokens
• POST /api/auth/refresh - Refresh access token

Documents

• POST /api/documents/upload - Upload document (multipart)
• GET /api/documents/my - Get user's documents
• GET /api/documents/{id} - Get document details
• GET /api/documents/{id}/download - Download document

Approvals

• GET /api/approvals/pending - Get pending approvals
• POST /api/approvals/{id}/approve - Approve document
• POST /api/approvals/{id}/reject - Reject document

Verification

• POST /api/verification/verify-hash - Verify by hash
• POST /api/verification/verify-file - Verify by file

Admin

• GET /api/admin/users - List all users
• PUT /api/admin/users/{id}/enable - Enable user
• PUT /api/admin/users/{id}/disable - Disable user
• POST /api/admin/users/{id}/roles - Add role

🔗 Smart Contract

The DocumentVerification contract provides:

• registerDocument(bytes32 hash, string storageKey) - Register document
• approveDocument(bytes32 hash) - Approve document
• rejectDocument(bytes32 hash, string reason) - Reject document
• verifyDocument(bytes32 hash) - Check document status
• documentExists(bytes32 hash) - Check if registered

Events

• DocumentRegistered(bytes32 indexed hash, string storageKey, address registrant, uint256 timestamp)
• DocumentApproved(bytes32 indexed hash, address approver, uint256 timestamp)
• DocumentRejected(bytes32 indexed hash, address approver, string reason, uint256 timestamp)

🧪 Testing

Backend Tests

cd backend
./mvnw test

Contract Tests

cd contracts
npx hardhat test

Frontend Tests

cd frontend
npm test

🚢 Deployment

Production Checklist

1. Set strong JWT secret (min 256-bit)
2. Configure production database
3. Set up AWS S3 or production MinIO
4. Deploy contract to mainnet/L2
5. Configure HTTPS with SSL certificates
6. Set up monitoring and logging
7. Configure rate limiting
8. Set up backup procedures

Environment Variables

See .env.example for all required configuration.

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

---

Built with ❤️ using Spring Boot, Next.js, and Ethereum