Project
Sword of Truth Publishing
An end-to-end self-publishing platform for independent authors — spanning manuscript authoring, editorial workflow, interior composition, EPUB3/PDF packaging, and multi-channel distribution to KDP, IngramSpark, and Draft2Digital — shipped in both SaaS and Desktop editions.
Sword of Truth Publishing addresses the fragmented toolchain independent authors face when moving from first draft to retail distribution. The platform was built from a clean architectural break from a Manuskript/PyQt5 legacy codebase, evolving into a modern FastAPI + Next.js 16 + Tauri 2 stack across 17 phased deliveries. The technical scope spans authoring (outline, scene hierarchy, snapshots, track changes, Fountain mode), editorial review cycles and ARC/beta reader flows, interior composition with paged preview and compile filters, EPUBCheck-conformant EPUB3 and print-ready PDF generation, and a connector framework routing submissions to KDP, IngramSpark, and Draft2Digital. The Desktop Edition ships as a Tauri 2 shell wrapping a Next.js static export and a FastAPI sidecar, with SQLite persistence, OS keychain credential management, APScheduler-driven backups, and a CI matrix covering Windows, macOS, and Linux. The SaaS edition adds real-time collaboration over WebSocket/SSE, Celery job queues, PostgreSQL, and Stripe-backed subscription billing. All 17 phases complete as of May 2026; 1750+ backend tests passing.
Project README
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 |
| fpdf2 | 2.8.7 | Both | |
| 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.
