Architecture Decisions — Bowrain Platform

This directory contains the Architecture Decisions for the bowrain platform — the hosted, collaborative, SaaS content platform built on neokapi. All content here is AGPL-3.0 licensed.

Bowrain builds on the neokapi framework. Framework-level decisions (content model, processing pipeline, tools, plugins, AI/MT provider interfaces, the kapi project model) live in the framework's Architecture Decisions. This directory describes bowrain-specific choices: the content store, sync protocol, multi-tenant auth, connectors, event bus, server-side AI operations, agent runtime, apps, and billing.

Tactical implementation details (SQL schemas, algorithm pseudocode, wire protocols specific to bowrain) live in Implementation Notes.

Foundation

AD	Title	Scope
001	Vision and Module Architecture	Bowrain identity, AGPL-3.0 boundary, three-module layout, apps inventory
002	Authentication and Workspaces	OIDC federation, PKCE, device flow, workspace multi-tenancy
003	Permissions and Access Control	Capability envelope model, token scopes, session grants

Data Layer

AD	Title	Scope
004	Content Store	PostgreSQL-backed versioned block store
005	Streams	Git-like branching at the content layer
006	Graph Concept Storage	Plain-SQL (default) / Apache AGE (opt-in) graph backends
007	Media and Blob Storage	Content-addressed BlobStore, asset metadata

Connectivity

AD	Title	Scope
008	Connector System	IntegrationConnector, categories, registry
009	Sync Protocol	Desired-state reconciliation, content types incl. context, ownership in the payload
010	Bowrain CLI	.kapi projects with server: block, hooks, MCP
011	REST API	Slug-based hierarchy, route taxonomy

Events & Automation

AD	Title	Scope
012	Distributed Event Bus	Redis Streams (ElastiCache in prod)
013	Automation Engine	Rules, quality gates, run visibility, SSE
014	Translator Workflow	Tasks, activities, notifications, source review
022	Convergence as a Service	Server-side kapi up runs, SSE event stream, server.converge policy, automation collapse

Intelligence

AD	Title	Scope
015	Server-Side AI Operations	Translation jobs, entity extraction, brand voice governance
016	Bravo Agent	ZeroClaw runtime, scoped tokens, identity delegation, MCP cloud

Applications

AD	Title	Scope
017	Bowrain Apps	Desktop, collaborative editor, Pulse, Admin Control Plane
018	Billing	Stripe plans, monthly credits + trial grant, feature matrix, middleware guards

Governance

AD	Title	Scope
019	The correction-learning loop	Corrections promoted into versioned regression-test checks
020	Governance, audit, and rollback	Groups, deny rules, role overrides, status ABAC, separation of duties, tamper-evident audit log, rollback
021	The brand knowledge graph	Concepts and typed relations, change-set governance, blast radius, Brand hub