Boja is a TypeScript-first, PostgreSQL-backed chat and learning community platform — think Discord meets Skool — built for instant offline resume. Two native frontends (Expo/React Native and React DOM) share design tokens, domain logic, and Zero-powered sync over a single PostgreSQL source of truth. The API plane is Elysia/OpenAPI self-hosted, with Rocicorp Zero providing query-driven partial sync so clients load instantly from local state and catch up in the background. Infrastructure is self-hosted with Cloudflare enterprise services (Stream, R2, Images, CDN) as the media and delivery plane. Billing runs on NMI + value.io through an in-repo immutable double-entry ledger.
| Domain | Decision | Rationale |
|---|---|---|
| Language / runtime | TypeScript + Bun-compatible server | Full-stack type safety, single language, monorepo |
| Monorepo | Bun workspaces | Consistent with Bun runtime, avoids extra toolchain |
| Database | PostgreSQL — source of truth, server_id tenancy | Relational membership, transactions, Zero logical replication |
| Sync engine | Rocicorp Zero (query-driven partial) | Unbounded history + jump-to-message; instant local resume |
| Offline contract | Cached reads + instant resume + durable message-send outbox only | Server authority preserved; narrow local command boundary |
| Native frontend | Expo / React Native | True native rendering, Expo SDK 52+, New Architecture |
| Web frontend | React DOM + Vite + TanStack Router | Separate renderer; shares domain logic and tokens only |
| Design tokens | DTCG format → Terrazzo → web CSS + native TS | One token source; DaisyUI vocabulary on both platforms |
| Web styling | Tailwind v4 + shadcn-style owned components on Base UI | Accessible headless primitives + owned themed components |
| Native styling | Unistyles 3 | Zero-re-render theme switching; typed TS themes; updateTheme for server branding |
| Authentication | Better Auth — identity/sessions only | Boja owns servers, memberships, roles; no auth-plugin drift |
| Permissions | Shared pure-TS layered calculator over capability_key/effect rows | Deterministic, auditable, testable; same code on client + server |
| API layer | Elysia OpenAPI from day one | Versioned HTTP contract; generated MCP + CLI clients |
| Ephemeral realtime | Bun WS gateway + Redis/Valkey TTL | Presence + typing only; no replay requirement |
| Jobs / background | pg-boss (Graphile Worker fallback) | PostgreSQL-native enqueue; transactional outbox→job dispatch |
| Infrastructure | self-hosted production + Cloudflare enterprise plane | Self-hosted ownership; contracted CF edge/media services |
| Files | Private R2 + CF Images/Workers/CDN + self-hosted scan workers | Direct upload, edge delivery, Postgres authorization authority |
| Video / live | Cloudflare Stream (broadcast/VOD) + LiveKit self-hosted (fast-follow) | V1 broadcast bounded; interactive rooms via self-hosted LiveKit |
| Billing | In-repo NMI + value.io service, immutable double-entry ledger | Custom TSYS deal retained; explicit payment/accounting/entitlement facts |
| Merchant of record | Boja is default MoR; future Whop/Stripe as verified adapters | One community membership + entitlement projection |
| Tax | Adapter-isolated Anrok/Avalara candidate | Regulatory specialty; still posts to balanced ledger |
| Search | Meilisearch v1.48 self-hosted (ParadeDB challenger spike) | Hybrid BM25+vector; synonym-friendly; known TRW experience |
| Threads | Threads as channels | Reuses message history, unreads, permissions primitives |
| Bots | First-class service principals, capability-row grants, webhook-first | Explicit identity, scope, rate and audit boundaries |
| Ops CLI | bojastack — admin-API-first with redaction + access-explain | Operator tooling meets same authorization standards as product APIs |
| History boundary | 90-day hot Zero publication + authorized archive API | Bounded synced dataset; explicit source-tier seam |
| DMs | v1 — global dm_conversations model | Launch surface; not modeled as server-owned channels |
| Access model | Invite-only v1; no anonymous or guest access | Reduces authorization ambiguity and public surface |
| Courses | Full TRW-style learning v1 — modules, prerequisites, role rewards | Courses are paid-community core, not later add-on |
| Synonyms | Platform-wide dictionary v1; per-server fast-follow | Domain jargon + creator terminology is a launch hard requirement |
| Greenfield posture | New company; TRW is prior-art evidence only, no migration | No legacy data, compatibility machinery or service coupling |
server_id tenancy.tax_payable:<jurisdiction>.dm_conversations model, not server-owned channels.