Date: March 2026 | Status: Complete Research & Implementation Ready | Author: Research Team

This documentation suite provides comprehensive guidance for implementing a local-first Rust platform with persistent messaging, caching, graph databases, object storage, and container orchestration. All recommendations are current as of March 2026 and tested against production workloads.

Crate:       async-nats = "0.35"
Protocol:    NATS 2.x (Jetstream v2)
Runtime:     Tokio-based async
License:     Apache 2.0 (open source)
Performance: 1M+ msgs/sec, sub-ms latency

Key Features:

• Exactly-once delivery semantics
• Persistent streams with configurable retention
• Pull and push consumer patterns
• Built-in clustering for HA
• Monitoring endpoint at :8222

Best For: Feature state transitions, WP event ordering, cross-project coordination

Getting Started: See LOCAL_FIRST_TECH_RESEARCH.md § 1 for detailed API patterns and configuration

Primary:     Dragonfly 1.3+ (single binary)
Fallback:    Valkey 8.0+ (Redis fork, open source)
Client:      redis = "0.25", bb8-redis = "0.16"
Protocol:    Redis Protocol v3 (100% compatible)
Runtime:     Async compatible
License:     BSL (Dragonfly) → LGPL (Valkey)
Performance: 20-50% better memory efficiency than Redis

Use Cases:

• Snapshot caching with TTL (SET + expiry)
• Rate limiting (INCR + time windows)
• Session state (HSET with field structure)
• Feature flag caching
• Dependency graph cache (ZSET for versioning)

Dragonfly Advantages:

• Multi-threaded (leverages modern CPUs)
• Single binary distribution
• 50ms startup vs 200ms for Redis
• Superior memory pooling

Fallback Strategy: If BSL licensing becomes problematic, swap to Valkey (100% API compatible)

Getting Started: See LOCAL_FIRST_QUICK_REFERENCE.md § 2 for integration patterns

Crate:       neo4rs = "0.7"
Protocol:    Bolt v4.4 (v5.x compatible)
Runtime:     Tokio-based async
Version:     Neo4j 5.20+ Community
License:     Community Edition free for development
Performance: O(1) relationship traversal

Modeling Capability:

• Feature → WorkPackage relationships
• Dependency graphs (DEPENDS_ON, BLOCKS, RELATES_TO)
• Cross-project artifact links
• Shortest path finding (cycle detection)
• Full ACID transactions

Why Neo4j over alternatives:

• Purpose-built for graph queries (not relational)
• Browser UI for development exploration
• Mature Rust driver with connection pooling
• 15+ years production history
• Constraint and index support

Alternatives Considered (Not recommended):

• SurrealDB: Still alpha, limited graph support
• EdgeDB: PostgreSQL-based, weaker graph indexing
• SQLite + Recursive CTEs: File-based limits scale, no native graph indexing
• TigerGraph: Enterprise-focused, not community-suitable

Getting Started: See LOCAL_FIRST_EXAMPLE_IMPLEMENTATION.md § 5 for full Neo4j integration

Crate:       aws-sdk-s3 = "1.15" (recommended)
Alternative: minio-rs (officially maintained by MinIO)
Protocol:    S3 v4 (100% compatible)
Runtime:     Async compatible
Distribution: Single binary (Go)
License:     AGPL (MinIO) / Apache 2.0 (AWS SDK)

Capabilities:

• Multi-part uploads with resume
• Metadata and tagging
• Versioning and lifecycle policies
• Server-side encryption
• Batch operations
• Bucket policies and access controls

Local Standalone Mode:

• No external dependencies
• Embedded or containerized
• Console UI at :9001
• Hot-reload configuration

Getting Started: See LOCAL_FIRST_QUICK_REFERENCE.md § 4 for S3 client patterns

Tool:        process-compose = "1.7+"
Config:      process-compose.yml (YAML)
Features:    Service dependencies, health checks, file watch
Runtime:     Native OS processes (no Docker daemon required)
Performance: ~1-2 seconds startup for full stack

Dependency Ordering:

• depends_on: <service>: complete → Wait for health check
• depends_on: <service>: started → Wait for process launch only
• Automatic restart with backoff policy

Health Checks:

health_check:
  test: ["CMD", "curl", "-f", "http://localhost:port/health"]
  interval: 10s
  timeout: 5s
  retries: 3

Readiness Probes:

readiness_probe:
  test: ["CMD", "curl", "-f", "http://localhost:port/ready"]
  interval: 5s
  timeout: 2s
  retries: 3

Key Advantages for Local-First:

• No Docker daemon overhead
• File-watch mode for auto-rebuild
• Native process debugging/profiling
• Same config can export to CI jobs
• Zero infrastructure cost

Getting Started: See LOCAL_FIRST_TECH_RESEARCH.md § 5 for complete process-compose.yml template

Project Requirement: Rust 1.85 ✓ (satisfies all crates)

# NATS
NATS_URL=nats://localhost:4222
NATS_JETSTREAM_DOMAIN=local
NATS_AUTH_TOKEN=<optional>

# Redis/Dragonfly
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=<optional>
REDIS_POOL_SIZE=16
REDIS_POOL_TIMEOUT=30

# Neo4j
NEO4J_URL=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
NEO4J_POOL_SIZE=16

# S3/MinIO
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=artifacts
S3_REGION=us-east-1

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
GRACEFUL_SHUTDOWN_TIMEOUT=30

# Logging
RUST_LOG=info,agileplus=debug
LOG_FORMAT=compact|json

