BitVelocity Documentation

Welcome! This site houses architecture overviews, ADRs, event contracts, and execution guides for the BitVelocity platform.

📋 Project Boards

Track and create stories directly on GitHub:

• 📊 Planner Board - High-level planning and epic tracking
• 🏃 Scrum Board - Sprint management and daily tasks

💡 Tip: Use GitHub's "Create issue from project" feature to quickly add stories from the board interface. Link issues to this documentation for traceability.

🚀 Quick Start

New to the project? Start here:

1. Projects & Modules Overview - Understand the codebase structure
2. Quick Start Guide - Get your development environment ready
3. Phases Overview - Follow the implementation roadmap

📁 Documentation Structure

00-OVERVIEW - Project Foundation

• Projects & Modules - Complete module inventory and learning paths
• Stakeholder Guide - Role-based navigation guide
• Project Charter - Mission, objectives, and constraints

01-ARCHITECTURE - System Design

• System Overview - Platform architecture
• Data Architecture - OLTP, CDC, OLAP flows
• Security Architecture - Authentication, authorization, secrets
• Domain Architectures - E-Commerce, Chat, IoT, Social, ML/AI
• Cross-Cutting Concerns - Observability, Events, Replay, Cost, Data Platform

03-DEVELOPMENT - Implementation Guides

• Microservices Patterns
• API Protocols - REST, gRPC, WebSocket, SSE, MQTT
• Testing Strategy
• Performance Testing

Stories & Phases - Execution Roadmap

• Quick Start - Get started quickly
• Reference Topics - Protocol and concurrency patterns
• Phases - Phase-by-phase implementation guide (Phase 0-9)

ADR - Architectural Decision Records

• ADR-001 - Repository structure decision
• ADR-002 - Event sourcing vs CDC strategy
• ADR-003 - Protocol learning sequence
• ADR-004 - Data architecture decisions
• ADR-005 - Security architecture approach
• ADR-006 - Resilience patterns
• ADR-007 - Observability strategy
• ADR-008 - Cloud abstraction approach

🎯 Learning Paths by Role

Software Architects & Technical Leaders

graph LR
    A[Project Charter] --> B[System Overview]
    B --> C[Data Architecture]
    C --> D[Domain Architectures]
    D --> E[ADR Reviews]

Backend Developers

graph LR
    A[System Overview] --> B[Microservices Patterns]
    B --> C[API Protocols]
    C --> D[Domain Implementation]
    D --> E[Testing Strategy]

1. Phases → pick your current phase
2. Actionable Build Plan
3. Event Contracts → Guide/README

Platform Engineers & DevOps

graph LR
    A[Cloud Strategy] --> B[Deployment Architecture]
    B --> C[Observability]
    C --> D[Disaster Recovery]
    D --> E[Cost Optimization]

1. Cloud Strategy
2. Deployment Architecture
3. Observability Strategy
4. Disaster Recovery
5. Cost Optimization

Data Engineers

graph LR
    A[Data Architecture] --> B[Data Governance]
    B --> C[Microservices Patterns]
    C --> D[Observability]

1. Data Architecture
2. Data Governance
3. Microservices Patterns (Data sections)
4. Observability Strategy (Data monitoring)

Project Managers

graph LR
    A[Project Charter] --> B[Sprint Planning]
    B --> C[Execution Roadmap]
    C --> D[Budget Planning]

📊 Implementation Progress Tracking

Sprint Progress (12 sprints total)

• ✅ Sprint 1: Foundation Bootstrap
• ⏳ Sprint 2: Event-Driven Core
• ⏳ Sprint 3: Real-time Patterns
• ⏳ Sprint 4: Query Aggregation
• ⏳ Sprint 5: External Integration
• ⏳ Sprint 6: IoT & Messaging
• ⏳ Sprint 7: Stream Processing
• ⏳ Sprint 8: Multi-Region Infrastructure
• ⏳ Sprint 9: Advanced Messaging
• ⏳ Sprint 10: Cloud Portability
• ⏳ Sprint 11: Resilience & Recovery
• ⏳ Sprint 12: Production Hardening

Technology Coverage

• Protocols: REST ✅, GraphQL ⏳, gRPC ⏳, WebSocket ⏳, SSE ⏳, MQTT ⏳, AMQP ⏳, SOAP ⏳
• Data Stores: PostgreSQL ✅, Redis ⏳, Kafka ⏳, Cassandra ⏳, MongoDB ⏳
• Cloud Platforms: GCP ⏳, AWS ⏳, Azure ⏳
• Patterns: CQRS ⏳, Event Sourcing ⏳, Saga ⏳, Circuit Breaker ⏳

Contributing Guidelines

1. Follow the existing document structure and naming conventions
2. Update cross-references when adding new documents
3. Maintain consistency with architectural decisions in ADRs
4. Include practical examples and implementation details
5. Update the main index when adding new major sections

🆘 Getting Help

Common Questions

• "Where do I start?" → Begin with the Stakeholder Guide
• "What's the budget?" → See Budget Planning
• "How are phases organized?" → Check Phases Overview
• "What about security?" → Review Security Architecture
• "Where's the data strategy?" → See Data Architecture

Support Channels

• Technical Questions: Review relevant ADRs and architecture documents
• Implementation Issues: Check microservices patterns and development guides
• Project Planning: Consult project management documentation
• Budget Concerns: Reference budget planning and cost optimization guides

Layered Dependency Contract (Do Not Violate)

Shared Libs ← (used by) All Domains
Security Platform ← (used by) All Domains
E-Commerce Events → consumed by others (but Order svc never imports Chat code etc.)
Cross-cutting docs define invariants; domain docs must not redefine them.

Quick links - Phases: stories/phases/ - Reference Topics: stories/REFERENCE-TOPICS.md - ADRs: adr/ - Event Contracts: event-contracts/