A high-performance temporal database with nanosecond-precision timestamps, unified file format, and world-class logging standards
✅ PRODUCTION CERTIFIED: EntityDB v2.34.6 has achieved corruption immunity through bounded resource management and architectural consistency.
🛡️ File Descriptor Mastery: 64% reduction (22→8) with mathematical guarantee preventing OS-level race conditions.
🚀 XVC Pattern: ParallelQueryProcessor transformed from unbounded risk to bounded reliability - revolutionary achievement.
📊 Quality Excellence: All 8 quality laws satisfied with bar-raising solution eliminating file descriptor exhaustion corruption.
🚀 EXTREME VIBE CODING (XVC): This entire codebase has been developed using Extreme Vibe Coding methodology.
Learn more: https://github.com/osakka/xvc
XVC Philosophy: High-velocity development with extreme attention to detail, surgical precision, and world-class quality standards.
EntityDB is a high-performance temporal database that stores everything as entities with nanosecond-precision timestamps. Built with a unified binary format (EUFF), embedded Write-Ahead Logging, and enterprise-grade features, it provides complete time-travel capabilities, tag-based RBAC, and production-ready reliability.
ParallelQueryProcessor Corruption Elimination: Revolutionary bounded resource management eliminating file descriptor exhaustion corruption through ReaderPool integration. 64% reduction in file descriptors (22→8) with mathematical guarantee of bounded usage.
OS-Level Stability: Complete elimination of kernel race conditions in file operations preventing astronomical offset corruption. Architectural consistency achieved through single source of truth reader management.
Production Excellence: HeaderSync automatic recovery combined with bounded resources creates corruption impossible by design. All 8 quality laws satisfied with bar-raising architectural solution.
v2.32.6: Database file unification - single .edb format eliminates separate database, WAL, and index files. 66% reduction in file handles with simplified backup and recovery operations.
v2.32.5: Worca Workforce Orchestrator Platform - Full-stack workforce management application demonstrating EntityDB as a complete application platform.
v2.32.4: Technical debt elimination - comprehensive codebase cleanup with zero TODO/FIXME/XXX/HACK items remaining.
BREAKING CHANGE in v2.29.0: Authentication architecture changed. User credentials now stored directly in entity content field. NO BACKWARD COMPATIBILITY - all users must be recreated.
- 🕒 Time-Travel Queries: Complete temporal functionality with as-of, history, diff, and changes operations
- ⏱️ Nanosecond Precision: Every tag timestamped with nanosecond accuracy for precise temporal operations
- 📊 Temporal Analytics: Historical data analysis and trend identification capabilities
- 🔄 Immutable History: Complete audit trail with immutable historical records
- 📁 Single File Format: Unified
.edbfiles contain data, WAL, and indexes in single source of truth - 🏢 Pure Entity Model: Everything is an entity with tags - no tables, schemas, or complexity
- 🚀 High Performance: 256-shard concurrent indexing, memory-mapped files, O(1) tag caching
- 🛡️ Self-Healing: Automatic corruption recovery and index rebuilding capabilities
- 🔒 Tag-Based RBAC: Comprehensive role-based access control with fine-grained permissions
- 🔐 JWT Authentication: Secure token-based authentication with session management
- 🛡️ Enterprise Integration: SSL/TLS, comprehensive audit logging, security hardening
- 👥 Multi-Tenancy: Complete dataset isolation for multi-tenant deployments
- 📊 World-Class Observability: 100% compliant enterprise logging standards with 10 trace subsystems and dynamic configuration
- ⚙️ Zero Configuration: Intelligent defaults with comprehensive three-tier configuration system (Database > CLI > Environment)
- 🔧 Operational Excellence: Complete health monitoring, Prometheus metrics, performance optimization, and self-healing architecture
- 🚀 Battle-Tested: Comprehensive real-world scenario testing across 5 demanding use cases with proven reliability
- Go 1.21+ for development
- Linux/macOS/Windows support
- 1GB RAM minimum (4GB+ recommended for production)
# Clone the repository
git clone https://git.home.arpa/itdlabs/entitydb.git
cd entitydb
# Build the server (clean build with zero warnings)
cd src && make && cd ..
# Start the server (creates admin/admin user automatically)
./bin/entitydbd.sh start
# Verify server is running
curl -k https://localhost:8085/health# Access the web dashboard
# URL: https://localhost:8085
# Credentials: admin/admin (change in production!)
# API authentication
curl -k -X POST https://localhost:8085/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"admin"}'
# Create your first entity
curl -k -X POST https://localhost:8085/api/v1/entities/create \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"tags":["name:my-entity","type:demo"],"content":"SGVsbG8gV29ybGQ="}'
# Query entities
curl -k https://localhost:8085/api/v1/entities/list \
-H "Authorization: Bearer YOUR_TOKEN"EntityDB features world-class documentation with IEEE 1063-2001 compliance and 100% technical accuracy:
- Complete Documentation Library - Master navigation and world-class documentation
- Installation Guide - Production-ready setup in 5 minutes
- Quick Start Tutorial - Your first entities and temporal queries
- Core Concepts - Master the fundamentals
- API Overview - Complete REST API with 58+ endpoints
- Authentication Guide - Secure JWT-based authentication
- Entity Operations - CRUD operations and examples
- Temporal Queries - Time-travel and advanced querying
- Admin Guide - Complete operations and deployment guide
- Security Configuration - Enterprise security hardening
- Production Checklist - Comprehensive deployment guide
- Monitoring Guide - Observability and metrics
- System Architecture - Complete technical architecture
- Developer Guide - Development workflow and contribution
- Architecture Decisions - 6 ADRs and 45+ technical decisions documented
- Technical Reference - Complete specifications and configuration
// Time-travel to any point in history
GET /api/v1/entities/as-of?timestamp=2025-01-01T00:00:00Z&id=entity-123
// Get complete change history
GET /api/v1/entities/history?id=entity-123
// Compare between two time points
GET /api/v1/entities/diff?id=entity-123&from=2025-01-01T00:00:00Z&to=2025-02-01T00:00:00Z
// Track changes since timestamp
GET /api/v1/entities/changes?since=2025-01-01T00:00:00Z# User with comprehensive permissions
rbac:role:admin
rbac:perm:*
# User with entity view permissions only
rbac:role:viewer
rbac:perm:entity:view
# User with specific dataset access
rbac:role:analyst
rbac:perm:entity:view
rbac:perm:dataset:analytics:*# Environment variables for production optimization
export ENTITYDB_HIGH_PERFORMANCE=true
export ENTITYDB_LOG_LEVEL=info
export ENTITYDB_TRACE_SUBSYSTEMS=auth,storage
export ENTITYDB_USE_SSL=true
export ENTITYDB_PORT=8085- Audit Systems: Complete temporal audit trails with nanosecond precision
- Configuration Management: Track all configuration changes over time
- Financial Systems: Immutable transaction history with time-travel capabilities
- Compliance Reporting: Historical data analysis for regulatory requirements
- Application Backend: Entity-based data modeling without schema constraints
- API Gateway: Unified data access with comprehensive RBAC
- Microservices: Temporal data sharing between distributed services
- Analytics Platform: Historical trend analysis and data mining
- System Monitoring: Time-series metrics storage with temporal queries
- Performance Analysis: Historical performance trending and optimization
- Incident Response: Complete timeline reconstruction for root cause analysis
- Capacity Planning: Historical usage patterns for resource planning
- Entity Creation: ~95ms average with batching optimization
- Tag Lookups: ~68ms average with O(1) caching
- Temporal Queries: 18-38ms complex queries (60%+ improvement)
- Memory Usage: 51MB stable with effective garbage collection
- Concurrent Operations: Excellent performance under load
- File Size: No practical limits with autochunking (>4MB default)
- Entity Count: Tested with millions of entities
- Temporal History: Unlimited historical retention with configurable cleanup
- Concurrent Users: Multi-user collaboration with session management
- JWT Token Authentication: Secure, stateless authentication
- Session Management: TTL-based sessions with automatic cleanup
- Tag-Based RBAC: Fine-grained permission system
- Multi-Factor Ready: Foundation for MFA implementation
- Encryption at Rest: Binary format with optional encryption
- TLS/SSL: Secure communications by default
- Input Validation: Comprehensive input sanitization
- Audit Logging: Complete security event tracking
- SSO Ready: Foundation for single sign-on integration
- LDAP Compatible: External authentication system integration
- Security Headers: Comprehensive HTTP security headers
- CORS Configuration: Flexible cross-origin request handling
# Comprehensive health check
curl -k https://localhost:8085/health
# Prometheus metrics
curl -k https://localhost:8085/metrics
# System metrics
curl -k https://localhost:8085/api/v1/system/metrics- 100% Enterprise Compliance: Complete audit of 126+ source files achieving enterprise logging standards
- Revolutionary Architecture: Audience-optimized messaging for developers vs production SREs
- Dynamic Configuration: Runtime log level and trace subsystem adjustment via API, CLI, and environment
- Zero Performance Overhead: Thread-safe atomic implementation with no impact when disabled
- Industry Leadership: Professional format with structured contextual information and automatic file/function/line data
- System Metrics: Memory, CPU, storage, and performance metrics
- Application Metrics: Entity operations, query performance, error rates
- Security Metrics: Authentication events, permission checks, security events
- Custom Metrics: Application-specific metrics via generic metrics API
EntityDB welcomes contributions from the community:
# Clone and setup development environment
git clone https://git.home.arpa/itdlabs/entitydb.git
cd entitydb
# Follow developer guide for complete setup
./docs/developer-guide/01-contributing.md- Core Database: Temporal storage, indexing, and query optimization
- API Development: REST endpoint development and enhancement
- Security: RBAC, authentication, and security hardening
- Documentation: Technical writing and documentation improvements
- Testing: Test coverage, performance testing, and quality assurance
- Code Quality: Clean code principles, comprehensive testing
- Documentation: IEEE 1063-2001 compliance, technical accuracy
- Git Workflow: Structured branching, commit standards, code review
- Security: Secure coding practices, vulnerability assessment
- Version: v2.34.6 (ParallelQueryProcessor File Descriptor Corruption Elimination)
- Stability: Production Ready - Battle-tested across multiple real-world scenarios
- Test Coverage: Comprehensive test suite with e-commerce, IoT, SaaS, and trading system validation
- Documentation: IEEE 1063-2001 compliant with systematic accuracy verification
- Code Quality: Clean codebase with comprehensive audit and technical debt elimination
- Enhanced API Coverage: Complete documentation of all endpoints
- Performance Optimization: Continued optimization for large-scale deployments
- Security Enhancements: Advanced security features and compliance
- Ecosystem Growth: Tools, integrations, and community contributions
- Community Support: GitHub issues, discussions, and community forums
- Documentation: Comprehensive guides, API reference, and tutorials
- Professional Support: Enterprise support options available
- Training: Workshops, tutorials, and certification programs
- 📘 Documentation - World-class technical documentation
- 🐛 Issues - Bug reports and feature requests
- 💬 Discussions - Community Q&A and discussions
- 📧 Support - Direct technical support
- Installation Guide - Get started in 5 minutes
- API Reference - Complete API documentation
- Configuration Guide - Complete configuration options
- Troubleshooting - Common issues and solutions
EntityDB is licensed under the MIT License. See LICENSE for details.
- Temporal Database: Nanosecond-precision timestamps with complete time-travel capabilities
- Production Architecture: Tested across multiple real-world scenarios with reliable performance
- Clean Codebase: Systematic technical debt elimination and comprehensive audit
- Logging Standards: Enterprise logging compliance with structured format and dynamic configuration
- IEEE 1063-2001 Compliance: Professional technical documentation standards with accuracy verification
- Comprehensive Library: Systematic taxonomy and single source of truth architecture
- Technical Accuracy: 100% verification framework ensuring documentation matches implementation
- Unified File Format: Single-file architecture eliminating separate database, WAL, and index files
- Self-Healing: Automatic corruption recovery and intelligent index rebuilding capabilities
- Performance Optimization: Complex query optimization with O(1) tag caching and 256-shard indexing
EntityDB - Where temporal data meets enterprise excellence. Built for the future of data storage and time-travel capabilities.
For the latest updates and detailed changelog, see CHANGELOG.md
Repository: git.home.arpa/itdlabs/entitydb | Version: v2.34.6 | Build: Clean, Zero Warnings