Fifty years of engineering doctrine, applied consistently.

Actionary’s architecture is a coherent stack of principles ranging from 1974 (Dijkstra) to 2024 (MCP). Every foundational principle is fifteen to fifty years old. Every modern principle is production-proven at cloud-scale organisations today.

Every principle has an authoritative citation. Every one traces to concrete evidence in the codebase — a repository file, a role in the DB model, a migration number, a tool on the MCP surface.

The table below is the citation table behind every architectural claim we make on this site. Read it as a peer.

The fifteen principles

Where each one lives in the code

Every entry above cashes out as something concrete. Separation of Concerns is the three-layer backend: services/core_api/api/v1/routers/ (HTTP), services/core_api/application/ (domain logic), services/core_api/infra/repositories/ (persistence). Least Privilege is the five-role DB model — crm_user, crm_app, crm_platform_admin, crm_schema_owner, crm_migrate — each role scoped to one purpose, NOSUPERUSER NOBYPASSRLS where it matters. PoEAA is 87 repository files, one per aggregate, with a CI lint (.github/workflows/inline_sql_budget.yml) that fails any pull request introducing inline SQL in a router.

Hexagonal Architecture is two HTTP adapters over one core: 55 REST routers in core_api and 72 MCP tools in services/mcp_server/. Storage swaps between local disk, S3, R2, MinIO, and Backblaze through shared/storage/storage_adapter.py — one env var. LLM provider swaps between Anthropic, OpenAI, Bedrock, Azure OpenAI, and Gemini through services/core_api/application/llm/base.py — one factory branch.

Row-Level Security lives at the substrate. Migration 338 enabled RLS on every tenant-scoped table; policies key on app.current_tenant_id; crm_app cannot bypass RLS even under a hostile query. Feature-Sliced Design is 21 modules under apps/web/src/features/. MCP is a first-class service alongside core_api and apps/web.

Every claim on the architecture page resolves to a file path in this repository. That is the point.

The applied stance

Cockburn’s Hexagonal Architecture puts adapters at the boundary and business logic at the core. Wiggins’s Twelve-Factor App says dependencies are explicit and backing services attach through config. Martin’s Chapter 32 warns “Do not marry the framework.” Read together they compose into one stance:

Open standards at the infrastructure boundary. Code we own at the application core.

At every layer where a real open standard exists, Actionary ships a thin adapter. PostgreSQL 16. S3-API. Redis wire protocol. OpenTelemetry OTLP. MCP. OAuth 2.1 with DCR and PKCE. HTTP + OpenAPI. Every one has multiple compatible implementations; the substrate is portable by construction.

At every layer where the “ecosystem” is an opinionated framework masquerading as a standard, we own the code. The RAG pipeline is a few hundred lines in services/core_api/application/upload_indexer_service.py — extract, chunk, embed, persist — writing against pgvector through content_asset_chunks_repository.py. The workflow engine is workflow_runs plus FOR UPDATE SKIP LOCKED. Agent orchestration is propose-then-execute on the MCP tool surface. Permission enforcement is Postgres RLS plus a _permissions contract computed server-side on every list response.

Roads not taken

Each alternative gets a reason.

LangChain, LlamaIndex — orchestration middleware. Their patterns fit a specific shape of problem. When the business logic encodes decisions specific to Actionary’s entity model, its record_access predicate, and its audit-log integration, imported abstractions get in the way.

Pinecone, Weaviate — hosted vector databases. Adopting one means data leaves Postgres. Backup surface splits in two. Audit surface splits in two. The RLS visibility gate does not apply to the external store; a second implementation would be needed. pgvector on the same Postgres keeps every one of those a single-surface concern.

Temporal, Airflow — durable-execution frameworks. Adopting one means a second stateful service in the deploy topology when workflow_runs on Postgres already delivers the same idempotent-step guarantee.

Kafka, RabbitMQ — dedicated brokers. Redis lists via BLPOP with an orphan sweep against a Postgres state table is enough at our shape. A dedicated broker becomes the right choice once throughput demands it.

Every one of these is a valid architecture for a codebase built around it. The distinction is which layer of the stack imports the framework. Frameworks at the infrastructure boundary are portable. Frameworks at the application core become the coupling Chapter 32 warns about.

The takeaway

Our architecture is borrowed from decades of production practice. Every principle underneath it has been production-proven at Netflix, Uber, AWS, Microsoft, Apple, Google, and every bank for fifteen to fifty years. The modern principles are what leading cloud-native SaaS builds on today.

That is the point. A technical audience recognises the substrate on day one. A security reviewer, a CTO, or an acquirer inspecting the stack finds citations at every layer. The open-standards boundary means the code is portable. The owned application core means the substrate fits the domain. Every layer traces to a paper on the reading list and a codebase you can audit against it.