AD-001: Bowrain Vision and Module Architecture

Summary

Bowrain is the full-stack content platform built on the neokapi framework. It adds a versioned content store, bidirectional connectors to live systems, event-driven automation, multi-user workspaces, and collaborative editing on top of the framework's streaming pipeline. Bowrain ships as three Go modules — bowrain/core (shared platform types), bowrain/plugin (plugin behavior + the kapi-bowrain project-sync plugin binary), and bowrain (server, workers, desktop and web apps) — all licensed under AGPL-3.0, except the Apache-2.0 bowrain/plugin/schema recipe-vocabulary sub-module.

Context

The neokapi framework is the Apache-licensed core: content model, formats, tools, pipeline executor, plugin system, content memory, terminology, and AI/MT providers. It has zero platform dependencies — no database, no server, no authentication. See AD-framework-001: Vision and Module Architecture.

Bowrain is the commercial-grade platform layered on top. It persists content, syncs with live systems (CMS, design tools, code repos, marketing platforms), runs multi-user workflows, and exposes a REST + gRPC server, a Wails desktop app, a SaaS web UI, and admin control surfaces. The framework is one consumer agnostic; Bowrain is opinionated about persistence, sync, connectors, authentication, and collaboration.

The license boundary is structural: framework code is Apache-2.0 and never depends on AGPL code; every module under bowrain/ is AGPL-3.0. CI enforces this with GOWORK=off builds against the framework module.

Decision

Identity

Bowrain is a content platform, dual-licensed under AGPL-3.0 and a commercial license. It is available as a SaaS offering and for open-source self-hosting. Its job is to turn the framework's pipeline into a production-ready, multi-user system with persistent state, real-time collaboration, and integrations with the tools that already hold content.

Design principles:

1. Connector-first. Integration with live systems — CMS, design tools, code repositories, marketing platforms, TMS — is the primary integration mechanism. File formats are one connector category, not the whole story. See AD-008: Connector System.
2. Content-addressable blocks. Blocks are keyed by content hash, enabling deduplication across sources, incremental sync that only transfers changed content, and efficient version diffing. See AD-004: Content Store and Versioning.
3. Event-driven automation. Every content mutation emits a typed event. Automation rules, connector publishers, graph syncers, and background workers subscribe to these events.
4. Real-time collaboration. The desktop app, web UI, and embedded panels all connect to a single server instance via gRPC streaming. Block edits, presence, and memory/terminology updates propagate to every connected client.
5. Per-workspace multi-tenancy. Workspaces are the top-level isolation unit. Every project, token, connector, blob, and background job carries a workspace ID. See AD-002: Authentication and Workspaces.

Three Bowrain Modules

Bowrain is composed of three independent Go modules, each with its own go.mod:

Module	Import Path	Directory	Role
bowrain/core	github.com/neokapi/neokapi/bowrain/core	bowrain/core/	Shared platform types and interfaces: project model, auth, connector, store, event, client, agent
bowrain/plugin	github.com/neokapi/neokapi/bowrain/plugin	bowrain/plugin/	Plugin behavior (schema, commands, connector, MCP) + the kapi-bowrain plugin binary: kapi.yaml recipe init, push, pull, status, auth
bowrain	github.com/neokapi/neokapi/bowrain	bowrain/	Server, workers, desktop and web apps, storage implementations

Dependency rules, verified in CI with GOWORK=off builds:

framework (root, Apache-2.0)
    ↑
    ├── cli (shared CLI base, framework only)
    │    ↑
    │    └── bowrain/plugin (framework + cli + bowrain/core)
    │
    └── bowrain/core (framework only — pure types/interfaces)
         ↑
         ├── bowrain/plugin (framework + cli + bowrain/core)
         └── bowrain (framework + bowrain/core)

Key constraints:

• bowrain/core depends only on the framework module. It contains pure types and interfaces — no Cobra, no Viper, no SQLite, no Wails, no Echo, no OIDC, no keychain bindings. Every package that wants to share platform types without taking on platform dependencies imports from bowrain/core.
• bowrain/plugin depends on framework + shared CLI + bowrain/core. It is the only module that combines the shared CLI base with platform types.
• bowrain depends on framework + bowrain/core. It does NOT depend on the shared CLI module — the server and its apps don't need Cobra.
• Kapi and bowrain have no dependency on each other.

Module Contents

bowrain/core/ holds:

Package	Purpose
project/	Workflow facade pairing the framework's KapiProject recipe loader with the on-disk Layout: server-block helpers, sync cache, URL parsing
auth/	Auth types (User, Workspace, Token), JWT handling, PKCE, device flow client
connector/	ConnectorBase, IntegrationConnector, SourceConnector interfaces
client/	REST client for Bowrain Server
store/	ContentStore interface + domain types (Project, Version, Asset)
event/	Event types + bus interface
agent/	Agent mode types, session grants
config/	Auth persistence helpers

bowrain/plugin/ holds:

Package	Purpose
cmd/kapi-bowrain/	The manifest-driven kapi-bowrain plugin binary kapi dispatches to (Mode A/B/C)
commands/	Project commands (init, status, diff, pull, push, auth, stream, …) registered via cli.RegisterCommandFactory
connector/	BowrainSourceConnector
mcp/	Bowrain MCP tools
schema/	Recipe extension decoders (own Apache-2.0 go.mod)