1. Install Process Compose
2. Copy process-compose.yml from template
3. Add Cargo dependencies from section 2
4. Implement infrastructure modules (config, NATS, Redis, Neo4j, S3)
5. Add health check endpoints
6. Run integration tests

Estimated Time: 4-6 hours

Success Criteria:

• All services start and become healthy
• API health endpoint returns 200
• All integration tests pass

1. Implement WorkPackageGraph model (Neo4j)
2. Implement RedisCache layer (caching)
3. Implement event publishing via NATS
4. Implement artifact storage via S3
5. Write integration tests

Estimated Time: 8-12 hours

Success Criteria:

• Create WP with dependencies
• Query dependencies from Neo4j
• Cache snapshots in Redis
• Upload/download artifacts from S3
• Publish/consume events from NATS

1. Create Dockerfile for Rust API
2. Create docker-compose.yml for full stack
3. Test local container deployment
4. Document container build/push process

Estimated Time: 4-6 hours

Success Criteria:

• docker-compose up starts entire stack
• Container health checks pass
• API accessible at localhost:8080

1. Create K8s manifests (ConfigMap, Secrets, Services, Deployments)
2. Deploy to local K8s (Docker Desktop or minikube)
3. Test service discovery and networking
4. Implement ingress for external access

Estimated Time: 6-8 hours

Success Criteria:

• All pods become healthy
• Services communicate correctly
• Ingress route works

1. Create GitHub Actions workflow
2. Test build and deploy stages
3. Set up automated testing on PRs
4. Configure artifact registry

Estimated Time: 4-6 hours

Success Criteria:

• CI builds on every push
• Tests run and report results
• Container images pushed to registry

• Modern C++20 implementation with multi-threaded I/O
• 50% faster on modern hardware
• Superior memory efficiency (critical for containerized local dev)
• Single-binary distribution (matches local-first philosophy)
• Kubernetes-native clustering
• 100% Redis protocol compatible (can swap to Valkey if licensing becomes issue)

• Purpose-built for graph queries with O(1) relationship traversal
• Mature Rust driver (neo4rs) with full Bolt protocol support
• Browser UI for development and debugging
• Constraint and index support for data integrity
• Full ACID transaction support
• 15+ years of production hardening

• Exactly-once delivery semantics (critical for feature state transitions)
• Persistent streams with configurable retention policies
• Both pull and push consumer patterns
• Stream ordering guarantees
• No external dependencies (single binary)
• Built-in monitoring endpoint
• Open source (Apache 2.0)

• Zero Docker daemon overhead (direct OS process management)
• File-watch mode for rapid development iteration
• Health check and readiness probe support
• Dependency ordering with clear semantics
• Same configuration exportable to CI/CD
• Zero infrastructure cost

• Wider ecosystem adoption and examples
• Higher-level abstractions (ByteStream, collectors)
• Better error handling and retry strategies
• Works identically with MinIO via endpoint override
• Long-term maintenance by AWS

• Environment variables configured
• NATS streams created and tested
• Redis connection pool initialized
• Neo4j schema initialized with indexes
• MinIO bucket created and accessible
• Health endpoints returning 200 OK
• Readiness endpoints returning 503 until all services ready
• Integration tests passing
• Graceful shutdown handling SIGTERM
• Structured logging configured
• Prometheus metrics exposed (optional)
• Jaeger tracing configured (optional)

• All services have health checks
• Graceful shutdown with timeouts
• Connection pooling configured
• Retry logic with exponential backoff
• Structured logging with correlation IDs
• Metrics collection (Prometheus)
• Distributed tracing (Jaeger)
• Error handling and recovery
• Rate limiting implemented
• Database constraints and indexes
• Data backup/restore procedures
• Monitoring and alerting rules
• Load testing and capacity planning
• Security: authentication, encryption, authorization

"How do I start the stack locally?" → LOCAL_FIRST_DEPLOYMENT_GUIDE.md § Part 1

"What's the neo4rs API for creating a node?" → LOCAL_FIRST_EXAMPLE_IMPLEMENTATION.md § 5 (Neo4j Integration)

"How do I configure NATS JetStream?" → LOCAL_FIRST_TECH_RESEARCH.md § 1 + LOCAL_FIRST_QUICK_REFERENCE.md § 1

"Show me a complete working example" → LOCAL_FIRST_EXAMPLE_IMPLEMENTATION.md (complete 8-part implementation)

"How do I deploy to Kubernetes?" → LOCAL_FIRST_DEPLOYMENT_GUIDE.md § Part 3

"What environment variables do I need?" → LOCAL_FIRST_QUICK_REFERENCE.md (environment variable reference)

"How do I troubleshoot [service] not connecting?" → LOCAL_FIRST_DEPLOYMENT_GUIDE.md § Part 6 + LOCAL_FIRST_QUICK_REFERENCE.md (troubleshooting)

"What are the latest crate versions?" → LOCAL_FIRST_QUICK_REFERENCE.md (crate dependency list) + LOCAL_FIRST_INDEX.md (version matrix)

• NATS Rust Client
• NATS JetStream Docs
• Dragonfly Docs
• Neo4j Rust Driver
• AWS SDK for Rust
• Process Compose

• NATS Examples
• Neo4rs Examples
• AWS SDK Examples

• NATS Performance
• Dragonfly vs Redis

• Research Team (2026)
• Technology Review: Multi-crate compatibility analysis
• Implementation: Production-ready code examples
• Deployment: Kubernetes and CI/CD integration

Status: COMPLETE AND READY FOR IMPLEMENTATION

Last updated: March 2, 2026 Next review: June 2, 2026 (quarterly crate updates)