AI & LLM Architecture

Core Philosophy

• Externalized Computation: No self-hosted LLMs. External APIs (OpenAI, Anthropic, Gemini) keep hardware costs low and containers stateless.
• Nest.js as Orchestrator: LLMs are text generators; Nest.js gives them tools via Vercel AI SDK / LangChain.js. The LLM decides which function to call, Nest.js executes it, feeds back the result.
• PostgreSQL + pgvector as Memory: pgvector extension on Hetzner Managed Postgres for embeddings and similarity search. No external vector DB needed.

Agent Workflows

Type	Use Case	Request Path	Response Path
Background	Batch processing, weekly reports	Hasura Cron/Event → Worker (BullMQ) → LLM API	Worker saves to Postgres. User uninvolved.
Progress	Complex itineraries, B2B negotiations	User → Hasura ("pending" row) → Worker → LLM API	Worker updates Postgres. Hasura Subscriptions push live UI updates.
Real-Time Chat	Support copilot, instant Q&A	Vue.js → Traefik → Nest.js (HTTP) → LLM API	Nest.js streams via SSE. History saved after completion.

Infrastructure Integration

Queueing (BullMQ)

• BullMQ on Redis in Swarm. Managed via NestJS workers.
• Hasura event/cron triggers → NestJS enqueues BullMQ job → responds 200 OK immediately.
• Worker picks up job, handles slow AI calls, updates database on completion.
• See workflow-orchestration.md for the full trigger → execution model.

Segregated Services (Same Docker Image)

1. api (Web): HTTP server on. Handles SSE chat streams + standard traffic.
2. api-worker (Background): HTTP off. Listens to Redis queue. Scales independently.

Traefik Configuration

Long-lived connections for AI streaming need explicit timeout config:

labels:
  - "traefik.http.middlewares.ai-timeout.buffering.maxRequestBodyBytes=0"
  - "traefik.http.serversTransports.mytransport.respondingTimeouts.readTimeout=120s"

Strategic Use Cases

• Dispatch Assistant: Monitors traffic/weather alerts. Auto-drafts re-routing, checks driver limits, queues passenger SMS for dispatcher approval.
• Group Booking Negotiator: Calculates bulk discounts, suggests stops via pgvector search, generates PDF contracts.
• Customer Support Copilot: Actionable chat — rebook passengers, issue refunds via tool-calling.

---

Agentic Company Governance

Purpose

Company-level agent orchestration — AI agents that run the business (engineering, marketing, product, strategy), not the product. Distinct from the product-level AI use cases above.

Platform: Paperclip + MCP

• Runtime: Paperclip — open-source, MIT-licensed, TypeScript-based agent orchestration platform. Provides heartbeat scheduling, budget enforcement, atomic task checkout, approval gates, org charts, and audit trails.
• Deployment: Standalone service (own Postgres, own Docker container). Does not share a database with Busflow.
• Integration: Agents access Busflow systems via MCP (Model Context Protocol) servers. MCP tool assignment enforces bounded contexts — each agent sees only the tools scoped to its domain.
• Domain Teams: Agent teams map to BusFlow's four DDD bounded contexts (Commerce, Backoffice, Operations, Communications). Each team runs a PM/Engineer/QA triad scoped to its monorepo directories.
• Cross-Session Learning: Each domain maintains a .knowledge.md file for accumulated learnings. QA agents write on failure; Engineer agents read on wake.
• Governance Spec: agentic-led-company-spec.md defines principles. Paperclip implements the runtime.
• ADR: ADR-020
• MCP Protocol: mcp-agent-bridge.md

Architecture

┌──── Paperclip (standalone) ──────────┐       ┌──── Busflow ────────────┐
│                                      │       │                         │
│  Commerce Team   (PM · Eng · QA)     │  MCP  │  Hasura (product data)  │
│  Backoffice Team (PM · Eng · QA)     │◄─────►│  NestJS API (actions)   │
│  Operations Team (PM · Eng · QA)     │       │  GitHub (code)          │
│  Comms Team      (PM · Eng · QA)     │       │                         │
│                                      │       │                         │
│  Cross-Cutting: PM · Co-Founder      │       │                         │
│                                      │       │                         │
│  Own Postgres · Own Docker           │       │  Own Postgres · Swarm   │
└──────────────────────────────────────┘       └─────────────────────────┘

Evolution Path

Start with Paperclip as-is (Strategy A). Fork with select additions if needed (Strategy D). Full custom build only if fundamentally constrained (Strategy C).

---

Agentic Development Process

SDLC Integration

• Spec-Driven Design: Markdown architecture specs → AI scaffolds modules autonomously.
• Deep Contextual Testing: Agents trace dependencies, generate edge-case integration tests.
• Autonomous Refactoring: Background agents scan for tech debt, open draft PRs.
• Automated PR Reviews: AI checks diffs for logic flaws, security issues, style violations.

Guardrails

• Human in the Loop: AI = junior dev. Human owns the merge button. No direct-to-production.
• MCP Integration: Agents connect to live DBs, error logs, deployments via Model Context Protocol. See guidelines.md §7 for the dual-brain (Monorepo + NotebookLM) workflow.
• Shift-Left Security: AI cannot read .env or secrets. AgentShield prevents data exfiltration.
• Continuous Learning: ECC's instinct system extracts codebase patterns across sessions with confidence scores.