System Architecture

System Architecture

PlantUML diagrams for Flowbot system architecture. Render with any PlantUML-compatible tool (VS Code extension, plantuml.com, CLI, etc.).

Diagrams

File Type Description
architecture.puml Component Diagram Overall system architecture and component relationships
layers.puml Layered Diagram Abstraction layers from infrastructure to entry points
dataflow.puml Sequence Diagrams Key data flows: chat message, workflow, events, hub, notifications
deployment.puml Deployment Diagram Docker containers, CI/CD pipelines, external services

Agent engine (pkg/agent/) has dedicated docs and diagrams under docs/agent/ (architecture.md, agent.puml).

Analytics (personal usage + ops run health) has dedicated docs under docs/analytics/.

pkg vs internal dependency boundaries (migration waves): pkg-boundaries.md.

Rendering

# CLI (install plantuml)
plantuml docs/architecture/*.puml

# VS Code: install "PlantUML" extension and preview in-editor
# Online: https://www.plantuml.com/plantuml/uml/

Architecture Overview

Layers (top to bottom)

Layer 6 — External:        Users, Chat Platforms, Third-Party APIs
Layer 5 — Platform:        Discord/Slack/Tailchat adapters
Layer 4 — HTTP Gateway:    Fiber v3 server, REST API, auth middleware
Layer 3 — Business Logic:  modules, workflow engine, pipeline engine, LLM, agent engine
Layer 2 — Capability:      capability.Invoke() abstraction over providers
Layer 1 — Providers:       third-party service integrations (pkg/providers)
Layer 0 — Infrastructure:  PostgreSQL, Redis, Docker/kern executor

Management Plane (side plane)

Homelab Scanner → App Registry → Hub Manager → Capability Binding → Capability Layer
                                  ↑
                     Discovery Engine (labels + runtime probes)

Standing orders (do not restate)

Root AGENTS.md. Pagination: pkg/capability/AGENTS.md. pkg vs internal: pkg-boundaries.md. Auth call paths: pkg/auth/AGENTS.md. Hub lifecycle audit: internal/server/AGENTS.md.

Data Flows

  1. Chat Message: User → Platform → Adapter → Server → Module → capability.Invoke() → Provider → API
  2. Workflow: Trigger → Automate module → Workflow Engine → Executor (Docker/kern) → capability steps → Notifications
  3. Durable Events: DataEvent → PostgreSQL (data_events) → Redis Stream Outbox → Pipeline → Actions
  4. Hub Management: Homelab Scan → Discovery (labels + probes) → App Registry → Hub → Capability Binding
  5. Notifications: Module / CapCore notify_send → Dispatcher → [Slack, Pushover, ntfy, Message Pusher, inapp]

Entry Points

Binary Path Description
Server cmd/main.go HTTP server (Fiber v3 + fx DI)
Admin CLI cmd/cli/ User/token management, config, pipeline/workflow admin
Composer CLI cmd/composer/ Admin actions, website docs, and SKILL.md generation

Modules (5)

analytics, automate, example, hub, web

automate owns REST under /service/automate/{functions,pipeline,workflow} (scopes remain function:* / pipeline:* / workflow:*). See merge note.

Providers (24)

beszel, confluence, dozzle, drone, email, example, fireflyiii, gitea, github, grafana, kanboard, karakeep, memos, miniflux, netalertx, nocodb, scanopy, slack, traefik, transmission, trello, trilium, uptimekuma, wakapi

Capability packages (pkg/capability/)

confluence, core, devops, drone, email, example, fireflyiii, functions, gitea, github, kanboard, karakeep, memos, miniflux, nocodb, transmission, trello, trilium — plus conformance/

Notifications

Outbound: Slack, Pushover, ntfy, Message Pusher (with rules/ throttling/aggregation and template/). In-app: pkg/notify/inapp. CapCore notify_send is the pipeline/capability entry; see notification-gateway.md.

Shared Packages (35)

agent, auth, backoff, bulkhead, cache, capability, client, config, cronutil, event, exec, executor, flog, functions, homelab (with probe/), hub, i18n, media, metrics, module, notify, parser, pipeline, profiling, providers, rdb, route, stats, trace, types, utils, validate, views, webauth, workflow

CI/CD (.github/workflows/)

Workflow Description
build.yml Lint + Build
testing.yml Run all tests
build_cli.yml Build CLI tools
docker.yml Build Docker image
docker-agent-sandbox.yml Build agent sandbox image
docker-browser-cdp.yml Build Lightpanda / Playwright CDP images
agent-eval.yml Agent evaluation (regression)
release.yml Release pipeline
pages.yml Publish website to GitHub Pages