Architecture

Architecture

High-Level Shape

Open-Write is a three-layer local application. Nothing leaves the user's machine except AI requests.

[ Tauri window ]
       |
[ React + TypeScript UI ]      panels, editor, chat, overlays (port 1420 dev)
       |  HTTP on 127.0.0.1:8000
[ FastAPI backend (Python) ]   file I/O, parsing, AI routing, pipeline, gate
       |
[ Markdown files + SQLite ]    dual storage (Markdown = truth, SQLite = cache)

The frontend never reads files directly. Every read and write goes through the backend.

Layers

Desktop Shell — Tauri v2

Tauri provides the native window, OS integration (file dialogs, opener), and packaging into a single Windows .msi. The shell spawns the Python backend as a sidecar process at app launch and tears it down at exit.

Frontend — React + TypeScript (Vite)

Renders the entire UI. Communicates with the backend over fetch to http://127.0.0.1:8000. Uses:

• CodeMirror 6 for the Markdown editor
• Zustand for shared state
• shadcn/ui + Tailwind CSS v4 for components
• Light + dark themes (app-wide, persisted)

Backend — Python + FastAPI (managed by uv)

A local-only HTTP server bound to 127.0.0.1:8000. Handles:

• File I/O and Markdown parsing
• Profile system (structured trait blocks, importance levels)
• AI prompt construction and routing (22 providers)
• Em-dash sanitizer (advisory, not blocking)
• Pipeline orchestrator (resumable phase state machine)
• Deterministic completion gate (word count, manifest, verify, lints, finalize)
• Harness layer (planner, router, runner, verifier, reporter)

In packaged builds, the backend is frozen into a single .exe via PyInstaller and bundled as a Tauri sidecar.

Dual Storage Model

Layer	Purpose	Format
Markdown files	Permanent source of truth	.md files in the project folder
SQLite	Fast local cache	<project>/.open-write/app.db

Markdown is the filing cabinet; SQLite is the index card on the desk. The cache can be rebuilt from Markdown if it is corrupted or deleted.

Project Folder Layout

MyNovel/
  project.json                     project settings
  manuscript/                      chapter .md files
  notes/                           outline, style guide, themes
  profiles/                        character, relationship, location, lore
  summaries/                       chapter and scene summaries
  exports/                         combined manuscript + snapshots
  .open-write/                     local cache (SQLite, settings)

For pipeline projects:

  bible/                           concept, outline, format rules
  state/                           pipeline_run.json, completion_manifest.json
  manuscript/chapters/             per-chapter drafts
  critic_outputs/                  critic review artifacts
  coverage_reports/                editorial coverage

Key Directories in the Repo

app/                     Tauri v2 + React 19 + TypeScript (Vite) frontend
  src/                   React source (screens/, components/, hooks/, types/, utils/)
  src-tauri/             Rust shell + tauri.conf.json + sidecar binaries
backend/                 Python FastAPI backend (managed by uv)
  app/
    main.py              FastAPI entry + CORS + router registration
    routers/             API routes (projects, documents, profiles, ai, pipeline, settings)
    ai/                  LLM routing, model catalog (26 curated models), prompts, sanitizer
    pipeline/            Open-Write gate toolchain (word_count, manifest, verify, lints, finalize, critics, orchestrator, outputs, profile_context)
    harness/             Architect protocols (planner, router, runner, verifier, reporter)
    tools/               CLI debugging tool (ow_cli.py)
  tests/                 pytest test suite
openwrite/               READ-ONLY reference of the Open-Write methodology
docs/                    Product scope, architecture, features, roadmap, releasing
scripts/                 Build and release scripts (build.ps1, build-backend.ps1, release.ps1)

Canonical vs Reference Rule

• backend/app/pipeline/ is the canonical runtime copy of the gate logic. Edit it.
• openwrite/ is a frozen read-only reference of the upstream methodology. Read its prompts/protocols from it; do not edit gate logic there.