Frontend Overview

The frontend platform takes a fundamentally different approach to UI architecture. Instead of building interfaces with traditional component-based patterns — where each component owns its state, effects, and event handling — HBIA decomposes the frontend into four interconnected reactive graphs.

The Problem with Traditional Frontend Architecture

In a typical React/Vue/Angular application:

• State is scattered. useState hooks live inside components. Context providers wrap arbitrary subtrees. Global stores add another layer. An AI agent trying to understand "where is the user's filter state?" has to read dozens of component files.
• Effects are hidden. useEffect calls are embedded deep inside components, often with complex dependency arrays. Side effects (API calls, analytics, localStorage) are invisible from the outside.
• Event flow is implicit. A button click might update local state, call a context method, dispatch to a store, and trigger a side effect — all through different mechanisms scattered across files.
• Components are entangled. A "simple" component might import hooks, context, stores, and utility functions, creating invisible coupling that's hard to trace.

The HBIA Approach: Four Reactive Graphs

HBIA models the frontend as four separate, interconnected graphs:

┌─────────────────────────────────────────────────────────┐
│                     User Action                          │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  EVENT GRAPH                                             │
│  User clicks "Refresh" → [set_loading, reset_filters]    │
└────────────────────────┬────────────────────────────────┘
                         │ mutations
                         ▼
┌─────────────────────────────────────────────────────────┐
│  STATE GRAPH                                             │
│  FilterState.region changed → triggers: [fetch_data]     │
└──────────┬─────────────────────────────┬────────────────┘
           │ triggers                     │ drives
           ▼                              ▼
┌──────────────────────────┐   ┌──────────────────────────┐
│  EFFECT GRAPH            │   │  UI GRAPH                 │
│  fetch_data watches      │   │  Dashboard reads          │
│  FilterState.region      │   │  FilterState.region       │
│  → API call              │   │  → re-renders             │
│  → mutates ChartState    │   │                           │
└──────────────────────────┘   └──────────────────────────┘

Events → mutate State → trigger Effects → State drives UI.

This cycle is the entire frontend data flow. No exceptions.

The Four Graphs

1. UI Graph

A tree of pure render components. UI nodes:

• Declare what state they read (subscriptions).
• Declare what events they emit.
• Declare children (composing the tree).
• Contain zero business logic — no hooks, no state, no effects.

Full documentation →

2. State Graph

Centralized state ownership. State nodes:

• Declare typed fields with initial values.
• Declare mutations (the only way to modify state).
• Declare triggers (effects that fire on state change).

Full documentation →

3. Effect Graph

Side effects triggered by state changes or events. Effect nodes:

• Watch state fields (reactive).
• Run a handler (API call, computation, logging).
• Mutate state (the result feeds back into the state graph).
• Optionally debounce.

Full documentation →

4. Event Graph

User interaction flows. Event nodes:

• Map a user action to an ordered sequence of mutations.
• Declare the source component.
• Define guards (preconditions).

Full documentation →

Why This Matters for AI

When an AI agent encounters a traditional React/Next.js codebase, it must:

1. Read every component file to find state.
2. Trace useEffect dependency arrays to understand effects.
3. Follow callback chains to understand event flows.
4. Mentally reconstruct the data flow from scattered pieces.

With HBIA's frontend, the AI reads four YAML files and has the complete data flow map:

• Every component and what state it reads.
• Every piece of state, its type, and its mutations.
• Every side effect, what triggers it, and what it writes.
• Every user event and the exact mutation sequence it triggers.

Package Layout

honey_badgeria/front/
├── graph/                  # Graph data structures
│   ├── ui_graph.py         # UIGraph, UINode
│   ├── state_graph.py      # StateGraph, StateNode
│   ├── effect_graph.py     # EffectGraph, EffectNode
│   ├── event_graph.py      # EventGraph, EventNode
│   └── domain.py           # FrontendDomain (bundles all four)
├── dsl/                    # YAML parsing & validation
│   ├── loader.py           # Loaders for each graph type
│   └── validator.py        # Cross-graph validation
├── lint/                   # Best-practice linting
├── explain/                # Human/AI-readable explanations
├── codegen/                # TypeScript code generation
│   └── runtime_gen.py      # FrontendCodegen
└── exceptions.py           # Frontend-specific errors

Next Steps

Topic	Description
The Four Graphs	Deep dive into each graph type
Frontend DSL Reference	YAML format for all four graph types
Code Generation	TypeScript runtime generation
Validation & Linting	Frontend-specific validation