Developer Guide

Developer Guide

Operations and development documentation for Flowbot.

Contents

  • Deployment — Binary, Docker, and systemd deployment methods with health checks
  • Monitoring — Grafana dashboard, Prometheus metrics via PushGateway, and alerting rules
  • Tracing — OpenTelemetry distributed tracing across all components
  • Conformance — Ability adapter conformance test suite for provider development
  • Cursor Cloud — Per-session PostgreSQL/Redis bootstrap and Cloud config gotchas

Development Tools

Build

go tool task build           # Main server
go tool task build:composer  # Composer CLI
go tool task build:cli       # Admin CLI
go tool task build:all       # All binaries
go tool task air             # Live reload

Code Generation

go tool task swagger   # Generate Swagger/OpenAPI docs
go tool task skills    # Generate SKILL.md files for CLI capabilities
go tool task webdoc    # Generate website docs from markdown sources
go tool task ent       # Generate ent code from database schema
go tool task templ     # Generate Go code from Templ templates

Code Quality

go tool task lint      # revive + actionlint + testifylint + oxlint
go tool task format    # go fmt + oxfmt
go tool task tidy      # go mod tidy

Security

go tool task secure    # govulncheck
go tool task leak      # gitleaks
go tool task gosec     # security scan
go tool task check     # all security & quality

XSS / Markdown HTML

User- or agent-controlled markdown rendered in the browser must go through
pkg/utils.MarkdownToSafeHTML (goldmark + bluemonday.UGCPolicy() with KaTeX
extensions). Do not pass unsanitized output to templ.Raw or template.HTML.
html.WithUnsafe() inside MarkdownToHTML only preserves markdown-embedded HTML
during conversion; sanitization is mandatory afterward.

Known templ.Raw call sites (all require pre-sanitized HTML):

  • pkg/views/partials/agent_resource_preview.templ — agent resource preview
  • pkg/views/partials/chatagent_message.templ — chatagent assistant/thinking HTML

Testing

go tool task test            # All unit tests
go tool task test:short      # Short mode (skip integration)
go tool task test:specs      # BDD acceptance tests (requires Docker)
go tool task test:coverage   # Coverage report

Conformance Tests

go test ./pkg/ability/...                                # All ability + conformance tests
go test -run TestConformance ./pkg/ability/bookmark/karakeep/  # Single adapter
go test ./pkg/ability/conformance/                       # Conformance framework self-tests

Add Go Tool Dependency

go get -tool import_path@version

systemd Service

The flowbot.service file is provided for headless Linux deployments.