# factory-ai/factory architecture

> Architecture diagram of the GitHub repository factory-ai/factory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/factory-ai/factory
- Repository: https://github.com/factory-ai/factory

## Overview

##### Project type and purpose
- This repo is primarily a **documentation site** (MDX/Markdown content + examples) for the “Factory” agent-native development platform.
- It contains:
- Docs in `/docs` (MDX files, images, CSS)
- A small examples folder (`/examples`)
- Build scripts (e.g. `convert_md_to_mdx.sh`)
- CI workflows (`.github/workflows/…`) for issue-label Slack notifications and site builds

##### File structure for architectural clues
- **Content layer**: `/docs`, `/community-builds.md`, `/examples`
- **Build tooling**: `convert_md_to_mdx.sh`, `docs/docs.json`, style assets
- **CI/CD**: GitHub Actions workflows under `.github/workflows`
- **Output target**: A static site (likely powered by a static-site generator such as Docusaurus, Next.js, etc.) and deployed to a CDN or GitHub Pages
- **Integrations**: Slack (issue-label notifications), GitHub Discussions, external links to CLI, Web, VS Code marketplace

##### README for refinements
- Confirms core deliverable = **static documentation site**
- Mentions community builds (a dynamic list fed from `community-builds.md`)
- Points to external services: CLI Quickstart, VS Code Extension, Community Discussions

##### Architectural patterns & design principles
- **Content-as-Code**: All docs live in Git, versioned, PR-driven
- **Static-Site Generation (SSG)**: Pre-render all pages for fast, cacheable delivery
- **Modular Documentation**: Directory structure mirrors site navigation, MDX for interleaving React (if used)
- **CI-Driven Deployments**: Builds and deployments triggered on `main` or tagged commits
- **Decoupled Integrations**: Slack notifications via a separate workflow, community builds updated independently

##### Sample component list
1. Developer Workstation (authoring MDX)
2. GitHub Repo (docs & examples)
3. Build Script (`convert_md_to_mdx.sh`, docs.json)
4. Static-Site Generator (Docusaurus/Next)
5. GitHub Actions Runner
6. CDN / Hosting (Vercel/Netlify/GitHub Pages)
7. Slack Webhook (issue-label notifications)
8. GitHub Discussions & Issues portal

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Layer
    subgraph "Content Layer"
        direction TB
        Repo["GitHub Repo"]:::repo
        Docs["Docs MDX Content"]:::repo
        CommunityBuilds["community-builds.md"]:::repo
        Examples["Examples"]:::repo
        README["README.md"]:::repo
    end

    %% Build & Transformation
    subgraph "Build & Transformation"
        direction TB
        Script["convert_md_to_mdx.sh"]:::build
        Metadata["docs.json"]:::data
        Style["style.css"]:::build
        SSG["Static-Site Generator"]:::build
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        Runner["GitHub Actions Runner"]:::ci
        IssueLabelWF["Issue-Label → Slack Workflow"]:::ci
        DocsBuildWF["Docs Build & Deploy Workflow"]:::ci
    end

    %% Hosting
    subgraph Hosting
        direction TB
        CDN["CDN / Hosting"]:::external
    end

    %% Integrations
    subgraph "External Integrations"
        direction TB
        Slack["Slack Webhook"]:::external
        GitHubUI["GitHub Discussions & Issues"]:::external
    end

    %% Developer
    Dev["Developer Workstation"]:::external

    %% Connections
    Dev -->|pushes content| Repo
    Repo --> Docs
    Repo --> CommunityBuilds
    Repo --> Examples
    Repo --> README

    Docs --> Script
    CommunityBuilds --> Script
    Examples --> Script

    Script --> Metadata
    Script --> Style
    Script --> SSG

    Dev -->|push triggers workflows| Runner
    Runner --> DocsBuildWF
    Runner --> IssueLabelWF

    DocsBuildWF -->|build site| SSG
    DocsBuildWF -->|deploy| CDN

    IssueLabelWF -->|notify| Slack

    CDN -->|serves site| GitHubUI
    CDN -->|serves site| Dev

    GitHubUI -->|discussion| Dev

    %% Click Events
    click Docs "https://github.com/factory-ai/factory/tree/main//docs"
    click CommunityBuilds "https://github.com/factory-ai/factory/blob/main/community-builds.md"
    click Examples "https://github.com/factory-ai/factory/tree/main//examples"
    click README "https://github.com/factory-ai/factory/blob/main/README.md"
    click Script "https://github.com/factory-ai/factory/blob/main/./convert_md_to_mdx.sh"
    click Metadata "https://github.com/factory-ai/factory/blob/main//docs/docs.json"
    click Style "https://github.com/factory-ai/factory/blob/main//docs/style.css"
    click IssueLabelWF "https://github.com/factory-ai/factory/blob/main/.github/workflows/issue-label-slack.yml"
    click DocsBuildWF "https://github.com/factory-ai/factory/blob/main/examples/droid-code-review-workflow/.github/workflows/droid-code-review.yml"

    %% Styles
    classDef repo fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef build fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef data fill:#F3E5FF,stroke:#6F42C1,color:#6F42C1
    classDef ci fill:#FFF5E5,stroke:#DB6D28,color:#DB6D28
    classDef external fill:#FFE8D0,stroke:#F66A0A,color:#F66A0A
```
