Blockchain Explorer

A full-stack real-time blockchain event indexing and analytics dashboard built with modern web technologies.

🚀 Features

⚡ Real-time Event Indexing - Automatic blockchain event monitoring and indexing
📊 Interactive Dashboard - Beautiful visualizations with Recharts
🔄 Live Updates - WebSocket-powered real-time data streaming
💾 Efficient Caching - In-memory LRU cache with 8-10x performance improvement
📦 Batch Processing - Optimized event processing (50 events/batch)
🔍 Advanced Filtering - Search and filter events by multiple criteria
📈 Analytics - Player leaderboards, event distribution, activity timelines
🏥 Health Monitoring - Comprehensive health checks and status reporting
🔐 Production-Grade Practices - Error handling, retry logic, graceful shutdown
🐳 Docker Support - One-command deployment with hot reload
🤖 CI/CD Ready - GitHub Actions workflows included
📝 Comprehensive Docs - 4,600+ lines of documentation across 7 guides

🛠 Tech Stack

Layer	Technology	Version
Frontend	React	19.0.0
	TypeScript	5.7.2
	Vite	7.1.10
	Tailwind CSS	4.1.14
	Recharts	3.2.1
	Socket.IO Client	4.8.1
Backend	Node.js	22.11.0
	Express	5.1.0
	TypeScript	5.7.2
	Socket.IO	4.8.1
	ethers.js	6.15.0
Database	PostgreSQL	18.0
	pg	8.13.1
Blockchain	Hardhat	3.0.4
	Solidity	0.8.28
DevOps	Docker	Latest
	Docker Compose	v2+

⚡ Quick Start

Option 1: Automated Setup (Recommended)

# Clone repository
git clone https://github.com/Exalt24/Blockchain-Explorer.git
cd Blockchain-Explorer

# One-command setup (5-10 minutes)
.\scripts\setup.ps1

# Open dashboard
Start-Process http://localhost:3000

Option 2: Manual Docker Setup

# 1. Start all services
docker-compose up -d

# 2. Run database migrations
docker-compose exec backend npm run migrate

# 3. Deploy smart contracts
docker-compose exec hardhat npm run deploy-docker

# 4. Restart backend
docker-compose restart backend

# 5. Generate test events (optional)
docker-compose exec hardhat npm run generate-events

Access the application:

🌐 Frontend: http://localhost:3000
🔌 Backend API: http://localhost:4000/api
💚 Health Check: http://localhost:4000/health
⛓️ Hardhat RPC: http://localhost:8545

📁 Project Structure

blockchain-explorer/
├── backend/              # Node.js/Express backend
│   ├── src/
│   │   ├── api/         # REST API routes
│   │   ├── config/      # Configuration files
│   │   ├── services/    # Business logic
│   │   ├── types/       # TypeScript types
│   │   ├── utils/       # Utility functions
│   │   └── websocket/   # WebSocket server
│   ├── migrations/      # Database migrations
│   └── tests/           # Test files
├── contracts/           # Smart contracts
│   ├── contracts/       # Solidity files
│   ├── ignition/        # Deployment scripts
│   ├── scripts/         # Helper scripts
│   └── test/            # Contract tests
├── frontend/            # React frontend
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── contexts/    # Context providers
│   │   ├── hooks/       # Custom hooks
│   │   ├── services/    # API services
│   │   └── types/       # TypeScript types
│   ├── public/          # Static assets
│   └── nginx.conf       # Nginx config for the production frontend image
├── docker/              # Docker configuration
│   ├── backend.Dockerfile
│   ├── contracts.Dockerfile
│   └── frontend.Dockerfile
├── scripts/             # Automation scripts (PowerShell)
│   ├── setup.ps1
│   ├── start-dev.ps1
│   ├── health-check.ps1
│   └── ... (7 more)
├── docs/                # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT.md
│   ├── TESTING.md
│   ├── TROUBLESHOOTING.md
│   ├── MONITORING.md
│   └── PRODUCTION-CHECKLIST.md
├── .github/workflows/   # CI/CD pipelines
│   ├── ci.yml
│   └── deploy.yml
├── docker-compose.yml       # Development environment
├── docker-compose.prod.yml  # Production environment
├── CHANGELOG.md
└── README.md

