122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
# 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
|