Understanding the System

The AI can explain how Logic Bee works, trace request flows, and help you debug issues.

Example Prompts

"Why is my hook not being called? Check the event-routing skill for how LogicHookRouter dispatches events."

"How does a request reach my hook?"

"Explain the boot sequence"

"What happens when I call bob.executeRequestOrThrow?"

"Where do hooks get registered?"

What the AI Does

1. Reads system architecture knowledge
   → Understands the full request lifecycle:
     HTTP → NestJS → BobRequest → LogicHookRouter → Your Hook → Response

2. Traces the event flow
   → Knows how @LogicHook decorator registers hooks at import time
   → Knows how LogicHookRouter dispatches events to hook classes
   → Knows how jobs are resolved from flow preset configs

3. Identifies common issues
   → Hook not in barrel file → not imported → not registered
   → Wrong event name → router can't find the hook
   → Missing bob.flowUser → query fails silently

Key Concepts the AI Knows

Request Flow

Frontend → HTTP POST → NestJS Controller
  → Creates FlowUser + BobRequest
  → Looks up preset config → resolves jobs
  → For each job: LogicHookRouter calls your hook's execute()
  → Returns { ok, error, data } to the client

Hook Registration

@LogicHook decorator fires at import time
  → Registers the class in LogicHookRouter's hookMap
  → Barrel file (hooks/index.ts) imports all hook files
  → No manual registration needed

Project Layout

apps/api/src/app/
├── hooks/           ← Your business logic (finance, inventory, sales, ...)
├── system-hooks/    ← Platform internals (don't edit)
└── interfaces/      ← Data type definitions

Common Debugging Questions

Question	What the AI checks
"My hook isn't being called"	Is it in the barrel file? Is the event name correct? Is it registered?
"I'm getting unauthorized errors"	Is bob.flowUser passed to queries? Is .addPolicy() used?
"My data isn't saving"	Is bob.dbSession() passed to write operations?
"My changes disappeared"	Was the hook in system-hooks/? (Admin overwrites those)

Tips for Better Results

• Include error messages — paste the exact error so the AI can trace the cause
• Name the hook — "my calculateBill hook" helps the AI find the right file
• Ask "why" — "why does FlowQuery need flowUser?" gets an architectural explanation