Overview

Message flow

Channel adapter
  → POST /v1/messages (api)
  → store.PutMessage                     all messages (inbound/outbound/delegation)
  → gateway.messageLoop (polls every 2s)
  → store.NewMessages (unprocessed since lastTimestamp)
  → impulseGate.accept(jid, msgs)       weight-based batching (100 threshold)
  → Three-layer pipeline:
      1. Sticky layer                    absorbs bare @name/#topic tokens
      2. Command layer                   matches slash-prefixed tokens (/new, /ping)
      3. Prefix layer                    inspects @name/#name inline, navigates to child/topic
      4. Routing layer                   walks routes table (seq order, match expressions)
  → queue.EnqueueMessageCheck
  → processGroupMessages
      → store.MessagesSince              per-chat agent cursor
      → store.FlushSysMsgs              XML system events prepended
      → router.FormatMessages            XML message batch
      → grants.DeriveRules               inject into start.json
      → container.Run                    docker run -i --rm
      → stream output
      → router.FormatOutbound            strip <internal> and <think> tags
      → store.PutMessage                 outbound messages return to unified path
  → POST /send to channel adapter

Daemons

Name	Language	Role
`gated`	Go	Message loop, routing, container dispatch
`timed`	Go	Cron poll, inserts scheduled messages
`onbod`	Go	Onboarding state machine (optional)
`dashd`	Go	Operator dashboard (HTMX, read-only)
`proxyd`	Go	Auth perimeter; /pub/ is public, everything else JWT-gated; /dash/, /auth/, Vite proxy
`teled`	Go	Telegram Bot API adapter (long poll)
`discd`	Go	Discord Gateway adapter (websocket)
`mastd`	Go	Mastodon streaming adapter
`bskyd`	Go	Bluesky firehose adapter
`reditd`	Go	Reddit polling adapter
`emaid`	Go	Email adapter (IMAP/SMTP)
`whapd`	TypeScript	WhatsApp adapter (Baileys multidevice)

SQLite tables

Table	Purpose
`messages`	All inbound and outbound messages; primary poll target for the gateway
`chats`	Known JIDs with name, channel, and error flag
`routes`	Routing rules: seq, match expression (key=glob pairs), target group
`registered_groups`	Active groups with folder, trigger word, container config, parent, slink token
`sessions`	Current Claude Code session ID per (group_folder, topic)
`session_log`	Historical session records with start/end time and result
`system_messages`	XML system events prepended to agent prompts
`scheduled_tasks`	Cron and one-shot tasks with status and next_run
`router_state`	Key/value persistence for lastTimestamp, lastAgentTimestamp
`auth_users`	Web auth accounts (argon2 hashed passwords)
`auth_sessions`	JWT refresh token hashes with expiry
`user_groups`	Maps web users to specific group folders
`email_threads`	Maps email thread IDs to chat JIDs
`onboarding`	Per-JID onboarding state machine records

Repository layout

cmd/arizuko/        CLI entrypoint (generate, run, create, group, status)
core/               Config, types, Channel interface
store/              SQLite persistence
api/                HTTP API server (channel protocol endpoints)
auth/               Identity, authorization, JWT, OAuth, middleware
chanreg/            Channel registry, health checks, HTTP channel proxy
gateway/            Main loop, message routing, commands
container/          Docker spawn, volume mounts, sidecars, runtime, skills seeding
ant/                In-container agent (TypeScript entrypoint + skills)
  skills/           Agent-side skills seeded into ~/.claude/skills/
queue/              Per-group concurrency, stdin piping
router/             Message formatting, routing rules
compose/            Docker-compose generation from *.toml service configs
ipc/                MCP server (unix socket per group, runtime auth via auth)
diary/              YAML frontmatter diary annotations
groupfolder/        Group path resolution and validation
mountsec/           Mount allowlist validation
chanlib/            Shared HTTP + auth primitives for channel adapters
grants/             Grant rule engine
notify/             Operator notification fan-out
gated/              Gateway daemon entrypoint
timed/              Scheduler daemon
onbod/              Onboarding daemon
dashd/              Operator dashboards
proxyd/             Web proxy
teled/              Telegram adapter
discd/              Discord adapter
mastd/              Mastodon adapter
bskyd/              Bluesky adapter
reditd/             Reddit adapter
emaid/              Email adapter
whapd/              WhatsApp adapter (TypeScript)

Data directory layout

/srv/data/arizuko_foo/
  .env                            config (gateway reads from cwd)
  store/
    messages.db                   SQLite database
  groups/
    <folder>/                     one directory per group
      CLAUDE.md                   agent instructions
      SOUL.md                     agent persona
      diary/                      dated diary entries
      episodes/                   archived session transcripts
      facts/                      freeform injected knowledge
      users/                      per-sender JID files
      logs/                       container run logs
      media/                      received media files
  data/
    ipc/
      <folder>/
        gated.sock                MCP unix socket
        sidecars/<name>.sock      sidecar MCP sockets
  web/
    pub/                          public web apps (served at /pub/)
    vhosts.json                   virtual host map (reloaded every 5s)
  services/
    *.toml                        additional compose service definitions