Backend Overview

The backend platform is a DAG execution engine that models applications as directed acyclic graphs. You define workflows in YAML, implement handlers in Python, and HBIA manages execution order, data flow, validation, contracts, caching, atomicity, and parallelism.

Architecture

┌──────────────────────────────────────────────────────┐
│                    YAML Flow File                     │
│   (vertices, edges, atomic groups, flow definitions)  │
└──────────────────┬───────────────────────────────────┘
                   │ parsed by DSL Loader
                   ▼
┌──────────────────────────────────────────────────────┐
│                    Graph Model                        │
│   (Vertex, Edge, Graph, AtomicGroup, GraphTopology)   │
└──────────────────┬───────────────────────────────────┘
                   │ validated by Graph Validator
                   ▼
┌──────────────────────────────────────────────────────┐
│                 Execution Engine                      │
│    ┌─────────────┬──────────────┬──────────────┐     │
│    │ DataStore    │ StateStore   │ DataLineage  │     │
│    └─────────────┴──────────────┴──────────────┘     │
│    ┌─────────────┬──────────────┬──────────────┐     │
│    │ Cache       │ Parallel     │ Async        │     │
│    └─────────────┴──────────────┴──────────────┘     │
│    ┌─────────────┬──────────────┐                    │
│    │ Atomicity   │ SAGA         │                    │
│    └─────────────┴──────────────┘                    │
└──────────────────────────────────────────────────────┘

Package Layout

honey_badgeria/back/
├── graph/              # Core data structures (Vertex, Edge, Graph)
│   ├── vertex.py
│   ├── edge.py
│   ├── graph.py
│   └── validator.py
├── topology.py         # GraphTopology (sort, stages, dependencies)
├── dsl/                # YAML parsing and validation
│   └── validator.py
├── loader/             # GraphBuilder (dict → Graph)
│   └── graph_builder.py
├── runtime/            # Execution engine
│   ├── executor.py     # GraphExecutor
│   ├── runner.py       # run_flow() / run_flow_async()
│   ├── data_flow.py    # DataFlowEngine
│   ├── data_store.py   # DataStore
│   ├── state_store.py  # StateStore
│   ├── lineage.py      # DataLineage
│   └── cache/
│       └── cache_manager.py
├── atomicity/          # Atomic execution
│   ├── group.py        # AtomicGroup
│   ├── context.py      # AtomicContext
│   ├── backends.py     # TransactionBackend, InMemoryBackend
│   └── saga.py         # SagaCoordinator, SagaStep
├── contracts/          # Type validation
│   └── contract.py     # VertexContract
├── registry/           # Handler resolution
│   └── handler_resolver.py
├── discovery/          # Auto-discovery of vertices
│   └── autodiscover.py
├── lint/               # Best-practice linting
│   └── ai_linter.py
├── explain/            # Human/AI-readable explanations
│   └── graph_explainer.py
└── validator.py        # Graph structural validation

Core Concepts

Concept	Description	Learn More
Graph Model	Vertices, edges, and graphs — the foundation	Graph Model
DSL	The YAML format for defining flows	DSL Reference
Execution Engine	How graphs are executed step by step	Execution Engine
Data Flow	How data moves between vertices	Data Flow
Parallel & Async	Concurrent execution of independent stages	Parallel & Async
Caching	SHA-256 hash-based result caching	Caching
Atomicity	All-or-nothing execution groups	Atomicity
SAGAs	Compensating transactions	SAGA Pattern
Contracts	Typed input/output validation	Contracts
Validation	DSL and graph structural validation	Validation
Linting	AI-friendly best-practice checks	Linting
Handlers	Resolution and security	Handlers
Discovery	Auto-discovery of decorated vertices	Discovery