Skip to content

STD-ARCH-001: Bluefly Factory Interface Contract

1. Core Architecture

The target architecture is Gas City ↔ ContextControl ↔ Drupal, where blutown.ai is the Factory/customer-facing environment and bluefly.io remains the marketing site.

The core contract is:

HUMAN / SYSTEM 
       │
       ▼
CONTEXTCONTROL (identity + scope + intent + policy + approval)
       │
       │ governed request
       ▼
GAS CITY API 
       │
       ▼
BEAD / FORMULA / AGENT 
       │
       ├───────────► Agent A
       │               │
       │               ▼
       │             result 
       │               │
       │             Bead update
       │               │
       ├───────────► Agent B
       ▼
EVENT STREAM 
       │
       ▼
CONTEXTCONTROL READ MODEL
       │
       ▼
CUSTOMER UI / AG-UI / EVIDENCE

ContextControl is the governed human projection and read model; Gas City is the sole execution orchestrator. - Beads carry durable work. - Formulas materialize repeatable operations. - Events synchronize state. - Drupal ECA and API Normalization compose the interface. - Tailscale provides private hardened-city access.

2. Separate the Four Communication Planes

Agents must stop mixing API, events, mail, Beads, and chat. They have distinct jobs:

Plane Authority Purpose
Work plane Beads What work exists, ownership, dependencies, readiness, status
Execution plane Agents + Formulas + Sessions Actually perform bounded work
Observation plane Events What happened, transitions, request completion, runtime facts
Human/control plane ContextControl Who can request, approve, inspect, govern, and understand work
  • BEADS != EVENTS
  • EVENTS != COMMANDS
  • MAIL != WORK AUTHORITY
  • CONTEXTCONTROL != ORCHESTRATOR

3. Agent-to-Agent Communication

The durable pattern for agent handoffs is: Bead exists → prerequisites recorded → dependencies recorded → evidence attached → ownership/routing changed → Agent B receives work

MAIL = notification/context only EVENT = observation/proof only

Mail can alert Agent B, but MAIL_SENT != WORK_ACCEPTED.

4. Formula V2 is the Workflow Compiler

Repeatable operations (e.g., Drupal security update) are NOT massive Agent prompts. They are Formulas. Gas City Formula V2 materializes each workflow step as an independent Bead and routes the resulting graph.

5. ContextControl is a Factory Read Model

Do not copy the Beads database into Drupal as a work authority. - Gas City = operational truth - ContextControl = governed human projection

ContextControl materializes only what humans need: Organization, Team, Project, Operation, Evidence, Policy, etc. using drupal/group.

6. Governed Capabilities vs Generic Endpoints

The Factory must expose a curated capability surface, not every Gas City API endpoint. Start with read-only capabilities (City Status, Agent State, etc.) and add tightly governed commands (Approve Operation, Cancel Operation). Do NOT expose arbitrary bead mutation or shell execution as generic Drupal AI tools.

7. Event-Driven UI

Gas City is asynchronous. Gas City Event → event subscriber → ECA → Drupal read model update. Polling is a recovery mechanism, not the primary architecture.

8. Governed Drupal Commands

Human clicks APPROVE → Drupal permission check → Group/project scope check → Cedar/ContractPlane policy → ECA → API Normalization Tool → Gas City API (202 ACCEPTED) → request_id → Event stream → Operation updated.

9. Trust Boundaries & Access

  • Gas City Supervisor remains a backend runtime service bound to loopback (127.0.0.1:8372). It must not become the public edge.
  • PUBLIC EXTERNAL WEBHOOK → Cloudflare Tunnel → hooks.blutown.ai → declared /hook path
  • PUBLIC/CUSTOMER DASHBOARD → dash.blutown.ai → intended dashboard edge
  • PRIVATE FACTORY API → factory-api.blutown.ai → Tailnet/private edge → Gas City API

Do not use Cloudflare Tunnel for factory-api.blutown.ai or expose the full supervisor API publicly.

10. The 5 Interface Contract

Every integration must map to these five interfaces:

  1. REQUEST: Human/system asks for an operation.
  2. AUTHORIZE: Identity, scope and policy are established.
  3. EXECUTE: Gas City materializes Beads/Formulas/Agents.
  4. OBSERVE: Events provide typed, cursor-based state transitions.
  5. PROVE: ContextControl presents evidence and receipts.