Skip to the content
Krizaka Blog

33

Our design choices, for architects: each one with its official docs

Nov 15, 20269 min read

What I faced, Eight design choices an architect can question, each against the alternative we refused; What we built, each choice as one block: the choice, the refusal, why, the cost, with its official docs

A long brick hall with arched doorways and hanging lamps, a small yellow duck walking toward the far end

This post is for architects, tech leads and designers. It is short on prose on purpose: each decision is one block, with the choice, the alternative we refused, why, and what it costs us. Every claim about a tool links to its official documentation, so you can check it. What we run is read from our code on main, not from memory.

The eight choices at a glance

  • Messaging

    Set aside
    Kafka
    Chosen
    RabbitMQ Why: we need work queues (one task, one worker, then it is gone). What it costs: we run the broker; every consumer must be idempotent.
  • Data

    Set aside
    NoSQL as the system of record
    Chosen
    PostgreSQL, jsonb where needed Why: invariants across rows, kept by one transaction. What it costs: a migration for every change of shape.
  • Vectors

    Set aside
    a separate vector database
    Chosen
    pgvector in the same PostgreSQL Why: the vector lives with its row, in the same transaction and the same backup. What it costs: the extension before the migrations; HNSW costs memory.
  • Runtime

    Set aside
    an orchestrator we run
    Chosen
    few containers, Next.js standalone Why: the platform builds, deploys, restarts and routes. What it costs: the JVMs of one container live and die together.
  • End-to-end tests

    Set aside
    retesting the library in every product
    Chosen
    Playwright (web), Maestro (mobile), on the journeys Why: every test has one subject. What it costs: two tools, and the emulator is slow.
  • CI

    Set aside
    a copy per repository
    Chosen
    36 reusable workflows, pinned Why: a fix reaches every repository with a pin bump. What it costs: changing a shared workflow changes every repository.
  • Monitoring

    Set aside
    Prometheus, Loki and Grafana run by us
    Chosen
    Grafana Cloud, dashboards as code Why: probes and storage are not our product. What it costs: the free tier's limits, and a redaction step before Loki.
  • Shared code

    Set aside
    copying between products, or one repository
    Chosen
    published libraries, imported Why: a behaviour written and tested once. What it costs: a version bump for every change.

The detail follows, in the same order.

The view at C1 and C2

Two views of one model written in LikeC4, the notation of the C4 model, checked against our organisation's base model. Less detail than our internal views, and nothing sensitive: no host, address or account.

The context (C1)Customers and visitors use Verikora and Folioviv; Verikora asks Sovkora, the AI engine, for checks; the three products build on the shared libraries, published to the package registries; the platform runs the shared workflows on GitHub, which deploys main to the cloud; Sovkora sends its logs, metrics and traces to monitoring.
CustomerVisitorKrizakaplatformVerikoraFoliovivGitHubSovkoraCloud hostingSharedlibrariesMonitoringPackageregistrieschecks adocumentruns ashopbuys on astorefrontasks forchecksbuildsonbuildsonbuildsonchecks, trains andreleasespublishedtoprovisionsdeploysmainlogs, metrics,traces
The drawing in words

