Skip to content

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

RepositoryWhat it isStack
ikazebot-serverThe API and the background workerNestJS 11 (Express), Drizzle ORM, Postgres 18 + pgvector, BullMQ on Redis, Mastra (AI) behind src/ai
ikazebot-webThe dashboard, public site, docs, and the embeddable widgetNext.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_URL has no NEXT_PUBLIC_ prefix for that reason.
  • The one exception is the widget. embed.js and 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:

  1. 1embed.js → iframeon the customer's site
  2. 2Origin allowlist + rate limit10/min per visitor
  3. 3Guardrailsspam, moderation, topics
  4. 4Credits reserved
  5. 5Agent assembled from its rowinstructions, model, actions
  6. 6Retrieval → model → SSE stream
  7. 7Usage recorded, message stored

Key choices, and why

ChoiceWhy
pgvector in the same PostgresOne 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 gatewayHundreds of models through one integration. A per-model credit multiplier of our own gives per-model pricing.
Mastra as a library, not a serviceNo network hop. Nothing outside src/ai imports it, so its API can change without touching the rest.
Ports for anything swappableBilling, storage, mail and embeddings are interfaces with one adapter each, so a provider change is a driver change
SSE, not WebSockets, for repliesOne direction, works through proxies, no sticky sessions
Row-level security as the tenancy boundaryA 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.md covers what we build, ARCHITECTURE.md how, and ROADMAP.md when, with the feature codes (F01…).
  • ikazebot-server/README.md covers database setup, storage, jobs and the per-feature runbooks.
  • ikazebot-server/DEPLOY.md is the production runbook.
Get started free — 50 credits a month