About verbweaver

A writing and design platform that thinks nonlinearly (in relationships) while enabling you to generate documents and communicate your work in a linear format.

v

Published by

verbweaver

Visit View Profile

README.md

View on GitHub

Verbweaver

Verbweaver is a writing and design platform that thinks in relationships (graphs). It's designed for writers, artists, engineers, developers, analysts, and anyone who wants to design things while linking every idea together and turning those ideas into manageable tasks. Think and take notes in a way that is natural to you. Then, when it comes time to communicate your ideas or information to other people, use the Compiler and the powerful templating engine to generate a linear document in various common filetypes.

Currently, the desktop application is in Beta. The web server version with enhanced collaboration features is under development and is not yet ready for use.

🌟 Features

Verbweaver Logo

Graph-based Design: Visualize relationships between your ideas, documents, and tasks
Task Management: Turn any idea into a trackable task with Kanban boards
Markdown-powered: All content is stored as Markdown files with metadata headers. The Pandoc Markdown format is used to enable exporting to many file formats using Pandoc with advanced formatting.
Write to your heart's content: Use the built-in Editor or your favorite Markdown editor application to write chapters, notes, data, findings, or anything else.
Unified Data Model: Everything is a node; a node is everything. A single file can be a written document, tracked as a Task, and visualized as a node on a graph.
Export Anywhere: Compile your non-linear notes into linear documents (PDF, Word, ePub, etc.)
Git Version Control: Built-in version control for all your projects
Multi-platform: Available as a web app and desktop app (Windows, Mac, Linux)

🚀 Getting Started

🖥️ Desktop Application (Recommended for Individual Writers)

The desktop application provides the best offline experience and bundles the frontend, a lightweight local backend, and default templates. It offers unique advantages compared to the web application:

Features

Offline Mode: Work without internet connection
Local Storage: Your data stays on your machine
Cross-platform: Built with Electron, the desktop app works on Windows, MacOS, and Linux
Native Performance: Faster file operations and Git integration
System Integration: Native file dialogs, system tray, auto-updates
No Authentication: Start working immediately

Intalling the desktop app

Installers are available for each release:

Windows: .exe installer
macOS: .dmg installer
- If the MacOS .app that you have is unsigned (such as by downloading the version automatically compiled by GitHub Actions), you may need to removed the quarantined attribute in order to run it: xattr -dr com.apple.quarantine Verbweaver.app
Linux: .AppImage (or .deb / .rpm installers)

Building the Desktop mode manually

Build from source (one-time setup):

# Clone
git clone https://github.com/Verbweaver/verbweaver.git
cd verbweaver

# Install workspace dependencies (root installs shared + frontend + desktop)
npm ci

# Build shared types and frontend (required before desktop packaging)
npm run build:shared
npm run build:frontend

Run in development (per platform)

Windows (PowerShell)

# Terminal 1 — Backend
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Desktop
cd desktop
npm install
npm run dev

For Windows, a convenient script to build and run the application in development mode is located at desktop\build-and-run.ps1.

macOS (zsh/bash)

# Terminal 1 — Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Desktop
cd desktop
npm install
npm run dev

Linux (bash)

# Terminal 1 — Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Desktop
cd desktop
npm install
npm run dev

Notes:

Packaged installers bundle and auto-start a platform-specific backend binary (no separate step needed).
In development you should run the backend yourself (two terminals as shown above).
Desktop packaging is handled by electron-builder. See scripts in desktop/package.json (dist, dist:win, dist:mac, dist:linux).

Web Application (For Teams) - WIP

Note: The web server version is incomplete and still in active development.

Perfect for collaboration and cloud access.

Quick start with Docker:

# From repo root
docker-compose up -d

Manual setup (separate terminals):

# Backend (FastAPI)
cd backend
python -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Frontend (Vite)
cd ../frontend
npm install
npm run dev  # serves at http://localhost:5173

🔧 Web Server Configuration

Key configuration options can be set via environment variables:

Environment (backend):

# .env
SECRET_KEY=change-me
DATABASE_URL=sqlite+aiosqlite:///./verbweaver.db
BACKEND_CORS_ORIGINS=http://localhost:5173

# OAuth (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GITHUB_CLIENT_ID=your-github-client-id

Using PostgreSQL instead of SQLite:

# .env (PostgreSQL)
SECRET_KEY=change-me
# Async SQLAlchemy driver string using asyncpg
DATABASE_URL=postgresql+asyncpg://verbweaver:verbweaver@localhost:5432/verbweaver
BACKEND_CORS_ORIGINS=http://localhost:5173

