PocketBase for Arizuko

Should arizuko adopt PocketBase? Technical Analysis

What is PocketBase?

PocketBase is a single-binary Go backend (15MB) that bundles:

• SQLite database (WAL mode, embedded)
• Real-time subscriptions (SSE, not WebSocket — unidirectional server→client)
• Authentication (users, OAuth providers, JWT)
• File storage (local filesystem or S3)
• Admin dashboard (CRUD UI for collections)
• REST API (auto-generated from schema)

Philosophy: Ship as a single executable, extend via Go library (embed PocketBase as a package, add custom routes/hooks)

Arizuko's Current Stack

Let's map arizuko's architecture to PocketBase's features:

Feature	PocketBase	Arizuko	Overlap?
Database	SQLite (WAL mode, embedded)	SQLite (WAL mode, store/ package, 5s busy timeout)	✅ Identical
Auth	Built-in users table, OAuth (Google/GitHub/Discord), JWT sessions	auth/ package: OAuth (Google/GitHub/Discord/Telegram), JWT, auth_users/auth_sessions tables, argon2 hashing	✅ Identical feature set
Real-time	SSE subscriptions on collections (create/update/delete events)	SSE via proxyd web channel (web: JIDs), poll-based message delivery	⚠️ Different model (arizuko: message-centric, not CRUD-centric)
Admin UI	Built-in HTMX dashboard for CRUD	dashd/: read-only HTMX portal (status, tasks, activity, groups, memory)	⚠️ Different purpose (arizuko: observability, not CRUD)
File storage	Local FS or S3, tied to collection fields	Media enricher: attachments → groups/<folder>/media/, Whisper transcription	⚠️ Different model (arizuko: message-attached, not collection-attached)
REST API	Auto-generated from schema	api/ package: /v1/messages, /v1/channels/register (custom, not auto-generated)	❌ No overlap
Routing	N/A	router/ + routes table: match expressions, three-layer pipeline (sticky → command → prefix → routing)	❌ Arizuko-specific
Channels	N/A	chanreg/: HTTP channel protocol, health checks, adapter registry (Telegram/WhatsApp/Discord/etc.)	❌ Arizuko-specific
Agents	N/A	gateway/ + container/: Docker orchestration, IPC (MCP over unix sockets), grants engine	❌ Arizuko-specific

Analysis: Where PocketBase Would (Not) Fit

❌ Core Gateway (gated)

Why not:

• Arizuko's store/ package is already optimized for the message-routing-agent flow
• PocketBase's collection-based CRUD model doesn't map to arizuko's messages table semantics (e.g., agent_cursor, routed_to, topic, audit metadata)
• Routing layer (router/) needs direct SQL access to routes table with seq-ordered match expressions — PocketBase's auto-generated API wouldn't help
• Gateway polls store.NewMessages() every 2s with custom filtering (is_from_me=0, cursor tracking) — PocketBase's real-time SSE is push-based, not poll-based

Verdict: No value. Arizuko's store/ is leaner and purpose-built.

❌ Auth (proxyd + auth/)

Why not:

• Arizuko's auth/ package already does OAuth (4 providers), JWT, argon2 hashing, refresh tokens
• PocketBase's auth is tightly coupled to its collections model — arizuko's auth is decoupled (used by proxyd, dashd, IPC authorization)
• Arizuko's user_groups table restricts web users to specific group folders — PocketBase doesn't have this concept
• Login rate limiting (5 attempts/15min per IP) is custom-coded in auth/web.go — PocketBase would require hooks to replicate

Verdict: No value. Arizuko's auth is already feature-complete and integrated.

⚠️ Dashboard (dashd)

Current state: dashd is read-only HTMX, shows system observability (channels, groups, queue, tasks, routing table)

PocketBase could offer: If dashd ever needs CRUD operations (e.g., edit routes, manage groups, update task schedules), PocketBase's admin UI could accelerate development

But:

• Arizuko's domain model (routes with match expressions, groups with tiers, tasks with cron) requires custom forms — PocketBase's auto-generated UI wouldn't fit
• dashd is intentionally read-only (operators use arizuko CLI or MCP tools for mutations)
• Adding write operations would bypass grants engine + authorization checks unless carefully integrated

Verdict: Marginal value. Custom HTMX forms are probably simpler than PocketBase integration.

✅ New Standalone Services

Where PocketBase shines:

If arizuko needs a **new service** with standard CRUD + auth requirements (not tightly coupled to routing/channels/agents), PocketBase could be a fast MVP path:

