Sword of Truth Publishing

A full-stack publishing platform covering the entire author lifecycle: drafting → production → packaging → distribution. Authors submit a manuscript once — it is composed, validated against every channel's requirements, and routed to KDP, IngramSpark, and Draft2Digital from a single pipeline.

Status: Phases 0–17 complete. UI/UX Modernization complete (design system, author-first nav, desktop startup UX, accessibility, analytics instrumentation, feature flags). 1750+ backend tests passing. Frontend complete. Desktop Edition shipped — see desktop/README.md. Phase 17 plan documented at docs/plans/DESKTOP_COMPLETION_PLAN.md. UI/UX plan at docs/plans/ui-ux-modernization-plan.md.

---

Editions

Sword of Truth Publishing ships in two editions, sharing one codebase.

	SaaS (web)	Desktop
Hosting	Cloud-hosted	Local install (Win/macOS/Linux)
Pricing	Subscription	One-time purchase
Connectivity	Always online	Offline-first authoring & packaging; online only for Distribution submit, Billing, cloud AI assist, Collaboration
Persistence	PostgreSQL (cloud)	SQLite (local)
Multi-device	Yes	Single machine (optional cloud sync — see desktop/CLOUD_SYNC_DESIGN.md)
Collaboration	Yes (workspaces, presence, real-time)	Single user (live collaboration is online-only)
Tech shell	Next.js 16 in browser	Tauri 2 wrapping Next.js static export + FastAPI sidecar
Build	CI / Vercel	desktop/ — npm run desktop:build:{win,mac,linux}

---

What This Is

Sword of Truth Publishing is a publishing platform for independent authors, with emphasis on non-fiction and personal development. The platform handles:

• Authoring — manuscript structure, outline, scene/chapter hierarchy, characters, world-building, snapshots & diff, annotations, track changes, footnotes, cross-references, index, ToC, Fountain screenplay mode, redline change bars
• Editorial — assignments, review cycles, spellcheck, ARC/beta reader flows, rule-based AI style analysis, AI assist, DOCX export, copy-fit
• Layout & typography — composition profiles, paged preview, font storage & licensing, ICC profiles, print marks, ornaments, conditions, compile filters, style libraries
• Packaging — EPUB3 generation (stdlib, EPUBCheck-conformant), PDF generation (6×9 trade paperback via fpdf2), build orchestration, channel validation, quality gates, issue diagnostics, EPUB accessibility compliance, galley proofs
• Production bridges — submission package, build manifest, royalty estimator, ISBN procurement, cover spec & builder, series management, proof orders
• Distribution — single-submission routing to KDP, IngramSpark, Draft2Digital via connector framework; sync, retry, withdraw; sales reporting; webhook ingest
• Author platform — landing page builder, launch checklist, reader list, newsletter integrations
• Auth & ops — JWT-based auth, OWASP middleware, GDPR compliance, incident runbooks, backup/restore (DR), launch readiness gates, rollout cohorts
• Notifications — transactional email (Resend), in-app notifications, presence, real-time collaboration over WebSocket + SSE fallback, font storage events, scene collab

---

Tech Stack

Backend

Layer	Technology	Version	Edition
API framework	FastAPI	0.104.1	Both
Server	Uvicorn (ASGI)	0.24.0	Both
Validation	Pydantic v2	2.9.2	Both
ORM	SQLAlchemy 2.0 (async)	2.0.35	Both
Database (SaaS)	PostgreSQL + psycopg	16 / 3.3.4	SaaS
Database (Desktop)	SQLite + aiosqlite	—	Desktop
Migrations	Alembic	1.13.1	Both
Job queue	Celery + Redis	5.3.4 / 7	SaaS only
In-process scheduler	APScheduler	—	Desktop only
Auth	python-jose (JWT)	3.3.0	Both
PDF	fpdf2	2.8.7	Both
Email	Resend (optional)	—	SaaS (no-op on Desktop)
Language	Python	3.13	Both

Frontend

