# writer/writer-framework architecture

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

- Interactive diagram: https://gitdiagram.com/writer/writer-framework
- Repository: https://github.com/writer/writer-framework

## Overview

##### Project type and purpose
- This is a full-stack, open-source framework (“Writer Framework”) for building AI apps with a visual UI editor (Vue-based) and a Python backend.
- The README describes a state-driven reactive model: JSON-defined UIs, WebSocket syncing, Python event handlers, and optional AI/LLM modules.

##### File structure
Top level:
- `.github/workflows` – CI for tests, UI tests, publishing
- `alfred/` – Python scripts (build, install, publish, run, CI, GitHub integration) – this is the CLI engine behind the `writer` command
- `apps/` – sample apps (`default`, `hello`) with `.wf` JSON UI snapshots and Python entrypoints (`main.py`)
- `src/ui/` – the visual editor and UI runtime (Vue 3 + Vite + Storybook + Playwright tests)
- `src/writer/` – core Python library (CLI entry, state manager, event loop, blocks, AI integration, evaluator, server)
- `tests/backend/` – pytest suite for all Python modules and blocks
- `tests/e2e/` – Playwright end-to-end UI tests

##### README for additional insights
- Describes backend/front-end separation, state management, asynchronous event handling, WebSocket streaming, and developer UX (live-reload, versioned JSON UI).
- Mentions AI module and deployment options (via writer/deploy).

a. Main components:
1. CLI Layer (“writer” / `alfred/` scripts)
2. Frontend Visual Editor & Runtime (`src/ui/`)
3. Backend Server & State Manager (`src/writer/serve.py`, `core.py`, `evaluator.py`)
4. UI JSON Store (`apps/<app>/.wf/*.jsonl`)
5. Event Handlers & Business Logic (`src/writer/blocks/`, user-defined in `apps/<app>/main.py`)
6. External AI/LLM Services (`src/writer/ai/`)
7. Persistence & Deployment (`deploy.py`, optional cloud or on-prem)

b. Relationships & interactions:
- The user runs `writer create|edit|run` (CLI) → spawns the Python server and/or Vite dev server.
- Browser Alice navigates to the Builder UI (served by Vite) → connects via WebSocket to the Python server.
- Frontend fetches UI JSON (`.wf/metadata.json`) from backend or local FS.
- User manipulates the UI; editor writes updated JSON to disk and sends events over WebSocket.
- Backend’s state manager receives events, dispatches to Python handlers (`blocks/`), updates in-memory state.
- Backend streams state diffs back via WebSocket → Frontend updates the DOM.
- For AI calls, handlers invoke `writer/ai/*` which call external LLM endpoints.
- Tests: pytest exercises Python modules; Playwright drives the UI in headless browsers.

c. Architectural patterns & design principles:
- Separation of concerns: CLI vs. frontend vs. backend core vs. user logic
- Reactive state-driven MVC: state model (Python dict) → view (JSON+Vue) → controller (event handlers)
- Modular plugin architecture for “blocks” (each block is a self-contained action)
- Asynchronous event processing in thread pools
- Versioned UI definitions stored alongside code for reproducibility

d. Key technologies & frameworks:
- Python 3.8+ (Poetry, pip)
- FastAPI / Starlette or custom ASGI server for HTTP & WebSocket
- Vue 3 + Vite + Storybook for UI builder
- Playwright for e2e tests
- pytest / mypy for Python tests & type checking
- GitHub Actions for CI / CD