• Group Management UI — Web app for creating groups, assigning users, browsing memory files
• Metrics Dashboard — Collect agent performance metrics (tokens, latency, cost), store in SQLite, visualize with PocketBase's admin UI
• Knowledge Base — Community-contributed facts, recipes, cookbooks (separate from agent memory)
• User-facing Chat UI — Alternative to proxyd's SSE-based web channel, using PocketBase's real-time for simplicity

Example: Metrics Service

// metrics/main.go
package main

import (
    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/apis"
)

func main() {
    app := pocketbase.New()

    // Custom route: POST /api/metrics (called by gateway after agent run)
    app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
        e.Router.POST("/api/metrics", func(c echo.Context) error {
            // Store agent metrics: folder, session_id, tokens, latency, cost
            // Auto-generates REST API for querying
        })
        return nil
    })

    app.Start()
}

Benefits:

• Single binary (15MB)
• Instant REST + real-time API
• Admin UI for exploring metrics
• No need to write CRUD boilerplate

Verdict: Yes — PocketBase is ideal for ancillary services that don't touch core routing/agent logic.

Technical Deep Dive: Why Arizuko's Stack is Better

1. Message Flow Model

PocketBase: CRUD-centric (create/read/update/delete on collections)

Arizuko: Message-flow-centric (inbound → routing → agent → outbound)

PocketBase's real-time model assumes you're building a typical web app (to-do lists, user profiles, comments). Arizuko's message table has specialized semantics:

• agent_cursor — per-chat read pointer for incremental message delivery
• routed_to — audit trail of which group processed the message
• topic — web channel topic routing (multi-topic sessions per JID)
• is_from_me, is_bot_message — filters for poll loop
• source — canonical adapter-of-record for outbound routing

PocketBase's collection API wouldn't expose these semantics cleanly. Arizuko's store.NewMessages(), store.MessagesSince(), store.PutMessage() are purpose-built.

2. Routing Complexity

Arizuko's routing is a three-layer pipeline with match expressions:

1. Sticky layer — Absorbs bare @name/#topic tokens
2. Command layer — Matches /new, /ping, /stop
3. Prefix layer — Inspects @name/#topic inline, navigates to child group or topic session
4. Routing layer — Walks routes table (seq order, match expressions like platform=telegram verb=mention)

PocketBase has no concept of "routing" — it's a CRUD backend. You'd have to reimplement the entire routing logic on top of PocketBase, losing all benefits.

3. Channel Protocol

Arizuko's channel adapters (Telegram, WhatsApp, Discord) register via HTTP, health-check every 30s, and receive outbound messages via POST /send. This bidirectional HTTP protocol is custom to arizuko's architecture.

PocketBase has no concept of "channels" — you'd have to build chanreg/ logic on top, again losing benefits.

4. Grants Engine

Arizuko's grants engine controls which MCP tools/actions a group can use, with rule merging for delegation (NarrowRules). This is tightly coupled to IPC authorization checks.

PocketBase's auth is collection-level (read/write permissions on collections), not action-level. You'd need to bolt on custom middleware, duplicating effort.

5. Single Binary vs Microservices

PocketBase's selling point: Single 15MB binary for rapid prototyping

Arizuko's reality: Already ships as a single Docker image (arizuko:latest) with all daemons (gated, timed, dashd, teled, etc.) compiled into one image. The compose file spawns multiple containers, but they share the same binary.

PocketBase doesn't simplify deployment here — arizuko's compose-based deployment is already streamlined.

Comparison: PocketBase vs Arizuko SQLite

Aspect	PocketBase	Arizuko	Winner
SQLite setup	Auto-configured (WAL mode, busy timeout)	Manual (store/ package, 5s timeout, migration via PRAGMA user_version)	PocketBase (less boilerplate)
Schema migrations	Built-in migration system with Go API	Custom dbmig/ library (keyed by service name, SQL files in migrations/)	PocketBase (more polished)
Real-time	SSE (unidirectional, collection events)	SSE via proxyd (message events, web channel JIDs)	Tie (both use SSE, different semantics)
Auth	OAuth + JWT + refresh tokens (tied to collections)	OAuth + JWT + refresh tokens (decoupled, custom user_groups)	Arizuko (more flexible for multi-tenancy)
Admin UI	Auto-generated CRUD forms	Custom HTMX dashboards (read-only, observability)	PocketBase (for generic CRUD), Arizuko (for custom domain)
Extensibility	Hooks (~30+ events), embed as Go library	No hooks system (direct function calls across packages)	PocketBase (cleaner for plugins)
Performance	Single-instance SQLite (WAL mode, limited concurrency)	Single-instance SQLite (same limits, shared across daemons via WAL)	Tie
Deployment	Single binary (15MB)	Docker image (multi-daemon, shared binary)	PocketBase (simpler for solo services)

