Architecture

Logical boundaries that can separate later without changing ownership.

The initial deployment co-locates services on one Docker Compose host, but presentation, domain state, orchestration and AI/RAG remain explicit boundaries.

Browser

Public + /app

Nginx

only public ingress

Next.js

presentation

NestJS

auth + domain state

PostgreSQL

state + audit + pgvector

Dispatch Worker

outbox leasing

n8n

deterministic orchestration

FastAPI

AI + retrieval

Ownership

Next.js

Public technical site and authenticated presentation. No authoritative business rules.

NestJS

Authentication, authorization, tickets, state transitions, audit, internal APIs and outbox records.

n8n

Deterministic branching and service coordination. It does not own authorization or final ticket state.

FastAPI

Structured extraction/drafting plus self-hosted RAG ingestion, embeddings, retrieval and citations.

Asynchronous processing

Outbox → human review

click a stage

DB transaction. NestJS writes the ticket and outbox event atomically.

Single-host deployment

Internet
   │
 Nginx ── / → Next.js
   └──── /api → NestJS ── PostgreSQL / private files
                    │
                  outbox → Dispatch Worker → n8n
                                             ├→ NestJS internal APIs
                                             └→ FastAPI → pgvector / model provider

Only Nginx is intended for public exposure. PostgreSQL, n8n, FastAPI, the worker and internal API paths stay on the private service network.

Deployment models

Single-host deployment is about where the services run. Deployment models are about whether organizations share that host. The same code supports both.

	Shared (multi-tenant)	Dedicated (per organization)
How	All organizations in one PostgreSQL database. Every row carries `organization_id`; NestJS and the SQL queries enforce the scope on each request.	Each organization gets its own copy of the stack and database, with one organization inside.
Best for	Many smaller customers at low cost per customer.	Banks and larger companies with strict data residency or isolation rules.
Used by	The public sandbox today.	Available with the same code and Compose setup.

Known limit: ticket numbers use one counter shared by all organizations. That is fine for dedicated hosting and the sandbox. Per-organization numbering is a planned step for shared hosting with real customers.