The plugin registers its commands, MCP tools, and recipe schema against the shared CLI base's registries via init(). The shared CLI module never imports bowrain/core/project.

bowrain/ holds the full platform:

Subdirectory	Purpose
cmd/bowrain-server/	REST (Echo v4) + gRPC API server
cmd/bowrain-worker/	Background worker (async push, asset processing, etc.)
server/	HTTP/gRPC handlers, middleware chain
service/	Business logic — auth, project, connector, flow services
auth/	OIDC integration, AuthStore (SQLite + PostgreSQL)
store/	ContentStore implementations (SQLite + PostgreSQL)
storage/	Shared SQLite + PostgreSQL migration utilities
connector/	Concrete connector implementations
event/	Event bus implementation + automation engine
billing/	Subscription and quota management
jobs/	Background job processor
brand/	Brand voice profiles, tag dimensions
graph/	Brand knowledge graph — plain-SQL (default) and Apache AGE (opt-in) backends
analytics/	Usage analytics and reporting
memory/	SQLite + PostgreSQL content memory implementation
terms/	SQLite + PostgreSQL terms store implementation
proto/	Protobuf definitions for gRPC and sync
apps/bowrain/	Wails v3 desktop app (Go + React/TypeScript)
apps/web/	SaaS web UI
apps/ctrl/	Admin control panel
apps/pulse/	Public real-time dashboard
apps/keycloak-theme/	Custom Keycloak theme
packages/ui/	@neokapi/ui AGPL component library

Binaries and Apps

Binary / App	Module	Role
kapi-bowrain plugin	bowrain/plugin	Project-centric sync commands dispatched via kapi, analogous to git
bowrain-server	bowrain	Echo v4 REST + gRPC server (multiplexed on one port via h2c)
bowrain-worker	bowrain	Background worker for async push, asset processing, events
apps/bowrain	bowrain	Wails v3 desktop app
apps/web	bowrain	SaaS web UI
apps/ctrl	bowrain	Admin control panel
apps/pulse	bowrain	Public real-time dashboard

The server multiplexes gRPC and HTTP on the same port via h2c (cleartext HTTP/2) protocol detection: requests with Content-Type: application/grpc are routed to gRPC, all others to the HTTP router. See AD-009: Sync Protocol for the sync endpoints.

Relationship to the Framework

Bowrain consumes framework interfaces and never forks them. The key framework interfaces Bowrain uses:

Framework Interface	Bowrain Use
format.DataFormatReader/Writer	Connector implementations extract and re-emit Parts
tool.Tool	Server-side flows run the same tools as the CLI
flow.Executor	The server executes flows via the same executor
aiprovider.LLMProvider	AI translation, QA, and review tools use the same provider interface
mtprovider.MTProvider	MT translation tools likewise
core/storage.BlobStore	Bowrain provides Azure Blob and local filesystem implementations. See AD-007: Media and Blob Storage.
memory.ContentMemory	Bowrain provides SQLite + PostgreSQL implementations
terms.Terminology	Bowrain provides SQLite + PostgreSQL implementations
plugin registries	Bowrain hosts format and tool plugins via gRPC + Java bridge

The framework never imports bowrain/*. Bowrain never forks framework types. Shared types live in bowrain/core so that packages like bowrain/auth can re-export them via Go type aliases for backward compatibility.

Workspace Coordination

A top-level go.work at the repository root lists all the Go modules (framework, host, shared CLI, kapi, kapi-desktop, bowrain/core, bowrain/plugin, bowrain/plugin/schema, bowrain, and the scripts/* tooling modules) so that a single go build ./... from the root resolves cross-module imports without replace directives. Each child module still declares replace directives in its own go.mod for CI builds with GOWORK=off — these CI builds catch accidental cross-module imports before they reach main.

Each module is tagged independently:

v0.16.0              → framework
bowrain/core/v0.1.0    → bowrain/core
bowrain/plugin/v0.1.0  → bowrain/plugin
bowrain/v0.16.0        → bowrain

Frontend Workspace

A root package.json npm workspace coordinates every frontend package under the monorepo. Apache-2.0 packages (packages/ui, packages/flow-editor, packages/storybook-config) are shared by both kapi-desktop and bowrain apps. AGPL-3.0 packages live under bowrain/packages/ui (@neokapi/ui) and bowrain/apps/*. vp install at the repo root installs all workspace members.

Consequences

• Each binary carries only the dependencies it needs. The kapi-bowrain plugin has no Wails, Echo, or OIDC; bowrain-server has no Cobra; kapi CLI has no bowrain at all.
• The module split inside bowrain/ lets bowrain/core evolve as a stable types contract while bowrain/plugin and bowrain iterate on behavior.
• All AGPL-3.0 code is contained within the bowrain/ subtree, making the license boundary visually obvious and verifiable in CI.
• The framework stays Apache-2.0 and fully reusable by any consumer; Bowrain is one of them.
• Content flows from connectors into the ContentStore, gets processed by framework tools, and flows back to its source system — the same streaming pipeline that powers the standalone CLI.
• Single-binary distribution: each server binary is a static Go binary with no JVM, no Node.js runtime, and no container required for basic usage.

Related

• AD-002: Authentication and Workspaces
• AD-004: Content Store and Versioning
• AD-008: Connector System
• AD-009: Sync Protocol
• AD-framework-001: Vision and Module Architecture