Appwrite: The Microservices Alternative

What is Appwrite?

Appwrite is an open-source Backend-as-a-Service (BaaS) written in PHP with Go components (Traefik reverse proxy). Unlike PocketBase's single binary, Appwrite runs as 18 Docker containers orchestrated via Docker Compose.

Features:

• Databases — MariaDB (not SQLite), document-oriented collections with relationships
• Auth — Email/password, OAuth (30+ providers), magic links, phone auth, teams/roles
• Storage — File uploads, image transformations, S3-compatible backends
• Functions — Serverless functions (Docker-based, multiple runtimes: Node, Python, PHP, Dart, Ruby, Go, etc.)
• Messaging — Email, SMS, push notifications
• Real-time — WebSocket subscriptions (bidirectional)
• Hosting — Appwrite Sites for static sites
• GraphQL + REST + WebSocket — Multiple API flavors

Architecture: Appwrite vs PocketBase vs Arizuko

Aspect	Appwrite	PocketBase	Arizuko
Deployment model	18 Docker containers (microservices)	Single 15MB binary	Single Docker image, multi-daemon (gated, timed, dashd, adapters)
Database	MariaDB (separate container)	SQLite (embedded)	SQLite (shared via WAL mode)
Language	PHP (backend) + Go (Traefik)	Go	Go (backend) + TypeScript (agent + whapd)
Real-time	WebSocket (bidirectional)	SSE (unidirectional)	SSE via proxyd (unidirectional)
Serverless functions	✅ Built-in (Docker-based, multi-runtime)	❌ None (extend with Go hooks)	✅ Agent containers (Claude Code, custom logic)
Resource footprint	Heavy (~1GB RAM minimum for 18 containers)	Light (~50MB RAM)	Medium (~300MB RAM for gated + adapters)
Scalability	Horizontal (MariaDB replication, load balancing via Traefik)	Vertical only (single SQLite file)	Vertical only (single SQLite file)
Admin UI	Full-featured web console (teams, permissions, functions, logs)	Auto-generated CRUD forms	Custom HTMX dashboards (read-only observability)
Auth complexity	Full RBAC (teams, roles, permissions per collection)	Simple (users + OAuth)	Custom (JWT + user_groups table, grants engine for actions)
File storage	Advanced (image transformations, compression, S3 backends)	Basic (local FS or S3, tied to collections)	Custom (media enricher, Whisper transcription, local FS)

When to Use Appwrite vs PocketBase

Choose Appwrite if:

• You need horizontal scalability (MariaDB replication, multi-instance deployment)
• You want built-in serverless functions (multiple runtimes, event triggers)
• You need teams + RBAC (complex permissions per collection)
• You're building a collaborative app (WebSocket > SSE for bidirectional real-time)
• You need advanced file storage (image transformations, S3 backends)
• You don't mind 18 containers (Docker Compose is mandatory)

Choose PocketBase if:

• You want zero-ops deployment (single binary, no Docker Compose)
• Your app is small-scale (< 100k users, single-region)
• You prioritize simplicity (Go library, extend with hooks)
• You want to self-host for cheap (runs on $5/mo VPS)
• SQLite is enough (no need for MariaDB replication)

Appwrite vs Arizuko: Architecture Comparison

Similarities:

• Both use Docker Compose for multi-daemon orchestration
• Both support OAuth providers (Google, GitHub, Discord)
• Both have real-time subscriptions (Appwrite: WebSocket, Arizuko: SSE)
• Both have admin dashboards (Appwrite: full CRUD, Arizuko: observability)

Key Differences:

Aspect	Appwrite	Arizuko
Primary use case	Generic BaaS (CRUD apps, web/mobile backends)	Agent orchestration (routing, channels, LLM containers)
Database model	Collections (document-oriented, MariaDB-backed)	Messages + routes + groups (SQLite, custom schema)
Serverless model	Generic functions (Node, Python, PHP, etc.)	Agent containers (Claude Code SDK, TypeScript, MCP tools)
Routing	HTTP reverse proxy (Traefik)	Message routing (match expressions, three-layer pipeline)
Channel protocol	N/A	Custom HTTP bidirectional protocol (adapters for Telegram/WhatsApp/Discord)
Auth grants	Collection-level permissions (read/write/update/delete per team/role)	Action-level grants (MCP tool/action permissions, rule merging for delegation)
Deployment size	18 containers (~1GB RAM)	5-8 containers (~300MB RAM)

