# samhatoum/auto-engineer architecture

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

- Interactive diagram: https://gitdiagram.com/samhatoum/auto-engineer
- Repository: https://github.com/samhatoum/auto-engineer

## Overview

##### Project type and purpose
- This is a monorepo toolchain (“Auto Engineer”) for automating the full SDLC via a CLI and modular plugins.
- Purpose: model application behavior as “flows,” export schemas, scaffold server/client code, implement via AI agents, and validate with checks.

##### File structure
- Top-level:
- package.json, pnpm-workspace.yaml, turbo.json → pnpm+Turborepo monorepo
- packages/ → core modules (CLI, flow DSL, code generators, implementers, checks, utilities)
- examples/ → ready-made example apps (e.g. shopping-app)
- integrations/ → sample integrations (AI, cart API, product API)
- .github/, docs/, scripts/ → CI/CD, documentation, helper scripts
- Patterns:
- Plugin-based CLI (packages/cli)
- Command/Event bus (packages/message-bus)
- File abstraction & sync (packages/file-store, packages/file-syncer)
- Code generators & implementers (flow, server-generator-apollo-emmett, frontend-generator-react-graphql, server-implementer, frontend-implementer)
- Validation suites (server-checks, frontend-checks)
- AI gateway (packages/ai-gateway) for unified provider API

##### README for additional insights
- Describes a pipeline: Flow Modeling → IA Generation → Scaffolding → AI-Coding/Test Loop → Quality Checks
- Architecture section calls out: Plugin-based, Command pattern, Event-driven, Type-safe

##### Main components & their interactions
a. Components
- CLI & Plugin Loader (packages/cli)
- Flow DSL (packages/flow)
- Code Generators:
– Server generator (packages/server-generator-apollo-emmett)
– Frontend generator (packages/frontend-generator-react-graphql)
- Implementers:
– Server implementer (packages/server-implementer)
– Frontend implementer (packages/frontend-implementer)
- Information Architect (packages/information-architect)
- Design System Importer (packages/design-system-importer)
- Message Bus (packages/message-bus)
- AI Gateway (packages/ai-gateway) & External AI Providers
- File Store (packages/file-store) & File Syncer (packages/file-syncer)
- Validation Suites (packages/server-checks, packages/frontend-checks)
- Example / Workspace (examples/shopping-app, flows/)

b. Relationships and data flow
1. User invokes “auto” CLI → Plugin Loader resolves command → dispatch to correct plugin
2. Plugin defines a command handler via Message Bus → CLI emits command → Message Bus routes to handler
3. Handler may:
– Read/write files via File Store → persisted to disk
– Sync changes via File Syncer (watch & hot-reload)
– Call AI agents through AI Gateway → external AI provider (Anthropic, OpenAI, etc.)
– Generate or populate code scaffolds (GraphQL schema, resolvers, React components)
4. After code is generated/implemented:
– Validation plugins run type checks, test suites, linting
5. Built-in Message Bus Dashboard (port 5555) visualizes commands/events via WebSocket

c. Architectural patterns & principles
- Plugin-Based Architecture: loose coupling of features behind CLI
- Command Pattern: every action is a named command with typed parameters
- Event-Driven: Message Bus routes commands and events between modules
- Type-Safe: Full TypeScript and strict typing across packages
- Modular Monorepo: pnpm workspaces + Turborepo for efficient builds

