overview architecture

Architecture

Active contributors: Andy Taylor, Sagar Narayan

Purpose

The repository is a content-only documentation site. It has no application server, no compiled artifacts, and no runtime code beyond CI helpers and a small shell script. The "architecture" therefore describes how content is organized, how the navigation is wired, how localization works, and what automation supports the editorial workflow.

High-level layout

graph TD
    subgraph Repo["Factory-AI/factory"]
        README[README.md]
        Docs[docs/]
        GH[.github/]
    end

    subgraph DocsTree["docs/"]
        DocsJSON[docs.json — navigation, theme, redirects]
        EN[English content trees]
        JP[jp/ — Japanese mirror]
        Images[images/]
        Style[style.css]
        Convert[convert_md_to_mdx.sh]
    end

    subgraph EnglishTrees["English content"]
        Welcome[welcome/]
        CLI[cli/]
        Web[web/]
        Integrations[integrations/]
        Enterprise[enterprise/]
        Guides[guides/]
        Reference[reference/]
        Changelog[changelog/]
        Benchmarks[benchmarks/]
        Snippets[snippets/]
    end

    subgraph CI[".github/workflows"]
        Sync[sync-jp-docs.yml]
        BulkTL[translate-jp-docs-bulk.yml]
        Disc[changelog-to-discord.yml]
        Lin[changelog-to-linear.yml]
        Slack[pr-merge-slack.yml]
        Droid[droid.yml + droid-review.yml]
    end

    Repo --> Docs
    Repo --> GH
    Docs --> DocsJSON
    Docs --> EN
    Docs --> JP
    Docs --> Images
    Docs --> Style
    Docs --> Convert
    EN --> Welcome
    EN --> CLI
    EN --> Web
    EN --> Integrations
    EN --> Enterprise
    EN --> Guides
    EN --> Reference
    EN --> Changelog
    EN --> Benchmarks
    EN --> Snippets

    DocsJSON -->|drives sidebar| Mintlify[Mintlify renderer]
    EN -->|MDX content| Mintlify
    JP -->|MDX content| Mintlify
    Mintlify -->|publishes| Site[docs.factory.ai]

    GH --> CI
    CI -->|automates JP translation| JP
    CI -->|posts release notes| Disc
    CI -->|posts release notes| Lin
    CI -->|notifies merges| Slack

Loading

Content tree

The English content lives directly under docs/. The most important top-level groups, mirroring the navigation in docs/docs.json:

Path	Topic
docs/welcome/	Landing page
docs/cli/	CLI (droid) docs — getting started, configuration, features, BYOK, droid-exec, account/security
docs/web/	Desktop and web app docs — agent readiness, getting started, machine connection, cloud templates
docs/integrations/	GitHub App, JetBrains, Zed, IDE integrations, Linear, Slack
docs/enterprise/	Identity, SSO/SCIM, network/deployment, privacy, telemetry, compliance
docs/guides/	Power-user guides, building plugins, droid-exec recipes, skill recipes, hook recipes
docs/reference/	CLI reference, hooks reference, analytics API, readiness reports API
docs/changelog/	Release notes for the CLI
docs/benchmarks/	Benchmark pages (terminal-bench, nextjs-eval, etc.)
docs/snippets/	Shared snippets included in multiple pages
docs/jp/	Japanese mirror of all the above
docs/images/	Screenshots, GIFs, and diagrams used by MDX pages
docs/logo/	Light and dark Factory logos

Navigation

docs/docs.json is the single source of truth for navigation. It declares two languages (en, jp), and each language declares a list of tabs (Docs, Guides, Changelog, Benchmarks, API Reference). Each tab contains nested groups and pages. Pages are referenced by path without the .mdx extension (e.g., cli/getting-started/overview). The file also declares site theme colors, fonts, the favicon, the topbar links, the footer socials, the contextual options (copy/view/chatgpt/claude buttons on every page), the SEO canonical, and a long list of HTTP redirects for renamed routes. See docs/docs.json (~1150 lines).

Localization

Japanese translations are kept in parallel under docs/jp/, file-for-file. The translation pipeline is automated:

• .github/workflows/sync-jp-docs.yml watches changes to English MDX files and uses droid (Factory's own agent) to keep the Japanese mirror in sync.
• .github/workflows/translate-jp-docs-bulk.yml runs bulk translations (e.g., when many pages change at once or a new doc area is added).

Both workflows are themselves examples of droid-exec usage in CI.

Notification & release workflows

Workflow	Purpose
.github/workflows/changelog-to-discord.yml	Posts new changelog entries to the community Discord
.github/workflows/changelog-to-linear.yml	Mirrors changelog entries into Linear for product tracking
.github/workflows/pr-merge-slack.yml	Notifies a Slack channel when PRs merge
.github/workflows/droid.yml	Generic droid runner that PRs can opt into
.github/workflows/droid-review.yml	Runs Factory's own code-review droid on PRs

Helper script

docs/convert_md_to_mdx.sh is a small Bash helper that renames .md files to .mdx recursively. It exists because Mintlify expects MDX, but content occasionally arrives as plain Markdown.

Key source files

File	Purpose
docs/docs.json	Navigation, theme, redirects, language tabs, SEO
docs/style.css	Custom CSS overrides for the Mintlify theme
docs/snippets/	Shared MDX snippets re-used across pages
docs/convert_md_to_mdx.sh	Renames .md → .mdx
.github/workflows/sync-jp-docs.yml	Keeps docs/jp/ in sync with English changes
.github/workflows/droid-review.yml	Code review on PRs via Factory droid
README.md	Project pitch, install snippets, ecosystem links

Entry points for modification

• To add or move a page, edit the corresponding MDX file and update its entry in docs/docs.json. Adding a new page without a docs.json entry leaves it unreachable from the sidebar.
• To rename a page, add a redirects entry in docs/docs.json from the old path to the new one so existing inbound links continue to work.
• To add a new top-level section, add a new group (or tab) in docs/docs.json and create the matching directory under docs/ (and docs/jp/).
• To change the visual style, edit docs/style.css or the colors, styling, and logo blocks in docs/docs.json.