##### Detail—capture
- CLI commands & dependencies
- UI build/test pipeline (Storybook, Playwright)
- Python modules: core, evaluator, blocks, deploy
- Sample apps directory structure
- WebSocket vs. HTTP flows
- Asynchronous thread-pool processing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        run["run.py"]:::cli
        build["build.py"]:::cli
        install["install.py"]:::cli
        publish["publish.py"]:::cli
        ci["ci.py"]:::cli
        github["github.py"]:::cli
    end

    %% Frontend Visual Editor & Runtime
    subgraph "Frontend Visual Editor & Runtime"
        main_ts["main.ts"]:::frontend
        vite_config["vite.config.ts"]:::frontend
        builder["Builder Components"]:::frontend
        renderer["Runtime Renderer"]:::frontend
    end

    browser["Browser (User)"]:::frontend

    %% Backend Server & State Manager
    subgraph "Backend Server & State Manager"
        serve["serve.py"]:::backend
        core["core.py"]:::backend
        evaluator["evaluator.py"]:::backend
        sync["sync.py"]:::backend
        ui_manager["ui_manager.py"]:::backend
    end

    %% Event Handlers & Blocks
    subgraph "Event Handlers & Blocks"
        blocks_dir["Blocks Directory"]:::backend
        user_default["apps/default/main.py"]:::backend
        user_hello["apps/hello/main.py"]:::backend
    end

    %% AI Module
    subgraph "AI Module"
        ai["AI Module"]:::external
    end

    %% Persistence & Deployment
    subgraph "Persistence & Deployment"
        deploy["deploy.py"]:::backend
        templates["templates"]:::backend
        static_assets["App Static Assets"]:::persistence
    end

    %% UI JSON Store
    subgraph "UI JSON Store"
        meta_default["default metadata.json"]:::persistence
        meta_hello["hello metadata.json"]:::persistence
        jsonl_default["default .jsonl files"]:::persistence
        jsonl_hello["hello .jsonl files"]:::persistence
    end

    %% External Services
    subgraph "External Services"
        llm["LLM Endpoints"]:::external
    end

    %% Connections
    run -.->|spawns| main_ts
    run -.->|spawns| serve
    browser -->|Loads UI| builder
    builder -->|Fetch JSON UI| meta_default
    builder -->|Fetch JSON UI| meta_hello
    builder -->|WebSocket Connection| serve
    serve -->|State Diffs via WS| builder
    serve -->|Invoke Blocks| blocks_dir
    blocks_dir -->|User Logic| user_default
    blocks_dir -->|User Logic| user_hello
    serve -->|Call AI Module| ai
    ai -->|External API Calls| llm
    serve -->|Deploy Artifacts| templates
    serve -->|Serve Static Assets| static_assets

    %% Click Events
    click run "https://github.com/writer/writer-framework/blob/dev/alfred/run.py"
    click build "https://github.com/writer/writer-framework/blob/dev/alfred/build.py"
    click install "https://github.com/writer/writer-framework/blob/dev/alfred/install.py"
    click publish "https://github.com/writer/writer-framework/blob/dev/alfred/publish.py"
    click ci "https://github.com/writer/writer-framework/blob/dev/alfred/ci.py"
    click github "https://github.com/writer/writer-framework/blob/dev/alfred/github.py"
    click main_ts "https://github.com/writer/writer-framework/blob/dev/src/ui/src/main.ts"
    click vite_config "https://github.com/writer/writer-framework/blob/dev/src/ui/vite.config.ts"
    click builder "https://github.com/writer/writer-framework/tree/dev/src/ui/src/builder/"
    click renderer "https://github.com/writer/writer-framework/tree/dev/src/ui/src/renderer/"
    click serve "https://github.com/writer/writer-framework/blob/dev/src/writer/serve.py"
    click core "https://github.com/writer/writer-framework/blob/dev/src/writer/core.py"
    click evaluator "https://github.com/writer/writer-framework/blob/dev/src/writer/evaluator.py"
    click sync "https://github.com/writer/writer-framework/blob/dev/src/writer/sync.py"
    click ui_manager "https://github.com/writer/writer-framework/blob/dev/src/writer/ui_manager.py"
    click blocks_dir "https://github.com/writer/writer-framework/tree/dev/src/writer/blocks/"
    click user_default "https://github.com/writer/writer-framework/blob/dev/apps/default/main.py"
    click user_hello "https://github.com/writer/writer-framework/blob/dev/apps/hello/main.py"
    click ai "https://github.com/writer/writer-framework/tree/dev/src/writer/ai/"
    click deploy "https://github.com/writer/writer-framework/blob/dev/src/writer/deploy.py"
    click templates "https://github.com/writer/writer-framework/tree/dev/src/writer/templates/"
    click static_assets "https://github.com/writer/writer-framework/tree/dev/apps/<app>/static/"
    click meta_default "https://github.com/writer/writer-framework/blob/dev/apps/default/.wf/metadata.json"
    click meta_hello "https://github.com/writer/writer-framework/blob/dev/apps/hello/.wf/metadata.json"
    click jsonl_default "https://github.com/writer/writer-framework/tree/dev/apps/default/.wf/"
    click jsonl_hello "https://github.com/writer/writer-framework/tree/dev/apps/hello/.wf/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#028A0F;
    classDef persistence fill:#FFE8B0,stroke:#D97706;
    classDef external fill:#F0D0FF,stroke:#8E2AF2;
    classDef cli fill:#EDEDED,stroke:#999;
```
