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 — Capability adapter conformance test suite for provider development
  • Cursor Cloud — Per-session PostgreSQL/Redis bootstrap and Cloud config gotchas
  • Contributing — PR checklist, Agent Notes, lint/test expectations

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 native binaries

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 gosec     # security scan
go tool task check     # lint + secure + gosec

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

Policy (which layer, behavior vs correctness, assembled example): docs/testing/README.md.

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/capability/...                             # All capability + conformance tests
go test -run TestConformance ./pkg/capability/karakeep/  # Single adapter
go test ./pkg/capability/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.