Architecture

The model

NovaBuildBot is a hierarchical multi-agent system. A top-level Personal Bot receives every message from the business owner and decides what to do — usually by delegating to a specialist sub-agent.

Components

BOT 0 — Personal Bot (supervisor)

The owner's single chat surface. It does not edit files, post to Instagram, run audits, or read analytics directly. Its tools are:

• delegate_to_website_agent(task, mode)
• delegate_to_social_media_agent(task, mode)
• narrate_to_owner(text) — sends a status line before/during work
• update_memory(key, value) — the supervisor is the only writer of business memory (specialists return memory hints in their summaries; the supervisor serializes the writes to avoid races)

Two delegation modes:

• sync — the supervisor blocks for up to 25 s. If the specialist finishes inside that window, the supervisor relays the summary in its reply. If not, the run continues in the background and the publisher DMs the owner when it lands.
• async — fire-and-forget. The supervisor returns "started — run #N" immediately. Used for blog generation, multi-file edits, anything ≥30 s.

BOT 1 — Website Agent

Edits content and templates, writes blog posts, runs SEO audits, pulls site analytics, commits and deploys. Tools: WEBSITE_TOOLS (read/write/str_replace/list/delete files, commit_and_push, seo_audit, get_site_analytics) plus RESEARCH_TOOLS (web_search, fetch_webpage, generate_content).

Sub-capabilities surfaced in the diagram:

• SEO — built. Audit + apply pattern; integrates with Google Search Console via Nova-managed properties.
• AEO (Answer Engine Optimization) — roadmap. Visibility in ChatGPT, Perplexity, Google AI Overviews. Distinct from classic SEO. Not built today.
• Blog — built. Generates SEO-optimized posts and publishes them as .md files in the customer's repo.

BOT 2 — Social Media Agent

Marketing strategy, content calendars, captions with hashtags, direct posting. Tools: SOCIAL_TOOLS (post_to_instagram, post_to_facebook, check_social_connections, get_social_post_history) plus RESEARCH_TOOLS.

• Instagram — built. Single image and carousel posts via the Graph API.
• Facebook Page — built. Text, link, and photo posts via the Graph API.

BOT 3 — Customer Lead Mgmt (planned)

Today the bot only talks to the business owner. The hand-drawn original marks an end-customer-facing branch with an X — explicitly out of scope for the current phase. When it lands, it will handle inbound WhatsApp messages from the business's customers, qualify leads, and route them.

Foundations

Three pieces of infrastructure that every specialist relies on:

• Tool groups (tools.py) — WEBSITE_TOOLS, SOCIAL_TOOLS, RESEARCH_TOOLS, MEMORY_TOOLS. Each specialist sees only its subset; the supervisor sees MEMORY_TOOLS plus its three delegation tools.
• Business memory (business_memories table) — a per-business key/value store the supervisor maintains and every agent reads as ambient context.
• Approval framework (agent_pending_approvals table + Telegram buttons) — when a specialist proposes a change in review mode, the owner gets an inline approve/reject DM. Nothing ships without consent in review mode.
• Scheduler (agents/scheduler.py) — a background thread that fires review-mode runs on a weekly cadence and dispatches the publisher to deliver completed async runs to the owner via DM.

Two run modes

The same specialist code serves both entry points:

• On-demand — the owner sends a message → supervisor delegates → specialist runs once → summary returns to the supervisor (sync) or the publisher (async).
• Review — the scheduler fires the specialist with mode="review" on its cadence → the specialist looks at current state with its tools and proposes 1–3 high-impact actions, surfaced to the owner via the approval framework.

Feature flag

multi_agent_enabled lives in business_memories (per-business override) with NOVABOT_MULTIAGENT_DEFAULT env (global default). When OFF, the chat path falls back to a legacy monolithic Claude loop with all 16 tools visible at once. Admin command: /multiagent on|off|status <business_id>.

Diagram updated 2026-05-25. Source of truth: this page. If the architecture changes, edit _includes/architecture-diagram.njk and bump this note.