Could Arizuko Use Appwrite?

Theoretical fit:

• Auth — Appwrite's OAuth + teams could replace auth/ package
• Storage — Appwrite's file storage could replace media enricher
• Functions — Appwrite functions could... run agents? (awkward fit)

Why it doesn't work:

1. Wrong data model — Appwrite's collections are CRUD-oriented (to-do lists, user profiles). Arizuko's messages table has specialized semantics (agent_cursor, routed_to, topic, source) that don't map to Appwrite's document model.
2. No routing concept — Arizuko's three-layer pipeline (sticky → command → prefix → routing) with match expressions is custom. Appwrite has no equivalent — you'd reimplement routing on top of Appwrite's API, losing all benefits.
3. No channel protocol — Arizuko's bidirectional HTTP channel protocol (adapters register, receive health checks, accept POST /send for outbound) is custom. Appwrite has no concept of "channels."
4. Wrong serverless model — Appwrite functions are stateless, event-driven (like AWS Lambda). Arizuko's agent containers are stateful (session state, multi-turn conversations, MCP unix sockets). Trying to run Claude Code in Appwrite functions would be a nightmare.
5. Deployment bloat — Appwrite adds 18 containers. Arizuko currently runs 5-8 containers (gated, timed, dashd, teled, whapd, etc.). Adding Appwrite would triple container count for features arizuko already has.
6. MariaDB overkill — Arizuko's SQLite works fine (WAL mode, shared across daemons). MariaDB adds operational complexity (replication, backups, connection pooling) without clear benefit for arizuko's scale.

Verdict: ❌ Appwrite is a terrible fit for arizuko core. It's a generic BaaS, not an agent orchestration platform. Using Appwrite would be like using a bulldozer to plant a garden — technically possible, but wildly inappropriate.

Summary: Three-Way Comparison

Platform	Best For	Arizuko Fit?
PocketBase	Solo devs, MVPs, CRUD-heavy side projects (< 100k users)	✅ Good for new standalone services (metrics, group mgmt UI)
Appwrite	Teams building collaborative web/mobile apps (100k-1M users, need RBAC + functions)	❌ Terrible fit (wrong data model, 18 containers, no routing/channels)
Arizuko (custom)	Agent orchestration, multi-channel routing, LLM workflows	✅ Already optimal for its domain

When PocketBase is "Better Than Supabase"

You mentioned PocketBase should be "like Supabase but better" — here's the comparison:

Feature	Supabase	PocketBase	Why PocketBase Wins
Deployment	Cloud-hosted OR self-host (complex: Postgres + PostgREST + GoTrue + Realtime + Storage, ~12 containers)	Single 15MB binary	Radically simpler
Database	PostgreSQL (requires separate server)	SQLite (embedded, no separate server)	Zero ops (for small scale)
Real-time	WebSocket (bidirectional, Postgres LISTEN/NOTIFY)	SSE (unidirectional, simpler)	Less complexity (if you only need server→client)
Auth	GoTrue (separate service, Postgres-backed)	Built-in (SQLite-backed)	Unified (one binary, one DB)
Cost	Free tier (2 projects, 500MB DB, 1GB file storage) → $25/mo (8GB DB, 100GB storage)	Free (self-hosted, unlimited)	$0 forever
Scalability	Horizontal (Postgres replication, read replicas)	Vertical only (single SQLite file, WAL mode = ~10k writes/sec max)	Supabase wins (if you need horizontal scale)
Ecosystem	Mature (PostgREST, pgvector for embeddings, extensions)	Young (limited extensions, SQLite-FTS only)	Supabase wins (richer features)

PocketBase is "better" when:

• You want zero ops (no Docker Compose, no Postgres tuning)
• Your app is single-region, < 100k users
• You prioritize simplicity over scale
• You want to self-host for free (no cloud vendor)

Supabase is better when:

• You need horizontal scale (multi-region, millions of users)
• You want managed hosting (no server maintenance)
• You need Postgres features (pgvector, RLS, full-text search, PostGIS)
• You're building a collaborative app (WebSocket-based real-time is superior to SSE)

Recommendation for Arizuko

Core System: Don't Use PocketBase

