Architecture
Two repositories, one product: the processes, where they run and how they talk.
On this page
ikazebot is a multi-tenant SaaS: many businesses (workspaces, called organizations in the code) share one deployment, and none may ever see another's data. Every design choice also has to work on a single VPS run by a small team, so there is no managed queue service and no second region.
Two repositories, one product
| Repository | What it is | Stack |
|---|---|---|
ikazebot-server | The API and the background worker | NestJS 11 (Express), Drizzle ORM, Postgres 18 + pgvector, BullMQ on Redis, Mastra (AI) behind src/ai |
ikazebot-web | The dashboard, public site, docs, and the embeddable widget | Next.js 16 (App Router, cacheComponents), React 19, Tailwind 4, shadcn on Base UI |
They are separate repositories with separate lockfiles and deploys. There is no monorepo and no shared package. The API's response shapes are Zod schemas, copied by hand between ikazebot-server/src/shared/* and ikazebot-web/src/lib/shared/* (see API conventions).
Topology
Traefik (TLS, routing — managed by Dokploy)
│
┌────────────────┴─────────────────┐
app.ikazebot.com api.ikazebot.com
web (Next.js) ── server-side ──▶ api (NestJS)
fetch only │ Mastra in-process (src/ai)
│
┌───────────────┬───────────────┼──────────────────┐
Postgres 18 Redis 8 Object storage OpenRouter
+ pgvector queues, rate (R2 / MinIO) chat models,
rows, vectors limits, pub/sub uploads, exports embeddings
│
worker (same build as api, entry dist/worker.main.js)
ingestion · crawl · resync · rollups · webhooks · retention · mail
Who talks to whom
- The browser never calls the API directly. Dashboard pages fetch in Server Components, and changes go through Server Actions.
API_BASE_URLhas noNEXT_PUBLIC_prefix for that reason. - The one exception is the widget.
embed.jsand its iframe are a public, cross-origin surface. Even then, visitor requests reach the API through a relay in the web app (WIDGET_RELAY_SECRET), which forwards the visitor's real address for rate limiting. - The worker shares the API's code. Both are built from one repository and one build, and differ only in entrypoint. A job therefore uses exactly the same tenant-isolation code as a request.
The public chat path
The busiest unauthenticated path, and the one where abuse lands first:
- 1embed.js → iframeon the customer's site
- 2Origin allowlist + rate limit10/min per visitor
- 3Guardrailsspam, moderation, topics
- 4Credits reserved
- 5Agent assembled from its rowinstructions, model, actions
- 6Retrieval → model → SSE stream
- 7Usage recorded, message stored
Key choices, and why
| Choice | Why |
|---|---|
| pgvector in the same Postgres | One database to run and back up; vectors obey the same row-level security as every other row and stay consistent with the rows they came from |
| OpenRouter as the one model gateway | Hundreds of models through one integration. A per-model credit multiplier of our own gives per-model pricing. |
| Mastra as a library, not a service | No network hop. Nothing outside src/ai imports it, so its API can change without touching the rest. |
| Ports for anything swappable | Billing, storage, mail and embeddings are interfaces with one adapter each, so a provider change is a driver change |
| SSE, not WebSockets, for replies | One direction, works through proxies, no sticky sessions |
| Row-level security as the tenancy boundary | A forgotten WHERE clause returns nothing instead of another customer's data. See Tenancy. |
Where to read more
The repositories hold the source of truth. When this page and the code disagree, the code wins:
CLAUDE.md(identical in both repos) is the working agreement, cited by section (CLAUDE.md §5).ikazebot-server/docs/PRODUCT.mdcovers what we build,ARCHITECTURE.mdhow, andROADMAP.mdwhen, with the feature codes (F01…).ikazebot-server/README.mdcovers database setup, storage, jobs and the per-feature runbooks.ikazebot-server/DEPLOY.mdis the production runbook.