📚 Documentation

Comprehensive documentation available in the /docs directory:

API Reference - Complete API documentation with examples
Architecture - System design and component interactions
Deployment - Development and production deployment
Testing - Integration and performance testing
Monitoring - Monitoring and alerting setup
Troubleshooting - Common issues and solutions
Production Checklist - Pre-launch checklist

🤖 Development Scripts

PowerShell automation scripts for streamlined development:

# Setup & Management
.\scripts\setup.ps1              # Complete first-time setup
.\scripts\start-dev.ps1          # Start all services
.\scripts\stop-dev.ps1           # Stop services (keeps data)
.\scripts\reset-all.ps1          # Complete reset (destroys data)

# Utilities
.\scripts\deploy-contract.ps1   # Deploy smart contract
.\scripts\generate-events.ps1   # Generate test events
.\scripts\health-check.ps1      # System health check
.\scripts\view-logs.ps1         # View service logs
.\scripts\run-tests.ps1         # Run test suites
.\scripts\db-operations.ps1     # Database management

See DEPLOYMENT.md for detailed script documentation.

🔌 API Reference

REST Endpoints

GET  /api/events                # List events (paginated, filterable)
GET  /api/events/tx/:hash       # Events by transaction
GET  /api/events/block/:block   # Events by block
GET  /api/stats                 # Platform statistics
GET  /api/leaderboard           # Player rankings
GET  /api/stats/distribution    # Event type breakdown
GET  /api/stats/timeline        # Activity over time
GET  /health                    # System health

WebSocket Events

// Client → Server
socket.emit('ping');

// Server → Client
socket.on('newEvent', (event) => { /* ... */ });
socket.on('statsUpdate', (stats) => { /* ... */ });
socket.on('blockUpdate', (block) => { /* ... */ });

See API.md for complete API documentation.

🧪 Testing

Quick Diagnostics

cd backend

# Quick API smoke test
npm run diagnose-api

Test Suites

# Unit Tests
npm run test:health      # Health monitoring
npm run test:cache       # Cache service
npm run test:batch       # Batch processor

# Integration Tests
npm run test:e2e         # End-to-end flow
npm run test:api-integration
npm run test:concurrent
npm run test:ws-stress

# Performance Tests
npm run test:load        # Load testing
npm run test:cache-perf  # Cache performance

Contract Tests

cd contracts
npm test                 # All 16 tests

Test Coverage: 42+ automated tests across backend and contracts

See TESTING.md for detailed testing documentation.

🚀 Deployment

Development (Docker)

# Start environment
docker-compose up -d

# Stop environment
docker-compose down

Production (Docker)

# Create production .env
cp backend/.env.production.docker backend/.env
nano backend/.env

# Deploy
docker-compose -f docker-compose.prod.yml up -d

Production (PM2 + Nginx)

# Server setup
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs postgresql-18 nginx

# Clone and setup
git clone https://github.com/Exalt24/Blockchain-Explorer.git /opt/blockchain-explorer
cd /opt/blockchain-explorer
npm run setup # Helper script

# Deploy with PM2
cd backend
npm install --production
npm run build
pm2 start ecosystem.config.js --env production
pm2 save

# Setup Nginx + SSL
sudo certbot --nginx -d yourdomain.com

See DEPLOYMENT.md for complete deployment guide.

⚡ Performance

Benchmarks

API Response Times:

Cached: 5-20ms (avg)
Uncached: 50-150ms (avg)
P95: <200ms
P99: <500ms

Throughput:

200-500 req/s (single instance)
50+ concurrent WebSocket connections
100+ events/second indexing

Cache Performance:

Hit rate: 80-90%
Performance improvement: 8-10x
Speedup: Cache hits are 8-10x faster than misses

Optimizations

✅ Database:

Connection pooling (max 20)
Strategic indexes
Batch inserts (50 events)
Query optimization

✅ Caching:

In-memory LRU cache
TTL-based expiration (5-60s)
Automatic cleanup
WebSocket throttling (1/s for blocks)

✅ Processing:

Batch processing (50 events/batch)
Auto-flush (1s interval)
Error recovery with retry logic

🏗 Architecture

