Self-hostable backend for organizations — synchronization, document processing, OCR, indexing, permissions, collaboration, workflows, audit logs, retention policies, and external integrations.
Organizations self-host docsgraph-server to let their team use the
local-first docsgraph client
(SQLite-backed, offline-capable) while syncing, collaborating, and
running heavier processing (OCR, indexing) centrally.
- API: FastAPI (async).
- Database: PostgreSQL, accessed via SQLAlchemy's async engine. This server is the source of truth for synchronized state.
- Sync protocol: clients keep a local SQLite copy and an ordered
changelog of offline ops. They push batches of ops to
POST /api/v1/sync/push; the server assigns each a global sequence number, applies it to Postgres, and acknowledges it. Clients pull ops from other clients newer than their last-seen sequence number viaGET /api/v1/sync/pull. Seesrc/docsgraph_server/sync/for the documented contract (currently scaffolded, not yet implemented). - Migrations: Alembic, wired to the SQLAlchemy metadata in
src/docsgraph_server/db/. - Background jobs: arq (async, Redis-backed) for OCR, indexing, and other deferred work.
- Auth: JWT-based.
Requires uv and Docker.
# Bring up Postgres + Redis for local development docker compose up -d # Install dependencies (including dev extras) uv sync --all-extras --locked # Copy env defaults (matches docker-compose.yml) cp .env.example .env # Apply database migrations uv run alembic upgrade head # Run the API with auto-reload uv run uvicorn docsgraph_server.main:app --reload
The API will be available at http://localhost:8000, with a liveness
check at GET /health.
To run the background job worker:
uv run arq docsgraph_server.jobs.worker.WorkerSettings
Run these before opening a PR (CI runs the same set on Python 3.12 and 3.13):
uv run ruff check . uv run ruff format --check . uv run mypy src tests uv run pytest
Everything lives under src/docsgraph_server/:
| Module | Purpose |
|---|---|
main.py |
FastAPI app factory (create_app()), router mounting, /health. |
core/ |
Cross-cutting concerns: settings (config.py), read from env/.env. |
db/ |
Async SQLAlchemy engine/session, declarative base, Alembic migrations. |
api/ |
HTTP routers, one module per domain area (documents, permissions, workflows, audit). |
sync/ |
The client/server sync protocol: pydantic models + route stubs. |
ocr/ |
OCR engine interface; Tesseract is the intended first backend. |
indexing/ |
Search/embedding indexing interface. |
permissions/ |
Permission/ACL model interface. |
workflows/ |
Workflow/automation engine interface. |
audit/ |
Audit log recording interface. |
retention/ |
Retention policy enforcement interface. |
integrations/ |
External integrations (cloud storage, e-signature, SSO, webhooks, ...). |
jobs/ |
arq worker configuration and background task definitions. |
Most non-api/sync modules currently expose interfaces only
(typing.Protocol) — concrete implementations land as each area is built
out.
MIT, see LICENSE.