Overview

Philosophy

Huddle is a microservices platform. The API is the central authority for business logic, identity, and data; the other services are specialized workers and frontends that build on it. Long-running, cross-service work is coordinated with Temporal, and every service is wired into a shared observability stack.

How it fits together

graph TD
    Browser -->|tRPC over SDK| App[App<br/>Next.js]
    App -->|REST via SDK| API[API<br/>Go]
    API -->|start workflows| T{{Temporal}}
    T --> RAG[RAG worker<br/>Python]
    T --> NOT[Notification worker<br/>TypeScript]
    RAG -->|read/write via SDK| API
    NOT -->|read via SDK| API
    Website[Website<br/>Cloudflare] -.marketing.-> Browser

Services

APIGo backend — business logic, identity, persistence, and the Temporal client that triggers every workflow. Generates the SDKs.

AppNext.js frontend using a type-safe tRPC passthrough over the generated Go-API SDK.

RAGPython Temporal worker for document parsing, retrieval, and bond automation (PyMuPDF, Gemini via LiteLLM, pgvector + BM25).

NotificationTypeScript Temporal worker sending transactional email with React Email + Resend.

WebsitePublic marketing site — Next.js on Cloudflare Workers via OpenNext.

DocsThis site — Astro Starlight on Cloudflare.

Infrastructure

DeploymentRailway for the services, Cloudflare for the web properties; fast-forward-only promotion.

ObservabilitySelf-hosted Grafana LGTM stack, OTel, blackbox probes, and distributed tracing.

TemporalThe client/worker split, task queues, and deterministic workflow IDs.