Architecture docs

High-level architecture of the Translately platform. The canonical steering doc is .kiro/steering/architecture.md; this tree expands on it with diagrams, module maps, and Architecture Decision Records (ADRs).

Per CLAUDE.md rule #10, every PR that introduces a non-trivial technical decision lands an ADR here in the same PR.

Overview

  • Module map — Gradle module graph, dependencies, ownership.
  • Data model — ER diagram, entity relationships, indexing.
  • Request lifecycle — from HTTP → filter stack → controller → service → data layer.
  • Multi-tenancy — TenantContext, TenantRequestFilter, row-level isolation.
  • Authentication — JWT vs. OIDC vs. LDAP, token formats, refresh rotation.
  • Authorization — scopes, roles, @RequiresScope, per-resource permissions.
  • Crypto — envelope encryption for BYOK secrets, key rotation, at-rest protections.
  • Search — Postgres FTS (tsvector + pg_trgm) over keys and translations; no Elasticsearch in v1.
  • Webapp shell — route tree, state stores, TanStack Query boundaries.
  • CI pipelines — the six GitHub Actions workflows, branch-protection gates, and how tagged releases become signed images.
  • ICU validation — MessageFormat parse/validate contract, what’s checked and not checked, consumers.

ADRs

Architecture Decision Records live under decisions/. Every non-trivial technical choice (library swap, auth strategy, storage layout, algorithm, performance trade-off) gets an ADR. They’re immutable once accepted — supersede rather than edit.

Diagram conventions

  • Mermaid in .md files — renders natively on GitHub + Pages.
  • Exported PNGs under diagrams/ for the llms-full.txt ingestion (text-only LLMs can’t parse mermaid blocks).
  • Source alongside rendered — keep the .mmd next to the .png so diagrams are reproducible.

Table of contents