What is Logic Bee 🐝?

Logic Bee is an event-driven ERP API for the Naologic ecosystem. Built on NestJS + Fastify + MongoDB, it uses a decorator-based architecture where all business logic lives inside self-describing hook classes.

Why This Architecture

• Decorator-based hooks — business logic lives in @LogicHook classes that auto-register at import. No config files, no manual wiring.
• One hook per file — every function is isolated, testable, and discoverable by both humans and AI agents.
• Separated concerns — business hooks (hooks/) and system hooks (system-hooks/) live in distinct directories with auto-generated barrels.
• FlowQuery ORM — chainable, tenant-scoped database access with built-in permissions, business unit isolation, and bulk operations.
• Pipeline execution — concurrency control, timeouts, and circuit breakers at the hook level.
• AI-ready — skill files in .agents/skills/ let any AI agent understand and contribute to the codebase immediately.

Key Concepts

• Hooks — Self-contained units of business logic, decorated with @LogicHook
• Libraries — Logical groupings of related hooks (e.g. finance-bills, inventory-management)
• Events — The messages that drive your application flow
• FlowQuery — Chainable ORM for tenant-scoped database operations

Key Technologies

• Framework: NestJS (with Fastify adapter for performance)
• Architecture: Monorepo managed by Nx
• Database: MongoDB Atlas
• Real-time: WebSockets using a custom Redis adapter
• Process Management: Native Node.js cluster mode and PM2

Core Libraries

Library	Purpose
@logic-bee/event-engine	BobRequest, returnEventResult — the hook framework
@logic-bee/logic-hooks	@LogicHook decorator, LogicHookRouter, ExecutionPipeline
@logic-bee/flow-query	FlowQuery ORM, FlowUser, cluster management
@logic-bee/config	MongoDB connections, env vars, globalFlags
@logic-bee/interfaces	FlowDocument, system TypeScript interfaces, type map
@logic-bee/connectors	External API connectors (Stripe, QuickBooks, UPS, etc.)
@logic-bee/utils	Logging, crypto, CSV/Excel, validators

Routing & API

Logic Bee uses Fastify routes directly — no NestJS controllers. All requests flow through a unified route handler that authenticates, extracts the user context, and dispatches to the event engine.

Route Types

Route	Path	Auth	Purpose
Universal	POST /api/v2/universal/:cfpSlug/:dataType/:action	JWT	Standard authenticated requests (CRUD, actions)
Public	POST /api/v2/universal-public/:cfpSlug/:dataType/:action	API Key	External integrations, public-facing endpoints
Webhooks	POST /api/v2/webhooks/:cfpSlug/:dataType/:action	API Key	Inbound webhooks (no file uploads)
SSE Private	GET /api/v2/sse/connect + POST /api/v2/sse/message	JWT	Streaming responses for authenticated users
SSE Public	GET /api/v2/sse-public/connect + POST /api/v2/sse-public/message	API Key	Streaming responses for public API clients
App	GET /api/v2/app/ping	None	Health checks

How a Request Flows

HTTP Request → Auth (JWT or API Key) → Extract FlowUser → Build NaoEventRequest → Event Engine → Hook(s) → Response

Server-Sent Events (SSE)

For long-running operations (AI agents, reports, data pipelines), Logic Bee supports SSE streaming:

1. Client opens a persistent connection via GET /sse/connect → receives a sessionId
2. Client sends work via POST /sse/message with the sessionId
3. Server pushes events through the SSE stream in real time
4. Sessions auto-cleanup after 5 minutes of inactivity

Ports

Service	Port
HTTP API	3010
WebSocket	31225