ArcherDB Documentation

ArcherDB is a distributed geospatial database built for real-time location tracking at scale. It combines the consistency guarantees of Viewstamped Replication (VSR) with a high-performance S2-based spatial index, enabling sub-millisecond queries across billions of location events.

Security and continuity controls are infrastructure-managed by default: authn/authz, TLS/mTLS, encryption at rest, and backup orchestration are expected to be enforced outside of ArcherDB itself.

Quick Links

For Developers

Tutorials

Learn ArcherDB step-by-step:

• Quickstart - Insert and query your first location in 5 minutes
• Getting Started - Comprehensive setup, SDK installation, and usage patterns

How-To Guides

Goal-oriented guides:

• SDK Retry Semantics - Configure retry behavior and handle errors
• Error Codes - Understand and troubleshoot errors
• Testing Guide - Run tests locally for all 5 SDKs
• Benchmark Guide - Run and interpret performance benchmarks
• Release Checklist - Must-do go/no-go checklist before calling ArcherDB released
• Java Publish Checklist - Separate maintainer checklist for Maven Central publication

Reference

Complete API and configuration documentation:

• API Reference - All operations with request/response details
• OpenAPI Specification - Machine-readable API definition
• Tier Profiles - Runtime/capacity presets and release artifact guidance
• Hardware Requirements - Minimum and recommended specs
• LSM Tuning - Storage engine configuration
• Journal Sizing - Write-ahead log configuration

SDK Documentation

Comprehensive guides for each language:

• SDK Overview - Choosing an SDK, feature matrix, common patterns
• SDK Comparison Matrix - Feature parity and code examples
• SDK Limitations - Known issues and workarounds
• Parity Matrix - Cross-SDK verification status
• SDK Comprehensive Test Report - Current SDK validation evidence

For Operators

Deployment

• Operations Runbook - Day-to-day operational procedures
• Capacity Planning - Sizing clusters for your workload
• Multi-Region Deployment - Design/reference guide; server runtime is not GA

Recovery & Continuity

• Backup Operations - External snapshot/backup integration guidance
• Disaster Recovery - Replica recovery and external restore procedures
• Upgrade Guide - Rolling upgrades and external rollback planning

Troubleshooting

• Troubleshooting Guide - Diagnose and resolve common issues
• Error Codes - Error reference with troubleshooting guidance

Alert Runbooks

Per-alert response guides linked from Prometheus alerts:

• Replica Down - When a replica is unreachable
• View Changes - Frequent leader elections
• Index Degraded - Index performance issues
• High Read Latency - Read latency triage
• High Write Latency - Write latency triage
• Disk Capacity - Disk capacity and fill-rate response
• Compaction Backlog - Storage compaction backlog response
• Kernel Crash Durability - Crash-durability harness guidance

Performance

• Benchmarks - Benchmark framework and results
• Benchmark Guide - Running and interpreting benchmarks
• Profiling - Performance profiling workflows
• Performance Tuning - Query and workload optimization
• LSM Tuning - Storage engine optimization

Testing & CI

• Testing Guide - Run all tests locally
• CI Tiers - Smoke, PR, nightly, weekly tiers
• curl Examples - Raw HTTP examples for all operations
• Protocol Reference - Wire format and data types

Understanding ArcherDB

Architecture and design:

• Architecture - System design, data flow, and component interactions
• VSR Understanding - How Viewstamped Replication provides consensus
• Durability Verification - How ArcherDB ensures data durability

Security

• Security Best Practices - Infrastructure security and trust-boundary model
• Encryption Guide - External encryption-at-rest controls
• Encryption Security - Data-protection model and non-goals

Internals

For contributors:

• Message Bus Errors - Network layer error handling
• Upstream Backports - Local patches carried from upstream dependencies

Release Notes

• CHANGELOG.md - Release history and notable changes
• FINALIZATION_PLAN.md - Release hardening and exit criteria

---

Documentation Coverage

All documentation requirements (DOCS-01 through DOCS-08) are complete:

See .planning/REQUIREMENTS.md for full traceability.

Edit this page