Frontend (React 19)
        ↓ HTTP/WebSocket
Backend (Node.js + Express 5)
        ↓
    ┌───┴────┐
    │ Services│
    │┌───────┐│
    ││EventProc││
    ││ Stats  ││
    ││ Cache  ││
    │└───────┘│
    └────┬────┘
         ↓
    ┌─────────┐
    │PostgreSQL│
    │ Database │
    └─────────┘

Backend ← ethers.js → Blockchain (Hardhat/Ethereum)

See ARCHITECTURE.md for detailed architecture documentation.

🔍 Monitoring

Health Check

curl http://localhost:4000/health

# Returns comprehensive system status:
{
  "status": "healthy",
  "services": {
    "database": { "connected": true, "latency": 5 },
    "blockchain": { "connected": true, "latestBlock": "12345" },
    "eventListener": { "running": true, "errorCount": 0 },
    "websocket": { "enabled": true, "connectedClients": 3 },
    "cache": { "enabled": true, "hitRate": 0.85 }
  }
}

Recommended Stack

Metrics: Prometheus + Grafana
Logs: PM2 logs or ELK stack
APM: PM2 Plus, New Relic, or Datadog
Uptime: UptimeRobot or Pingdom

See MONITORING.md for monitoring setup guide.

🐛 Troubleshooting

Common Issues

Backend won't start:

# Check port availability
netstat -ano | findstr :4000

# Reinstall dependencies
rm -rf node_modules && npm install

# Verify environment variables
cat .env

Database connection failed:

# Check PostgreSQL is running
docker-compose ps postgres
docker-compose restart postgres

# Test connection manually
psql -h localhost -U postgres -d blockchain_explorer

No events indexed:

# Generate test events
cd contracts && npm run generate-events

# Check EventListener status
curl http://localhost:4000/health | jq '.services.eventListener'

# Verify CONTRACT_ADDRESS is set
grep CONTRACT_ADDRESS backend/.env

See TROUBLESHOOTING.md for complete troubleshooting guide.

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style
Write tests for new features
Update documentation
Ensure all tests pass
Keep commits atomic and descriptive

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with modern web3 stack
Inspired by blockchain explorers like Etherscan
Uses best practices from React, Node.js, and PostgreSQL communities

📞 Support

Documentation: Check /docs directory
Issues: Open an issue on GitHub
Discussions: Start a discussion on GitHub

🎯 Project Status

Current Version: 1.0.0

This is a portfolio project that runs locally via Docker. There is no hosted demo instance, so the "production" references below describe the configuration and practices baked into the codebase (prod Docker compose, Nginx config, error handling, health checks), not a live deployment.

✅ Completed Phases

✅ Phase 0: Project Setup and Dependencies
✅ Phase 1: Database Schema and Smart Contract
✅ Phase 2: Backend Service (Event Indexer + REST API)
✅ Phase 3: WebSocket Real-Time Layer
✅ Phase 4: Frontend Dashboard (React 19 + Recharts)
✅ Phase 5: Integration and Testing
✅ Phase 6: Docker and Production Readiness

🎉 Production-Ready Configuration

✅ Full-stack application functional
✅ Real-time event indexing
✅ Interactive dashboard
✅ Docker development environment
✅ Docker production configuration
✅ Comprehensive testing (42+ tests)
✅ Complete documentation (4,600+ lines)
✅ Performance optimized (cache, batch processing)
✅ Error handling and retry logic
✅ Health monitoring
✅ Resource limits configured
✅ Production-ready Nginx config
✅ PowerShell automation scripts
✅ CI/CD pipeline templates
✅ Production readiness checklist

🔮 Roadmap

Short Term (v1.1.0)

Redis integration for distributed cache
Prometheus metrics export
Grafana dashboards
Rate limiting middleware
GraphQL API

Medium Term (v1.2.0)

Multi-chain support
Advanced analytics
Data export features
Event notifications
Mobile-responsive improvements

Long Term (v2.0.0)

Machine learning insights
Mobile app (React Native)
Plugin system
Advanced filtering and search

Built with ❤️ for the Web3 community

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
backend		backend
contracts		contracts
docker		docker
docs		docs
frontend		frontend
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation