Engineering case study

How this site is built

Engineering case study of a production-minded knowledge base: architecture, localization, content authoring, quality, security, and infrastructure.

Source code Open the matrix

Problem

The site combines articles, a competency matrix, and architecture notes. It needs to help readers, stay comfortable for authoring, and demonstrate real engineering decisions instead of only listing technologies.

Architecture

Backend

Litestar, SQLAlchemy, Dishka, and PostgreSQL form an API-first backend with explicit boundaries between domain logic, HTTP, infrastructure, and storage. The private knowledge base extends a typed common item with dedicated one-to-one tables instead of universal JSON/EAV, while every operation is author-isolated.

LitestarSQLAlchemyPostgreSQLDishkaTaskIQ

Frontend

Angular hybrid SSR/CSR and backend-driven i18n provide SEO for public pages, while read-only matrix and article surfaces stay separate from protected workspaces: owner, admins, and moderators manage content, while owner and admins govern the team.

AngularSSRTypeScriptBootstrap

Infrastructure

nginx, Docker, MinIO with S3-compatible media storage, Valkey, and TaskIQ separate edge routing, files, cache, background jobs, and frontend/backend container runtimes, while public traffic switches between blue/green slots only after health checks pass. Private knowledge files use a separate MinIO bucket with no public URLs: the backend author-checks and streams content, while the public S3 edge returns 404. The edge nginx self-recovers after a sustained local liveness failure and uses a restart policy for Docker daemon or VPS restarts.

nginxDockerMinIOValkeyGitHub Actions

Safe AI access

Seven Agent REST operations are mounted in the main Litestar application without a separate process or Unix socket. A dedicated WireGuard-bound nginx mTLS listener preserves the private boundary with an exact allowlist; the public listener returns 404 for the internal path and strips forged certificate headers. A local stdio MCP bridge exposes exactly five Draft-only operations with no publish, generic CRUD, SQL, shell, or URL fetch. The simplification intentionally shares the backend process, DB role, secrets, and availability: private application-network isolation and trust in nginx remain part of the boundary.

Litestar RESTlocal stdio MCPWireGuardmTLSDraft-only

Engineering decisions

Clean Architecture keeps domain logic independent from Litestar, SQLAlchemy, and external services.
RU/EN localization is split between the UI catalog and content fields, so interface text is not mixed with articles and matrix content.
Privacy-safe analytics count views and reactions without cookies, raw IPs, user-agent strings, or third-party identifiers.
Deployment is treated as a controlled release process with a manual trigger: runtime configuration is rendered from a manifest, CI quality gates are decoupled from the deploy workflow, manual approval on the production environment remains explicit, and blue/green switching with health checks lowers rollout risk.

Quality and operations

Quality is covered by short checks: style, types, unit/integration tests, security, SSR smoke, performance, and SQL plans. They remain CI release evidence, while production deploy runs manually and switches blue/green traffic only after health checks pass. In operations, background jobs, cache, files, and runtime containers have separate responsibilities; public assets are served with CSP and immutable caching.

What is next

Near-term work includes RSS/Atom, a public roadmap, and continued work on observability, performance, and content quality.

Go to articles