Bloom Documentation

Bloom is an AI Product Owner that turns conversations into software projects. Users chat with Bloom through Telegram or the web dashboard; Bloom discovers requirements, maintains a living PRD, plans milestones, manages GitHub issues, reviews pull requests, and keeps the user informed across the software development lifecycle.

This is the documentation entry point. Start here and follow the links out. It is also published as a browsable site at bloom-docs.pages.dev, rebuilt and deployed on every push to main (see ci.md and deployment.md).

Start here

• What is Bloom? - the product in five minutes, condensed from the PRD and README.
• Quickstart - clone, install, and run the apps locally via the repo's Make/pnpm targets.
• Core workflows - drive a project through Bloom: create -> milestone plan -> build -> review -> deploy.
• Admin console basics - the grant-gated operations surface.
• Product Requirements Document - vision, goals, functional requirements, and the target technical architecture. The source of truth for what Bloom does.
• Project README - repository overview and getting started.
• Running locally - install, run the API offline, and wire real credentials.
• AGENTS.md - contributing workflow (milestones, issues, branches, PRs) and the quality bar every change must clear. The contract for human and AI contributors.

Architecture

Bloom's SDLC process is defined as data, not code - a stack-agnostic workflow spec that any orchestration engine compiles to. The MVP ships a small built-in interpreter of that spec (so there is no heavy engine dependency); LangGraph remains one possible future adapter behind the same Engine seam.