Arizuko's store/, auth/, router/, and gateway/ packages are already optimized for the message-routing-agent architecture. PocketBase would be a step backward:

• No simplification — You'd still need custom SQL for routing, agent cursor tracking, channel protocol
• Worse semantics — PocketBase's collection model doesn't map to arizuko's message flow
• More dependencies — PocketBase is 15MB + its own conventions; arizuko's store/ is < 2MB of focused code

Ancillary Services: Consider PocketBase

If you build new standalone services (not part of the routing/agent core), PocketBase could save time:

• Metrics dashboard — Collect agent performance data, auto-generate REST API
• Group management UI — CRUD for groups, users, memory files (separate from dashd)
• Knowledge base — Community recipes, cookbooks, Q&A (not tied to agent memory)

Implementation pattern:

// metrics-service/main.go
package main

import (
    "github.com/pocketbase/pocketbase"
    "github.com/pocketbase/pocketbase/core"
)

func main() {
    app := pocketbase.New()

    // Define "agent_runs" collection: folder, session_id, tokens, latency, cost
    // Auto-generates: GET/POST /api/collections/agent_runs/records

    // Custom webhook: gateway calls POST /api/metrics after each agent run
    app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
        e.Router.POST("/api/metrics", metricsHandler)
        return nil
    })

    app.Start() // Single binary, admin UI at http://localhost:8090/_/
}

Benefits:

• No SQL boilerplate (PocketBase handles CRUD)
• Instant admin UI for exploring metrics
• Real-time API (SSE) for live dashboards
• 15MB binary, deploys alongside arizuko compose stack

Alternative: Encore.ts (from earlier research)

If you're building new TypeScript services for arizuko's ecosystem (not Go), consider Encore.ts instead of PocketBase:

• Infrastructure from Code — Declare databases, Pub/Sub, cron in TypeScript, auto-provision
• 9x faster than Express (Rust runtime)
• Type-safe service communication (perfect for distributed systems)
• Local infra automation (no Docker Compose needed for dev)

Use case: Build a TypeScript webhook service that listens to agent events (via Pub/Sub) and updates external systems (Discord, Slack, analytics)

Final Verdict

Use Case	Recommendation	Why
Core arizuko (gated, store, router, auth)	❌ Don't use PocketBase	Already optimized, PocketBase doesn't fit message-flow model
Dashboard (dashd)	❌ Don't use PocketBase	Custom HTMX is simpler for read-only observability
New standalone services (metrics, group mgmt, knowledge base)	✅ Consider PocketBase	Fast MVP, zero boilerplate, admin UI included
TypeScript services in arizuko ecosystem	✅ Consider Encore.ts	Infrastructure from Code, distributed systems native

Bottom line: PocketBase is great for new CRUD-heavy services, but arizuko's core is already better without it.

---

Recommendation for Communication-First Engineers

Your context: "My weakness is communication.. leaning heavily to shipping and gaming-shipping not really selling my work."

If your strength is shipping (not marketing), here's how to think about these tools:

• PocketBase — Ship faster. Single binary = less explaining, less documentation, fewer moving parts to demo. Perfect for "here's the binary, it works" engineers.
• Appwrite — More to explain. 18 containers = more documentation, more architecture diagrams, more "why did you choose this?" questions. Bad fit if you hate selling complexity.
• Arizuko (custom) — You've already built it. No need to "sell" PocketBase/Appwrite internally. The code speaks for itself. Focus communication energy on:
  • User-facing docs (how to route messages, how grants work)
  • Architecture diagrams (one-pagers for "how does arizuko work?")
  • Cookbooks (copy-paste examples for common tasks)

Gaming-shipping mindset: Treat documentation like game design — users should "discover" features naturally, not read manuals. PocketBase wins here: its admin UI is self-documenting (click around, see what happens). Appwrite loses: 18 containers require upfront study.

For arizuko: Build "discovery tools" instead of docs:

• Interactive CLI — arizuko wizard that walks through setup (like npm init)
• Status dashboard — Make dashd more visual (routing flow diagram, message timeline)
• Example gallery — Pre-configured groups users can clone (arizuko clone telegram-bot)

Ship tools that show instead of docs that tell.

Sources

• PocketBase GitHub
• PocketBase Documentation
• Extend with Go - PocketBase
• Real-time API - PocketBase
• Supabase vs PocketBase: Full Comparison
• Appwrite GitHub
• Appwrite vs Supabase Comparison
• Appwrite's Building Blocks
• Encore.ts - TypeScript Backend Framework
• What is Infrastructure from Code?