Nautilus/ledgerdock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh README and add changelog baseline

Browse Source
This commit is contained in:
Beda Schmid
2026-02-21 12:46:53 -03:00
parent df401b9e55
commit 859acc133c
2 changed files with 109 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
CHANGELOG.md Normal file
View 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
View File

@@ -1,121 +1,154 @@
# DMS # 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: ## 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 - 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/`) ## Technology Stack
- Frontend: React + Vite + TypeScript (`frontend/`)
- Infrastructure: Postgres, Redis, Typesense (`docker-compose.yml`) - 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 ## Requirements
- Docker Engine - Docker Engine
- Docker Compose plugin - Docker Compose plugin
- Internet access for the first image build - Internet access for first-time image build
## Quick Start ## Quick Start
1. Start the full stack from repository root: From repository root:
```bash ```bash
docker compose up --build -d docker compose up --build -d
``` ```
2. Open services: Open:
- Frontend: `http://localhost:5173` - Frontend: `http://localhost:5173`
- Backend OpenAPI docs: `http://localhost:8000/docs` - API docs: `http://localhost:8000/docs`
- Health endpoint: `http://localhost:8000/api/v1/health` - Health: `http://localhost:8000/api/v1/health`
3. Stop when done: Stop the stack:
```bash ```bash
docker compose down docker compose down
``` ```
## Common Commands ## Common Operations
Start services: Start or rebuild:
```bash ```bash
docker compose up --build -d docker compose up --build -d
``` ```
Stop services: Stop:
```bash ```bash
docker compose down docker compose down
``` ```
Stream logs: Tail logs:
```bash ```bash
docker compose logs -f docker compose logs -f
``` ```
Rebuild services: Tail API and worker logs only:
```bash ```bash
docker compose down docker compose logs -f api worker
docker compose up --build -d
``` ```
Reset runtime data (destructive, removes named volumes): Reset all runtime data (destructive):
```bash ```bash
docker compose down -v 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 ## Data Persistence
Runtime state is persisted in Docker named volumes declared in `docker-compose.yml`: Docker named volumes used by the stack:
- `db-data` - `db-data`
- `redis-data` - `redis-data`
- `dcm-storage` - `dcm-storage`
- `typesense-data` - `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"}` - `GET /api/v1/health` returns `{"status":"ok"}`
- upload and processing complete successfully - Upload and processing complete successfully
- search returns expected results - Search returns expected results
- preview or download works for uploaded documents - Preview and download work for uploaded documents
- `docker compose logs -f` shows no API or worker failures - `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` ## Documentation Index
- 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. - `doc/README.md` - technical documentation entrypoint
## Technical Documentation
- `doc/README.md` - technical documentation index
- `doc/architecture-overview.md` - service and runtime architecture - `doc/architecture-overview.md` - service and runtime architecture
- `doc/api-contract.md` - HTTP endpoint contract and payload model map - `doc/api-contract.md` - endpoint and payload contract
- `doc/data-model-reference.md` - database model reference - `doc/data-model-reference.md` - persistence model reference
- `doc/operations-and-configuration.md` - operations runbook and configuration reference - `doc/operations-and-configuration.md` - runtime operations and configuration
- `doc/frontend-design-foundation.md` - frontend design system and UI rules - `doc/frontend-design-foundation.md` - frontend design rules