• Architecture overview - layers, request flow, and the key design seams.
• OpenClaw orchestration runtime design - the M9 boundary between Bloom's product control plane and OpenClaw runtime execution.
• Workflow to OpenClaw execution mapping - how Bloom workflow nodes, reducers, triggers, and tools map to the OpenClaw pilot runtime and future expansion paths.
• The decision graph - Phase 1 (capture) implemented (M14, FR-25); later phases proposed. Making decisions first-class, repo-owned artifacts linked to the milestones, issues, PRs, and code they affect, so the project accumulates its own rationale and blast-radius questions become queries.
• GitHub App setup - registering the App and the bloom-hosted vs client-owned repository model.
• Adopting an existing repository (brownfield) - bind a pre-existing repo as the project target (M44); planning grounds on a read-only codebase snapshot and yields change-tickets (no scaffold), and PRs open against the repo's own default branch.
• GitLab setup - config keys, per-project webhook wiring, and access-token storage for running a project on GitLab (M23 platform-agnostic VCS).
• Coordination & the engineer swarm - the label contract, delegation loop, and the swarm simulator used to test Bloom's Product-Owner coordination end-to-end.
• Engineering engine - the seam behind which Bloom executes a delegated ticket (one issue -> one PR); the contract, run lifecycle, and engine-mode configuration.
• ADR 0001: engine-runner stays on a dedicated VM - why the Claude Code execution worker is the one deliberate exception to the M24 Kubernetes-native deploy model, and how api pods keep reaching it over the tailnet.
• ADR 0002: child-flow runtime - proposed; the gate for #471. When TRUE per-work-item child flow instances are executed rather than projected, they run on the built-in engine's own reserved subworkflow node - not LangGraph subgraphs, Temporal, or an actor framework - per the #470 spike (throwaway prototypes) against the hierarchical-supervisor design's G1-G3 gate criteria.
• TypeScript migration feasibility verdict - M29 decision record, extended by the M30 write-slice, M31 LLM-slice, M32 streaming-slice, M33 domain-layer, M34 persistence+auth, M35 integrations, M36 agents, M37 services+engine, M38 HTTP-routes, and M39 orchestrator/langgraph-core addenda, closing with the M40 cutover plan. The measured per-slice cost of the Python->TS feasibility spike (apps/server + differential parity harness), the parity gaps found, dual-runtime + shared-Postgres coexistence findings, and the verdict against the ~1-dev-week/slice gate: keep strangling toward all-TS - re-affirmed by the first write slice (M30-3), the first LLM/agent slice (M31-4), the first streaming (SSE) slice (M32-4), and finally the orchestrator/workflow/ langgraph core (M39-9) gate re-measurements, then extended by the M33 domain-layer port (M33-5), the M34 persistence + auth port (M34-6), the M35 integrations port (M35-8), the M36 agents port (M36-7), the M37 services+engine port (M37-8), and the M38 HTTP-routes port (M38-5), which land the whole bloom.domain, bloom.persistence, bloom.integrations, bloom.agents/bloom.skills, and bloom.engine layers plus bloom.auth.oidc, the shared infra utils, the orchestrator-independent bloom.services, the deferred openclaw_harness + migration bundle, and the orchestrator-independent slice of bloom.api.routes (dashboard + admin auth, admin aggregator reads, /metrics, and the account-scoped credentials/telegram-link routers) within the measured envelope, and finally the M39 orchestrator/workflow/langgraph core (the workflow/ langgraph runtime + OpenClaw adapters, the services.orchestrator decision/lifecycle/review cores, the M37-deferred orchestrator-coupled services, and the M38-deferred orchestrator-coupled routes) - the last mandatory gate, cleared UNDER by ~1.5-2x with no new serializer (the control-flow spike hit 37/37 reusing pyjson.ts), so the freeze-core fallback is retired; record the cross-provider, agent, services+engine, route, and control-flow parity findings (webhook signature bytes, VCS abstraction fidelity, cache-stable prompt composition, pinned model_json_schema() documents, seam-isolated subprocess/git execution, Starlette cookie byte-parity, the pure-core/async-wrapper split and Python evaluation-semantics fidelity), and set the roadmap - with every shape measured and every layer ported, the M40 cutover then landed (flip server.enabled, point the gateway routes at apps/server, prove parity, re-derive the pooler budget, and finally decommission apps/api - completed in #808; the Python oracle stays recoverable at git d69f789), preceded by the small M39-8 deferral slices it inherited.
• Knowledge skills - the authoring + governance contract for vendored SKILL.md knowledge: front-matter fields, and the proprietary vs third-party provenance rules (M22); third-party imports go through the pinned-ref importer and the vetting checklist.
• Cross-platform project migration - export a project's SDLC state to a neutral, versioned bundle and re-materialize it on another VCS platform (M23), with an explicit report of anything not 1:1 transferable.
• Persistence - durable run-state storage on Supabase Postgres.
• Observability - structured logging, run/thread correlation ids, and the log event-name taxonomy.
• CI/CD pipeline (DevOps) - the whole pipeline: security -> test -> build -> deploy -> e2e, the two e2e lanes (pre-merge ephemeral + post-deploy), gating, and merge rules.
• Deployment - GitHub Actions CD to an exe.dev VM (Docker, stable HTTPS via the exe.dev edge, restart-on-failure).
• Preview environments (per-PR) - the M16 per-PR preview stack, starting with the isolated Supabase branch database each PR to main gets.
• Workflow specs overview - the abstraction, core concepts, and how the spec maps onto LangGraph / Temporal / XState.
• Workflow format (JSON Schema) - the contract every workflow definition must satisfy.
• Bloom SDLC workflow - the concrete end-to-end process instance.

Running locally

See Running locally under Getting started: install once at the repo root, run the API offline with the fake LLM provider, and wire real credentials when you need them.

Documentation map

Area	Where	Status
Product requirements	PRD.md	Drafted
User guide (getting started + core workflows)	docs/getting-started/, docs/core-workflows.md, docs/admin-console.md	Written (M45-3)
Architecture overview	docs/architecture.md	Implemented
Workflow engine + spec	apps/server/workflows/, apps/server/src/workflow/	Implemented
Backend API (Express)	apps/server/src/	Implemented
Agents (Product Owner, Reviewer)	apps/server/src/agents/	Implemented
Integrations (LLM, Telegram, GitHub, GitLab)	apps/server/src/integrations/, apps/server/src/llm/	Implemented
Engineering engine (build the software)	docs/engineering-engine.md, apps/server/src/engine/	Implemented (M6; disabled by default, opt-in simulator/claude_code)
GitHub repo wiring (App auth, bloom-hosted + client-owned)	docs/github-app.md	Implemented (needs App registration)
Repository adoption (brownfield onboarding)	docs/repo-adoption.md	Implemented (M44)
GitLab wiring (webhook intake + access tokens)	docs/gitlab.md	Implemented (M23; needs per-project webhook + stored token)
Knowledge skills (authoring + governance)	docs/skills.md, docs/skill-vetting.md, apps/server/src/skills/	Implemented (M11 registry; M22 provenance + third-party import)
Persistence (state store)	apps/server/src/persistence/, docs/persistence.md	Implemented (in-memory + Supabase)
Cross-platform migration (export/import)	docs/migration.md, apps/server/src/migration/	Implemented (M23)
Observability (structured logs, correlation ids)	docs/observability.md, apps/server/src/logger.ts	Implemented (M21)
CI/CD pipeline (DevOps)	docs/ci.md, .github/workflows/	Implemented
Deployment & operations	docs/deployment.md, apps/server/Dockerfile, deploy/helm/bloom/, .github/workflows/	Implemented
Milestones	Delivered docs under docs/milestones/: M3, M4, M5, M7, M9, M10, M11. Planned as GitHub milestones (the reviewable plan is the milestone + its issues): M12 - End-to-End Testing, M13 - Sharper Planning, M14 - Decision Graph (Capture), M15 - Immutable Deploys & Rollback, M6 - Production-Grade Engineering Engine, M18 - Deployment-Aware Planning, M19 - Client Credential Store, M20 - Dashboard UX Redesign: Project Workspace & Web Chat, M24 - Cloud Infra: Kubernetes-Native Dev & Staging Readiness, M25 - Staging Provisioning & Go-Live (deferred, paid), M26 - In-app project creation (web), M27 - Admin Dashboard (design of record: admin-dashboard-milestone-plan-fable.md; threat-model verification: admin-threat-model.md), M45 - Documentation app (the apps/docs Docusaurus site renders this docs/ tree in place; docs/ stays canonical).	M3-M11, M18, M19 delivered; M12-M15, M6 planned as GitHub milestones; M20 in delivery

Conventions

• New documentation lives under docs/ (or alongside the code it describes, linked from the map above). Add a row to the map when you introduce a new area.
• Keep this page as the single entry point - it should always link to everything a new reader needs, one hop away.