Layer	Technology	Version
Framework	Next.js (App Router)	16.1.6
UI	React	19.2.3
Styling	Tailwind CSS	v4
Editor	TipTap	latest
Fonts	Cormorant Garamond + Inter	Google Fonts
Analytics	Vercel Analytics	2.x (SaaS only)
Language	TypeScript	—

Desktop

Layer	Technology
Shell	Tauri 2 (Rust)
Frontend	Next.js static export (output: "export")
Backend sidecar	FastAPI packaged via PyInstaller
Persistence	SQLite via aiosqlite
Credential vault	OS keychain (Windows Credential Manager / macOS Keychain / libsecret) via keyring crate
Licensing	HMAC-SHA256, offline-verified, machine-fingerprint-bound
OS integration	File associations (.sotp, .msk), deep links (sotp://), single-instance, drag-and-drop
CI/CD	GitHub Actions matrix (windows-latest, macos-14, ubuntu-22.04)
Docs	desktop/README.md, desktop/SMOKE_TESTS.md, desktop/CLOUD_SYNC_DESIGN.md

---

Architecture

Repository layout

sword-of-truth-publishing/
├── backend/                  # FastAPI application (primary codebase)
│   ├── app/                  # 70+ routers, middleware, app factory
│   ├── domain/               # Business logic (framework-agnostic)
│   ├── persistence/          # SQLAlchemy ORM + adapters
│   ├── composition/          # Manuscript rendering engine
│   ├── cover/                # Cover spec and generation
│   ├── distribution/         # KDP / IngramSpark / D2D connectors
│   ├── notifications/        # Transactional email (Resend SDK wrapper)
│   ├── validation/           # Content validation rules
│   ├── workers/              # Celery worker configuration (SaaS)
│   ├── alembic/versions/     # Migrations 0001–0011
│   └── tests/                # 1750+ tests across ~125 files
├── frontend/                 # Next.js 16 web UI (and desktop static export target)
│   └── src/
│       ├── app/(app)/        # Authenticated shell, 50+ pages
│       ├── components/ui/    # Shared UI primitives (PageHeader, Button, Card, …)
│       └── lib/              # Auth context, API client, hooks, analytics, feature-flags
├── docs/
│   ├── brand-identity/       # BRAND-BIBLE.md (24 sections), creative brief, color tokens
│   └── plans/
│       ├── DOCUMENT_CREATION_PLAN.md       # Phases 0–16 roadmap (complete)
│       ├── DESKTOP_COMPLETION_PLAN.md      # Phase 17 — desktop edition
│       ├── ui-ux-modernization-plan.md     # UI/UX modernization — 8-phase author-first redesign
│       ├── ARCHITECTURE.md
│       ├── DECISIONS.md
│       ├── GAP_ANALYSIS.md
│       ├── PACKAGING_PIPELINE.md
│       ├── ROADMAP.md
│       ├── VERIFICATION_GATES.md
│       ├── brand-identity-plan.md
│       └── rebrand-implementation-plan.md
├── icons/SwordOfTruth/       # Branded source assets (SVG)
├── sample-projects/          # Templates bundled with Desktop edition (planned)
├── manuskript/               # Legacy PyQt5 fork (DEPRECATED — see docs/plans/DESKTOP_COMPLETION_PLAN.md §17.9)
├── docker-compose.yml
└── README.md

Frontend route map (high level)

/                                              landing page
/login, /sign-up                               auth
/dashboard                                     authenticated shell
/projects                                      project list
/projects/[projectId]/                         project home
/projects/[projectId]/{characters, history, research, search, series,
                       readers, landing-page, launch, backup,
                       collections, annotations, footnotes, xrefs,
                       index, toc, styles, ornaments, conditions,
                       compile-filters, fountain, scratchpad,
                       scene-metadata, spellcheck, dictionary,
                       style-analysis, font-licenses, font-storage,
                       icc-profiles, locks, assignments,
                       review-cycles, track-changes, galley, export}
/projects/[projectId]/books/[bookId]/{compose, quality, artifacts,
                       distribution, cover, royalty, isbn, sales,
                       accessibility, paged-preview, print-marks,
                       arc, copy-fit, proof-orders}
/tools/{names, templates}
/settings

---

Prerequisites

• Python 3.13+
• Node.js 20+
• Docker and Docker Compose (for SaaS dev with Postgres + Redis)

---

Setup (SaaS / dev)

Backend

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

Configure:

cp .env.example .env

Edit backend/.env:

DATABASE_URL=postgresql+psycopg://sotpub:password@localhost:5432/sword_of_truth_publishing
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=<generate a strong random string>
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=60
EMAIL_ENABLED=true
RESEND_API_KEY=
EMAIL_FROM=noreply@swordoftruthpublishing.com

Start infra and migrate:

docker-compose up -d postgres redis
cd backend && alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API: http://localhost:8000 · Swagger: http://localhost:8000/docs

Frontend

cd frontend
npm install
npm run dev          # http://localhost:3000

Full stack via Docker

docker-compose up

---

Setup (Desktop)

See desktop/README.md for prerequisites, dev loop, and per-OS build instructions.

Quick start:

# Install deps
cd frontend && npm ci && cd ..
cd desktop  && npm ci && cd ..
pip install -r backend/requirements.txt pyinstaller

# Build sidecar + launch in dev mode
node desktop/scripts/build-sidecar.mjs
cd desktop && npm run tauri:dev

---

Legacy Manuskript client

The legacy PyQt5/Qt5 Manuskript client in manuskript/ has been superseded by
the Tauri Desktop Edition. The legacy entry point (bin/manuskript) will print
a deprecation message and exit. Build scripts in package/ and snap/ are
preserved for historical reference only.

To import existing .msk projects into the Desktop Edition, use
Settings → Migration → Import from Manuskript (.msk).

---

API

Base URL: /api/v1. Auth is JWT. All responses include X-Process-Time-Ms. Errors return {"detail": "message"}.

Route group	Base path	Operations
Auth	/auth	Register, login, logout, me
Projects	/projects	CRUD, word count
Books	/projects/{id}/books	CRUD
Composition	/projects/{id}/compose	Manuscript rendering, paged preview, profiles
Authoring	/projects/{id}/{characters, world, snapshots, annotations, footnotes, xrefs, index, toc, scratchpad, scene-metadata, search, series, ornaments, conditions, compile-filters, fountain, change-bars, track-changes, style-analysis, name-generator, templates, research, dictionary, collections, locks, assignments}	CRUD per feature
Editorial	/projects/{id}/{review-cycles, assignments, spellcheck, docx, ai-assist, copy-fit, galley}	Editorial workflow
Layout & typography	/projects/{id}/{styles, font-licenses, font-storage, icc-profiles, print-marks}	Layout/typography engine
Packaging	/projects/{id}/books/{id}/packaging	EPUB3, PDF, build, validate, quality, gates, diagnostics, export, A11y
Cover	/projects/{id}/cover	Spec, generate, validate, builder
Distribution	/projects/{id}/books/{id}/publish	Submit, sync, withdraw, sales, reconcile
Sales	/projects/{id}/books/{id}/sales	Records, by-channel, by-format
Royalty	/projects/{id}/books/{id}/royalty	Print-cost model, margin
ISBN	/projects/{id}/books/{id}/isbn	Validate, register per-format, remove
Proof orders	/projects/{id}/books/{id}/proof-orders	Proof copy workflow
ARC / readers	/projects/{id}/{arc, readers}	Beta readers, public ARC, feedback
Landing & launch	/projects/{id}/{landing-page, launch}	Author landing builder, launch checklist
Collaboration	/workspaces	Workspace, members, invites, presence, scene-collab
Realtime	/realtime/projects/{id}/books/{id}	WebSocket + SSE fallback
Notifications	/workspaces/{id}/notifications	In-app + email preferences
Webhooks	/webhooks/distribution/{channel}/events	Inbound distribution events
Storage	/projects/{id}/books/{id}/storage	Presigned upload/download
Backup	/projects/{id}/backup	DR snapshot/restore
Billing	/billing	Subscriptions, usage
Admin	/admin	Users, system stats
Ops	/ops	Health, backups, incidents, GDPR, rollout, launch gate
Migration	/api/v1/migration	Export to .sotp bundle, import .sotp, import .msk
Telemetry	/api/v1/telemetry	Opt-in anonymous usage events (Desktop only)
Licensing	/api/v1/license	Activate, status, deactivate (Desktop only)
Diagnostics	/api/v1/diagnostics	Logs, sidecar status (Desktop only)
Autosave	/api/v1/autosave	Draft save + pending recovery (Desktop + SaaS)

---

Testing

cd backend
pytest tests/ -v
pytest tests/ --cov=app --cov=domain --cov=persistence --cov-report=html

Current baseline: 1750+ tests across ~125 test files.

Coverage target: ≥85% on domain/, app/, persistence/.

Frontend e2e (Playwright):

cd frontend
npx playwright test

---

Development Status

Phase	Scope	Status
0–9	Foundation, domain, project/book CRUD, composition, cover, validation, collab, billing, auth, admin, ops, EPUB3/PDF generation, build orchestrator, channel validation, quality, gates, diagnostics, submission export	✅ Complete
10	Authoring enhancement layer — snapshots, annotations, scratchpad, scene metadata, search, series, ornaments, conditions, compile filters, Fountain, change bars, track changes, AI assist, spellcheck, DOCX, project templates	✅ Complete
11	Editorial workflow — assignments, review cycles, ARC/beta readers, redline, spellcheck/grammar	✅ Complete
12	Layout & typography engine — styles, footnotes, xrefs, index, ToC, paged preview, print marks, ornaments, ICC profiles, A11y compliance, font licenses	✅ Complete
12.5	Infrastructure foundations — DB migration, object storage, realtime transport, notifications, font storage, i18n, DR backup, security hardening, performance budgets	✅ Complete
13	Authoring → Production bridge — onboarding, scene collab, presence, offline (PWA), series management	✅ Complete
14	Production → Packaging bridge — composition, quality gate, artifact, distribution, cover builder, royalty estimator, ISBN procurement	✅ Complete
15	Packaging → Distribution bridge — live connectors, sales reporting, webhook secret management, proof orders	✅ Complete
16	Author platform & launch — landing page builder, launch checklist, newsletter/reader-list integrations	✅ Complete
17	Desktop edition — Tauri 2 + FastAPI sidecar + SQLite + license activation + offline-first	✅ Complete
UX	UI/UX Modernization — design system tokens, author-first nav, PageHeader primitive, desktop startup UX, offline banner, skip-to-content, analytics funnel, feature flags	✅ Complete

Deferred (non-blocking): e2e browser tests for editor keyboard workflows, e2e outline reorder regression tests, production S3 credential rollout.

---

Brand

Brand identity documentation is in docs/brand-identity/. The full brand system (positioning, color, typography, voice, SEO strategy, competitive analysis) is in BRAND-BIBLE.md.

Color palette: Espresso #1E1206 · Parchment #F5EDD8 · Amber Gold #C8963E · Burnished Oak #7A5C3A

Typography: Cormorant Garamond (display/headings) + Inter (UI/body)

Voice archetype: The Illuminator — "From manuscript to reader, with nothing lost."

---

Legacy: Manuskript (deprecated)

The manuskript/ directory contains the original open-source Manuskript desktop application (Python 3 + PyQt5, v0.17.0) from which this project was forked. It is preserved for .msk file format compatibility and reference. It is being retired as part of Phase 17 (docs/plans/DESKTOP_COMPLETION_PLAN.md §17.9). New users should use the SaaS web edition (now) or the Tauri desktop edition (Phase 17). Legacy .msk files import cleanly into both editions.