docs: refresh README and add changelog baseline
This commit is contained in:
20
CHANGELOG.md
Normal file
20
CHANGELOG.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# Changelog
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
- Initialized `CHANGELOG.md` with Keep a Changelog structure for ongoing release-note tracking.
|
||||
|
||||
### Changed
|
||||
- Refreshed `README.md` with current stack details, runtime services, setup commands, configuration notes, and manual validation guidance.
|
||||
|
||||
### Deprecated
|
||||
|
||||
### Removed
|
||||
|
||||
### Fixed
|
||||
|
||||
### Security
|
||||
145
README.md
145
README.md
@@ -1,121 +1,154 @@
|
||||
# DMS
|
||||
|
||||
DMS is a single-user document management system for ingesting, processing, organizing, and searching files.
|
||||
DMS is a self-hosted 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
|
||||
## Core Capabilities
|
||||
|
||||
## Stack
|
||||
- Drag and drop upload from anywhere in the UI
|
||||
- File and folder upload with path preservation
|
||||
- Asynchronous extraction and OCR for PDF, images, DOCX, XLSX, TXT, and ZIP
|
||||
- Metadata and full-text search
|
||||
- Routing suggestions based on previous decisions
|
||||
- Original file download and extracted markdown export
|
||||
|
||||
- Backend: FastAPI + SQLAlchemy + RQ worker (`backend/`)
|
||||
- Frontend: React + Vite + TypeScript (`frontend/`)
|
||||
- Infrastructure: Postgres, Redis, Typesense (`docker-compose.yml`)
|
||||
## Technology Stack
|
||||
|
||||
- Backend: FastAPI, SQLAlchemy, RQ worker (`backend/`)
|
||||
- Frontend: React, Vite, TypeScript (`frontend/`)
|
||||
- Infrastructure: PostgreSQL, Redis, Typesense (`docker-compose.yml`)
|
||||
|
||||
## Runtime Services
|
||||
|
||||
The default `docker compose` stack includes:
|
||||
|
||||
- `frontend` - React UI (`http://localhost:5173`)
|
||||
- `api` - FastAPI backend (`http://localhost:8000`, docs at `/docs`)
|
||||
- `worker` - background processing jobs
|
||||
- `db` - PostgreSQL (`localhost:5432`)
|
||||
- `redis` - queue backend (`localhost:6379`)
|
||||
- `typesense` - search index (`localhost:8108`)
|
||||
|
||||
## Requirements
|
||||
|
||||
- Docker Engine
|
||||
- Docker Compose plugin
|
||||
- Internet access for the first image build
|
||||
- Internet access for first-time image build
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Start the full stack from repository root:
|
||||
From repository root:
|
||||
|
||||
```bash
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
2. Open services:
|
||||
Open:
|
||||
|
||||
- Frontend: `http://localhost:5173`
|
||||
- Backend OpenAPI docs: `http://localhost:8000/docs`
|
||||
- Health endpoint: `http://localhost:8000/api/v1/health`
|
||||
- API docs: `http://localhost:8000/docs`
|
||||
- Health: `http://localhost:8000/api/v1/health`
|
||||
|
||||
3. Stop when done:
|
||||
Stop the stack:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
## Common Operations
|
||||
|
||||
Start services:
|
||||
Start or rebuild:
|
||||
|
||||
```bash
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
Stop services:
|
||||
Stop:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
Stream logs:
|
||||
Tail logs:
|
||||
|
||||
```bash
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
Rebuild services:
|
||||
Tail API and worker logs only:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
docker compose up --build -d
|
||||
docker compose logs -f api worker
|
||||
```
|
||||
|
||||
Reset runtime data (destructive, removes named volumes):
|
||||
Reset all runtime data (destructive):
|
||||
|
||||
```bash
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## Frontend-Only Local Workflow
|
||||
|
||||
If backend services are already running, you can run frontend tooling locally:
|
||||
|
||||
```bash
|
||||
cd frontend && npm run dev
|
||||
cd frontend && npm run build
|
||||
cd frontend && npm run preview
|
||||
```
|
||||
|
||||
`npm run preview` serves the built app on port `4173`.
|
||||
|
||||
## Configuration
|
||||
|
||||
Main runtime variables are defined in `docker-compose.yml`:
|
||||
|
||||
- API and worker: `DATABASE_URL`, `REDIS_URL`, `STORAGE_ROOT`, `PUBLIC_BASE_URL`, `CORS_ORIGINS`, `TYPESENSE_*`
|
||||
- Frontend: `VITE_API_BASE`
|
||||
|
||||
Application settings saved from the UI persist at:
|
||||
|
||||
- `<STORAGE_ROOT>/settings.json` (inside the storage volume)
|
||||
|
||||
Settings endpoints:
|
||||
|
||||
- `GET/PUT /api/v1/settings`
|
||||
- `POST /api/v1/settings/reset`
|
||||
- `POST /api/v1/settings/handwriting`
|
||||
- `POST /api/v1/processing/logs/trim`
|
||||
|
||||
Note: the compose file currently includes host-specific URL values (for example `PUBLIC_BASE_URL` and `VITE_API_BASE`). Adjust these for your environment when needed.
|
||||
|
||||
## Data Persistence
|
||||
|
||||
Runtime state is persisted in Docker named volumes declared in `docker-compose.yml`:
|
||||
Docker named volumes used by the stack:
|
||||
|
||||
- `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.
|
||||
## Validation Checklist
|
||||
|
||||
## Configuration Notes
|
||||
After setup or config changes, verify:
|
||||
|
||||
- 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
|
||||
- Upload and processing complete successfully
|
||||
- Search returns expected results
|
||||
- Preview and download work for uploaded documents
|
||||
- `docker compose logs -f api worker` has no failures
|
||||
|
||||
## API Surface Summary
|
||||
## Repository Layout
|
||||
|
||||
Base prefix: `/api/v1`
|
||||
- `backend/` - FastAPI API, services, models, worker
|
||||
- `frontend/` - React application
|
||||
- `doc/` - technical documentation for architecture, API, data model, and operations
|
||||
- `docker-compose.yml` - local runtime topology
|
||||
|
||||
- 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`
|
||||
## Documentation Index
|
||||
|
||||
See `doc/api-contract.md` for the complete endpoint contract.
|
||||
|
||||
## Technical Documentation
|
||||
|
||||
- `doc/README.md` - technical documentation index
|
||||
- `doc/README.md` - technical documentation entrypoint
|
||||
- `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
|
||||
- `doc/api-contract.md` - endpoint and payload contract
|
||||
- `doc/data-model-reference.md` - persistence model reference
|
||||
- `doc/operations-and-configuration.md` - runtime operations and configuration
|
||||
- `doc/frontend-design-foundation.md` - frontend design rules
|
||||
|
||||
Reference in New Issue
Block a user