Architecture

Project Structure

apps/api/src/
├── main.ts                      # Boot: Fastify, imports both barrels
├── app/
│   ├── hooks/                   # Business logic (finance, inventory, sales, shipping, ...)
│   │   └── index.ts             # ⚠️ AUTO-GENERATED — do not edit
│   ├── system-hooks/            # ⛔ ADMIN-MANAGED — see warning below
│   │   └── index.ts             # ⚠️ AUTO-GENERATED — do not edit
│   └── interfaces/              # Business domain schemas (.data.ts) and types (.interface.ts)
│       └── registry/            # ⚠️ AUTO-GENERATED
│           ├── index.ts
│           ├── nao-interfaces.augment.ts
│           └── registry.ts

libs/
├── logic-hooks/                 # @LogicHook decorator, LogicHookRouter, ExecutionPipeline
├── event-engine/                # NaoEventRunner, BobRequest, integrations
├── flow-query/                  # FlowQuery ORM, FlowUser, cluster management
├── config/                      # MongoDB connections, env vars, globalFlags
├── interfaces/                  # FlowDocument, system TypeScript interfaces, type map base
├── connectors/                  # External API connectors (Stripe, QuickBooks, UPS, etc.)
└── utils/                       # Logging, crypto, CSV/Excel, validators

System Hooks Are Admin-Managed

The system-hooks/ directory is maintained and overwritten by system administrators. Do not modify system hooks without admin approval. Your changes will be overwritten on the next system update.

Business hooks in hooks/ are safe to edit freely.

Hook Anatomy

Every hook follows this file path pattern:

hooks/{library-slug}/{method-slug}/{method-slug}.{library-slug}.hook.ts

And this code structure:

@LogicHook({
  name: 'FinanceBillsCalculateBill',
  path: 'finance-bills/calculate-bill',
  library: 'finance-bills',
  method: 'calculate-bill',
  legacy: 'app/app.financeBillsHooks.calculateBill'
})
export class FinanceBillsCalculateBill {
  public static execute() {
    return async (bob: BobRequest<{ data: { data: any; naoQueryOptions: NaoQueryOptions } }>) => {
      let ok = true, error: any = null, data
      try {
        // your logic here
      } catch (err) { error = err; ok = false }
      return returnEventResult(bob, { ok, error, data })
    }
  }
}

Boot Sequence

main.ts → naoClusterManager → bootstrap() → AppModule

1. Configuration — loads .env and global secrets
2. Adapters — sets up RedisIoAdapter for WebSocket scaling
3. Middleware — registers helmet, csrf, multipart, secure-session
4. Connections — establishes database connections via initConnections()
5. Systems — initializes localization, event runner, hook repository, metadata

Cluster Mode

• Development: Runs directly in master process (no forking)
• Production: naoClusterManager forks worker processes to maximize CPU utilization

Role	Responsibility
Master	Manages workers and cluster-level tasks
Workers	Handle API requests and execute hooks

Deployment

Tool	Config
Docker	Dockerfile (production) or Dockerfile-quick-build (rapid iterations)
PM2	app.pm2.json
CI/CD	.github/workflows/