# 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:

```bash
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:

```bash
docker compose down
```

## Common Commands

Start services:

```bash
docker compose up --build -d
```

Stop services:

```bash
docker compose down
```

Stream logs:

```bash
docker compose logs -f
```

Rebuild services:

```bash
docker compose down
docker compose up --build -d
```

Reset runtime data (destructive, removes named volumes):

```bash
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