developer-guide

Developer Guide

Version: v2.34.0 | Last Updated: 2025-06-22 | Status: AUTHORITATIVE

Welcome to the EntityDB Developer Guide. This section provides comprehensive development and contribution guidelines for building with and contributing to EntityDB.

Quick Navigation

Development Setup

• Contributing Guidelines - Setup, prerequisites, and contribution process
• Git Workflow - Git practices, branching, and state tracking
• Logging Standards - Logging conventions and best practices
• Configuration Management - Configuration system and environment setup

Development Resources

• Documentation Architecture - Documentation structure and standards
• Maintenance Guidelines - Project maintenance procedures
• Quick Maintenance Checklist - Common maintenance tasks

Developer Journey

New Contributors

1. Setup: Start with Contributing Guidelines
2. Standards: Learn Logging Standards and Configuration Management
3. Workflow: Follow Git Workflow

Active Developers

• Daily Development: Git Workflow and Configuration Management
• Documentation: Documentation Architecture
• Maintenance: Maintenance Guidelines

Development Environment

Prerequisites

• Go 1.21+ for server development
• Node.js 18+ for frontend development
• Git with proper configuration
• Development tools (see setup guide)

Architecture Overview

EntityDB Development Stack:
├── Go Server (src/)
├── JavaScript Frontend (share/htdocs/)
├── Documentation (docs/)
├── Testing Framework (tests/)
└── Development Tools (tools/)

Key Development Areas

Backend Development

• Core Engine: Temporal database implementation
• API Layer: REST endpoints and business logic
• Storage: Binary format and WAL implementation
• Performance: Optimization and caching

Frontend Development

• Dashboard: Web interface using Alpine.js
• Worca Platform: Workforce management application
• API Integration: Client-side data management

Documentation

• Technical Writing: Following IEEE standards
• API Documentation: Swagger/OpenAPI specifications
• User Guides: Task-oriented documentation

Code Quality Standards

Technical Requirements

• Test Coverage: >80% for new code
• Performance: Sub-millisecond query targets
• Security: RBAC enforcement throughout
• Documentation: All public APIs documented

Review Process

1. Code Review: Peer review for all changes
2. Testing: Automated test suite passage
3. Documentation: Updated docs for feature changes
4. Performance: Benchmarking for critical paths

Development Tools

Built-in Tools

• Make Targets: make dev, make test, make lint
• Code Generation: Swagger docs, mock generation
• Testing: Unit, integration, and performance tests
• Debugging: Comprehensive logging and tracing

External Tools

• IDE Integration: VS Code configuration provided
• Git Hooks: Pre-commit quality checks
• CI/CD: Automated testing and deployment
• Monitoring: Development metrics and profiling

Common Development Tasks

Adding Features

1. Design documentation (ADR if architectural)
2. Implement with tests
3. Update API documentation
4. Performance validation
5. User guide updates

Bug Fixes

1. Reproduce with test case
2. Root cause analysis
3. Minimal fix implementation
4. Regression test addition
5. Documentation updates

Performance Optimization

1. Benchmark current performance
2. Profile bottlenecks
3. Implement optimizations
4. Validate improvements
5. Document changes

Support and Resources

• Technical Questions: Use GitHub discussions
• Bug Reports: GitHub issues with template
• Feature Requests: RFC process via issues
• Documentation Issues: Direct PR submissions

Internal Resources

• Architecture: Architecture Guide
• API Reference: API Documentation
• Admin Operations: Admin Guide

---

This developer guide covers EntityDB v2.32.5 development. For contribution guidelines, see Contributing Guidelines.