Elements

  • Customer: An organisation or a person who uses a Krizaka product.
  • Visitor: Reads the company site, the blog and the library sites.
  • Krizaka platform: How the org works: shared CI and standards, the agents tooling, the infrastructure as code, the templates.
  • Verikora: Checks documents and keeps the files they belong to.
  • Folioviv: A shop, its storefront and its editor.
  • GitHub: Code, issues, pull requests, CI, the merge queue and the tags.
  • Sovkora: The AI engine the products call: chat, documents, media, automations.
  • Cloud hosting: The app and static site hosting, the managed databases.
  • Shared libraries: Written once, versioned, consumed by every product.
  • Monitoring: Dashboards, logs, traces and probes from outside.
  • Package registries: npm (@krizaka/*), Maven Central and GitHub Packages (com.krizaka), where the libraries are published.

Relations

  • Customer → Verikora: checks a document
  • Customer → Folioviv: runs a shop
  • Visitor → Folioviv: buys on a storefront
  • Verikora → Sovkora: asks for checks
  • Verikora → Shared libraries: builds on
  • Folioviv → Shared libraries: builds on
  • Sovkora → Shared libraries: builds on
  • Krizaka platform → GitHub: checks, trains and releases
  • Shared libraries → Package registries: published to
  • Krizaka platform → Cloud hosting: provisions
  • GitHub → Cloud hosting: deploys main
  • Sovkora → Monitoring: logs, metrics, traces
The containers (C2)Verikora and Folioviv each have a Next.js web app in one container, an Expo mobile app and a PostgreSQL database; Sovkora has an edge service, the engine services, a RabbitMQ broker, Python workers and PostgreSQL databases with pgvector; the web apps import the TypeScript packages and the engine services build on the Java building blocks.
VerikoraFoliovivSovkoraShared librariesVerikoramobileExpoFoliovivmobileExpoVerikora webNext.js, onecontainerFolioviv webNext.js, onecontainerVerikoradatabasePostgreSQLFoliovivdatabasePostgreSQLEdge serviceSpring BootEngineservicesSpring BootMessagebrokerRabbitMQSovkoradatabasesPostgreSQL,pgvectorWorkersPythonTypeScript and UIpackages@krizaka/*, npmJava buildingblockscom.krizaka, MavenSQLHTTPSSQLHTTPSHTTPSroutespublishes from theoutboxSQL, outbox in the sametransactiondelivers, atleast oncereportsoutcomesimportsimportsbuildson
The drawing in words

Elements

  • Verikora: Checks documents and keeps the files they belong to.
    • Verikora mobile (Expo)
    • Verikora web (Next.js, one container): The site and the console, server-rendered.
    • Verikora database (PostgreSQL)
  • Folioviv: A shop, its storefront and its editor.
    • Folioviv mobile (Expo)
    • Folioviv web (Next.js, one container): The storefront and the editor, server-rendered.
    • Folioviv database (PostgreSQL)
  • Sovkora: The AI engine the products call: chat, documents, media, automations.
    • Edge service (Spring Boot): The one public door: authentication, rate limits, routing.
    • Engine services (Spring Boot): One service per bounded context, several JVMs in one container.
    • Message broker (RabbitMQ): Work queues per capability, retries, dead letters.
    • Sovkora databases (PostgreSQL, pgvector): One database per context; the outbox; the vectors beside the rows.
    • Workers (Python): Media, documents and models; consume the queues.
  • Shared libraries: Written once, versioned, consumed by every product.
    • TypeScript and UI packages (@krizaka/*, npm): UI, auth, data, payments, storage: the product imports, never copies.
    • Java building blocks (com.krizaka, Maven): The parent build, the BOM and the Spring Boot starters.

Relations

  • Verikora web → Verikora database: SQL
  • Verikora mobile → Verikora web: HTTPS
  • Folioviv web → Folioviv database: SQL
  • Folioviv mobile → Folioviv web: HTTPS
  • Verikora web → Edge service: HTTPS
  • Edge service → Engine services: routes
  • Engine services → Message broker: publishes from the outbox
  • Engine services → Sovkora databases: SQL, outbox in the same transaction
  • Message broker → Workers: delivers, at least once
  • Workers → Message broker: reports outcomes
  • Verikora web → TypeScript and UI packages: imports
  • Folioviv web → TypeScript and UI packages: imports
  • Engine services → Java building blocks: builds on

1. RabbitMQ rather than Kafka

  • Choice. RabbitMQ carries Sovkora's jobs to its workers. A service writes the job to an outbox table in the same database transaction as its own change; a relay publishes it. Each capability has its own routing key, so a CPU job and a GPU job land in different queues. Queues are bounded (max length and overflow), a failing message is retried and then dead-lettered, and a consumer acknowledges what it finished.
  • Refused. Apache Kafka.
  • Why. Our need is work queues: a job is done once, by one worker, then it is gone. Kafka is a partitioned log where “events are not deleted after consumption” and are retained per topic (Kafka, introduction); its strengths, replay and very high throughput, are not our problem today. AMQP routing is exactly our problem.
  • Cost. We operate the broker ourselves: our cloud host in Canada offers Kafka as a managed service, but not RabbitMQ. A broker lost with messages in flight loses them, which is why the outbox and the database, not the broker, hold the truth. Delivery is at least once, so every consumer must be idempotent.

2. Relational rather than NoSQL

  • Choice. PostgreSQL for every product, one database per bounded context in Sovkora (engine, users, billing, studio). The flexible parts are jsonb columns; Verikora's search is PostgreSQL full text; concurrent writers queue on row and advisory locks and FOR UPDATE … SKIP LOCKED.
  • Refused. A document store as the system of record.
  • Why. Our data carries invariants across rows: a credit hold and the job it pays for, a rule and its revisions, a document and its checks. A transaction keeps them true together, and the outbox only works because the message and the change commit at once. jsonb gives us the schema-light part where we need it, without a second engine.
  • Cost. Every change of shape is a versioned migration. We scale up before we scale out. A relational model has to be watched for unbounded reads and N+1 queries, so our Java rules refuse them.

3. Vectors beside the rows: pgvector, not a separate vector database

  • Choice. pgvector in the same PostgreSQL. Sovkora's semantic cache stores a 1024-dimension embedding with an HNSW index on cosine distance, and the recommendations live in the knowledge database. The cache is off by default; a pack has to turn it on.
  • Refused. A dedicated vector database beside PostgreSQL.
  • Why. A vector is useful only with the row it describes: same transaction, same backup, same tenant filter in the same query. pgvector offers exact and approximate search (HNSW, IVFFlat) with “ACID compliance, point-in-time recovery, JOINs” of Postgres (pgvector).
  • Cost. The extension must be installed by the cluster's administrator, before the migrations run. An HNSW index takes memory and time to build. At a scale we have not reached, a dedicated engine may answer faster; we have not measured it.

4. A few containers, and Next.js in one of them

  • Choice. Each product's web app is a Next.js server built with output: "standalone", one Docker image, run as one service at our cloud host in Canada. Sovkora runs an edge container and an engine container that starts several JVMs side by side; the stateful parts (PostgreSQL, the broker) live outside the app containers. Our sites (this blog, the library docs) are static exports. Each app is described by an app spec committed in its repository, and a tool reports any drift between the file and the live app.
  • Refused. One container per service on an orchestrator we would operate ourselves.
  • Why. A small team, one founder and AI agents: the platform builds, deploys on push to main, restarts and routes. The spec in the repository is the whole deployment, reviewed like code.
  • Cost. The JVMs in one container start, stop and scale together: if one exits, the container exits and the platform restarts the set. Each JVM gets its own heap inside the container's memory, which we size by hand. The platform's limits are ours.

5. Playwright for the web, Maestro for mobile

  • Choice. The main proof of a product is its journeys: one customer promise each, played as a seeded demo cast. Web journeys are Playwright tests in a project named critical; mobile journeys are Maestro YAML flows on an Android emulator, on every pull request. Both run from one shared workflow each, with one required check each.
  • Refused. Testing the library's components again in every product (snapshots, copies of what @krizaka/ui already asserts), and long end-to-end suites rerun after a flake.
  • Why. A product test has one of three subjects: its rules (unit), its server and API (integration, on a real database), its journeys (end to end). A bug found in a library component gets its test in the library. Playwright's projects give one configuration per browser or device; Maestro's flows are short and readable by a non-developer.
  • Cost. Two tools, two syntaxes (TypeScript and YAML). Emulator runs are the slowest part of our CI. Few journeys means a gap is possible between them, which unit and integration tests must cover.

6. CI written once, in GitHub

  • Choice. Our organisation's .github repository holds 36 reusable workflows (on: workflow_call): Node, Java, Python, Rust, mobile end to end, journeys, security scans. Every product calls them, pinned to a full commit SHA, and lands through a merge queue.
  • Refused. A copy of the CI in each repository.
  • Why. A fix to a check lands everywhere with a pin bump, and every repository answers to the same required checks, agents included.
  • Cost. A change to a shared workflow is a change to every repository, so it is tested on its own and rolled out by pin bumps. A caller can only change what the workflow exposes as inputs.

7. Monitoring with Grafana, as code

  • Choice. One Grafana Cloud stack. Synthetic Monitoring probes our public sites from outside; the Java services emit structured logs, metrics and traces through our observability starter and export them over OTLP once an environment's endpoint is set. Dashboards are JSON kept as code and linted.
  • The shape of a dashboard, without its data. One row per app: availability and latency seen from outside, then rate, errors and duration of the requests, then saturation, then the error lines of the logs (Loki). No host name, address or account appears in this post; that is why it shows the shape, not a screenshot.
  • Refused. Running Prometheus, Loki and Grafana ourselves.
  • Why. The probes, the storage and the alerting are not our product; the hosted free tier covers what we send today.
  • Cost. The free tier's limits are ours, and the telemetry leaves our hosting: that is why the logs (Loki) join the dashboards only after a shared redaction step. Today the probes are live; the services' telemetry is switched on environment by environment.

8. Shared libraries, consumed, never copied

  • Choice. TypeScript and UI packages under the @krizaka scope (krizaka-ui, krizaka-ts, docs on ui.krizaka.com and ts.krizaka.com); Java building blocks under com.krizaka (krizaka-java, docs on java.krizaka.com): a parent build, a BOM and Spring Boot starters for web, security, RabbitMQ, observability, persistence and more. Verikora's web app depends on 28 @krizaka packages, Folioviv's on 23; Sovkora's services import the BOM and then the starters, with no version of their own.
  • Refused. Copying code between products, and one repository for all products.
  • Why. A behaviour is written, tested and documented once; a product imports it and tests only its own rules. The RabbitMQ starter is where “published by one transactional line, retried with back-off, then dead-lettered” is written once for every service.
  • Cost. A library change reaches a product only through a version bump, and a breaking change needs a major version and a migration in each consumer. Libraries are public and open source, so their API is a promise.

What this post does not show

The internal decision records stay internal; this post gives their reasons, not their text. The model behind the two views declares the three products and the libraries at the level of this post; each product's full model lives in its own repository.