d. Key technologies
- TypeScript, Node.js, pnpm, Turborepo
- Vitest for testing, ESLint/Prettier for linting/formatting
- GraphQL (Apollo) for server scaffold
- React & Vite for client scaffold
- WebSocket for real-time dashboard

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & CLI
    User["User"]:::external -->|"runs auto"| CLI["CLI & Plugin Loader"]:::cli
    click CLI "https://github.com/samhatoum/auto-engineer/tree/main/packages/cli"

    %% Core Infra
    subgraph "Core Infrastructure"
        direction TB
        MB["Message Bus"]:::core
        click MB "https://github.com/samhatoum/auto-engineer/tree/main/packages/message-bus"
        AI["AI Gateway"]:::core
        click AI "https://github.com/samhatoum/auto-engineer/tree/main/packages/ai-gateway"
        FS["File Store"]:::core
        click FS "https://github.com/samhatoum/auto-engineer/tree/main/packages/file-store"
        FSync["File Syncer"]:::core
        click FSync "https://github.com/samhatoum/auto-engineer/tree/main/packages/file-syncer"
    end

    %% Connections in Core
    FS <--> FSync
    AI -->|"calls providers"| ExtAI["External AI Providers"]:::external

    %% Plugins
    subgraph "Plugin Modules"
        direction TB
        Flow["Flow DSL"]:::plugin
        click Flow "https://github.com/samhatoum/auto-engineer/tree/main/packages/flow"
        IA["Information Architect"]:::plugin
        click IA "https://github.com/samhatoum/auto-engineer/tree/main/packages/information-architect"
        DS["Design System Importer"]:::plugin
        click DS "https://github.com/samhatoum/auto-engineer/tree/main/packages/design-system-importer"
        SG["Server Code Generator"]:::plugin
        click SG "https://github.com/samhatoum/auto-engineer/tree/main/packages/server-generator-apollo-emmett"
        FG["Frontend Code Generator"]:::plugin
        click FG "https://github.com/samhatoum/auto-engineer/tree/main/packages/frontend-generator-react-graphql"
        SI["Server Implementer"]:::plugin
        click SI "https://github.com/samhatoum/auto-engineer/tree/main/packages/server-implementer"
        FI["Frontend Implementer"]:::plugin
        click FI "https://github.com/samhatoum/auto-engineer/tree/main/packages/frontend-implementer"
        SCheck["Server Validation Suite"]:::plugin
        click SCheck "https://github.com/samhatoum/auto-engineer/tree/main/packages/server-checks"
        FCheck["Frontend Validation Suite"]:::plugin
        click FCheck "https://github.com/samhatoum/auto-engineer/tree/main/packages/frontend-checks"
    end

    %% Core to Plugins routing
    CLI --> MB
    MB --> Flow
    MB --> IA
    MB --> DS
    MB --> SG
    MB --> FG
    MB --> SI
    MB --> FI
    MB --> SCheck
    MB --> FCheck

    %% Plugins use Core services
    Flow --> FS
    IA -->|"AI requests"| AI
    IA --> FS
    DS --> FS
    SG --> FS
    SG -->|"AI requests"| AI
    FG --> FS
    FG -->|"AI requests"| AI
    SI --> FS
    SI -->|"AI requests"| AI
    FI --> FS
    FI -->|"AI requests"| AI
    SCheck --> FS
    FCheck --> FS

    %% Pipeline sequence
    Flow --> IA --> SG --> SI --> SCheck
    IA --> FG --> FI --> FCheck

    %% Example workspace
    subgraph "Example Workspace" 
        direction TB
        Workspace["Shopping App Workspace"]:::example
        click Workspace "https://github.com/samhatoum/auto-engineer/tree/main/examples/shopping-app"
        FlowsDir["Flows Directory"]:::example
        click FlowsDir "https://github.com/samhatoum/auto-engineer/tree/main/examples/shopping-app/flows"
    end

    %% Code output and validation
    SG --> Workspace
    FG --> Workspace
    SI --> Workspace
    FI --> Workspace
    Workspace --> SCheck
    Workspace --> FCheck
    Workspace --> FlowsDir

    %% Styles
    classDef cli fill:#E3F2FD,stroke:#2196F3;
    classDef plugin fill:#FFF3E0,stroke:#FB8C00;
    classDef core fill:#E8F5E9,stroke:#43A047;
    classDef external fill:#FFEBEE,stroke:#E53935;
    classDef example fill:#ECEFF1,stroke:#546E7A;
```
