ledgerdock/README.md

DMS

DMS is a single-user document management system for ingesting, processing, organizing, and searching files.

Core capabilities:

• drag-and-drop upload from anywhere in the UI
• file and folder upload with path preservation
• asynchronous processing with OCR and extraction for PDF, images, DOCX, XLSX, TXT, and ZIP
• metadata and full-text search
• routing suggestions based on learned decisions
• original file download and extracted markdown export

Stack

• Backend: FastAPI + SQLAlchemy + RQ worker (backend/)
• Frontend: React + Vite + TypeScript (frontend/)
• Infrastructure: Postgres, Redis, Typesense (docker-compose.yml)

Requirements

• Docker Engine
• Docker Compose plugin
• Internet access for the first image build

Quick Start

1. Start the full stack from repository root:

docker compose up --build -d

2. Open services:

• Frontend: http://localhost:5173
• Backend OpenAPI docs: http://localhost:8000/docs
• Health endpoint: http://localhost:8000/api/v1/health

3. Stop when done:

docker compose down

Common Commands

Start services:

docker compose up --build -d

Stop services:

docker compose down

Stream logs:

docker compose logs -f

Rebuild services:

docker compose down
docker compose up --build -d

Reset runtime data (destructive, removes named volumes):

docker compose down -v

Data Persistence

Runtime state is persisted in Docker named volumes declared in docker-compose.yml:

• db-data
• redis-data
• dcm-storage
• typesense-data

The application settings file is stored under the storage volume at /data/storage/settings.json inside containers.

Configuration Notes

• API and worker runtime environment values are configured in docker-compose.yml (DATABASE_URL, REDIS_URL, STORAGE_ROOT, PUBLIC_BASE_URL, CORS_ORIGINS, TYPESENSE_*).
• Frontend API target is controlled by VITE_API_BASE in the frontend service.
• Handwriting, provider, routing, summary, display, and upload defaults are managed through the settings UI and persisted by the backend settings service.

Manual Validation Checklist

After changes, verify:

• GET /api/v1/health returns {"status":"ok"}
• upload and processing complete successfully
• search returns expected results
• preview or download works for uploaded documents
• docker compose logs -f shows no API or worker failures

API Surface Summary

Base prefix: /api/v1

• Health: /health
• Documents: /documents (listing, upload, metadata update, lifecycle actions, download and preview, markdown export)
• Search: /search
• Processing logs: /processing/logs
• Settings: /settings and /settings/handwriting

See doc/api-contract.md for the complete endpoint contract.

Technical Documentation

• doc/README.md - technical documentation index
• doc/architecture-overview.md - service and runtime architecture
• doc/api-contract.md - HTTP endpoint contract and payload model map
• doc/data-model-reference.md - database model reference
• doc/operations-and-configuration.md - operations runbook and configuration reference
• doc/frontend-design-foundation.md - frontend design system and UI rules