# Optional Redis cache
REDIS_URL=redis://localhost:6379/0

See .env.example for all available options.

Notes:

Ensure PostgreSQL is running locally and a database/user are created. For local dev:
- user: verbweaver, password: verbweaver, db: verbweaver
If you use docker-compose up -d, the compose file already provisions Postgres and Redis and points the backend to them.

Development Setup

For detailed setup instructions, see the Getting Started Guide.

If you are developing templates:

Global/default templates are bundled under assets/templates and copied into desktop builds.
The Compiler supports schema-driven variables and per-node variables; see docs/compiler-template-system.md.

🐳 Docker Deployment (Work in Progress)

Deploy Verbweaver using Docker:

docker-compose up -d

This will start:

Backend API on port 8000
Frontend on port 3000
PostgreSQL database (optional)
Redis for caching (optional)

🏗️ Architecture

Verbweaver uses a modern, scalable architecture:

Backend: Python with FastAPI, SQLAlchemy, and GitPython
Frontend: React with TypeScript, Vite, and Tailwind CSS
Desktop: Electron with secure IPC communication
Database: SQLite (default) or PostgreSQL
Real-time: WebSockets for collaboration

📦 Project Structure

verbweaver/
├── assets/                          # Static assets bundled with apps
│   └── templates/
│       ├── compiler/                # Default compiler templates by format
│       └── nodes/                   # Default node templates
├── backend/                         # FastAPI backend
│   ├── app/
│   │   ├── api/                     # API endpoints
│   │   ├── core/                    # Config, security
│   │   ├── db/                      # Sessions, redis client
│   │   ├── models/                  # Database models
│   │   ├── schemas/                 # Pydantic schemas
│   │   └── services/                # Business logic (compiler, templates, git)
│   └── tests/                       # Backend tests
├── desktop/                         # Electron desktop app
│   ├── src/
│   │   ├── main/                    # Main process
│   │   └── preload/                 # Preload scripts
│   └── resources/                   # Icons, packaging resources, defaults
├── docs/                            # Documentation site and guides
├── frontend/                        # React + Vite frontend
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   ├── store/
│   │   └── views/
│   └── package.json
├── nginx/                           # Reverse proxy configs
│   └── nginx.conf
├── shared/                          # Workspace with shared TS types/constants
│   ├── src/
│   │   ├── config.ts
│   │   ├── constants/
│   │   └── types/
│   └── package.json
├── docker-compose.yml               # Full-stack dev/deploy (backend, frontend, db, redis)
├── start-dev.ps1                    # Convenience dev script
├── start-dev.sh
└── README.md

📖 Documentation

Comprehensive documentation is available in the docs directory:

Getting Started Guide - Installation and setup
Architecture Overview - System design
API Reference - REST API documentation
User Guide - How to use Verbweaver
Developer Guide - Contributing and development
Repository Paths - How project storage works
Deployment Guide - Production deployment

🧪 Testing

Run the test suites:

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

# Desktop tests
cd desktop
npm test

# E2E tests
npm run test:e2e

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License + Commons Clause - see the LICENSE file for details.

The MIT License ensures that you have unrestricted rights to use, modify, and redistribute Verbweaver free of charge. However, the Commons Clause rider prohibits you from selling Verbweaver or a providing a service (such as a cloud-hosting solution) "whose value derives, entirely or substantially" from Verbweaver. If you wish to purchase a license exception to this clause, then please contact us with your offer.

🙏 Acknowledgments

Pandoc for the document file type conversion
- Pandoc is a separate program invoked by Verbweaver to generate documents in various formats. It is not "part of" Verbweaver in any way.
- The source code to the exact version of Pandoc that Verbweaver uses may be found at: https://github.com/jgm/pandoc/tree/3.8.1
Tectonic for the LaTeX typesetting system that can be run all as one binary
FastAPI for the excellent Python web framework
React for the UI library
React Flow for graph visualization
Monaco Editor for the code editor
Electron for cross-platform desktop apps
GitPython for Git integration
FullCalendar (core, daygrid) © Adam Shaw — MIT License. We redistribute CSS assets for offline availability. See license: https://fullcalendar.io/license/mit
All our contributors and supporters!

📞 Support & Communication

Documentation: docs/
Issues: GitHub Issues
Discord: Join our community
BlueSky: BlueSky
Email: https://verbweaver.design/contact

Built with ❤️ by the Verbweaver team