How writer/writer-framework works
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