From a5d20f264eaa11cba2d00d4bbdf73cdcce609727 Mon Sep 17 00:00:00 2001 From: Marcel Date: Tue, 5 May 2026 22:38:03 +0200 Subject: [PATCH] =?UTF-8?q?docs(legibility):=20write=20human-targeted=20RE?= =?UTF-8?q?ADME.md=20at=20repo=20root=20=E2=80=94=20DOC-1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five-section front door for new contributors: product description, subsystem map, quick-start (local dev + full Docker variant), where-to-go-next with TODO markers for DOC-2/4/5, and one-line private license. Corrects stale port reference (3000→5173, per vite.config.ts). Links docs/GLOSSARY.md, docs/adr/, docs/architecture/c4-diagrams.md, and Gitea issue tracker with LAN qualifier. Closes #395 Co-Authored-By: Claude Sonnet 4.6 --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..d6c93a1a --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# Familienarchiv + +Familienarchiv is a private web application for digitising, organising, and searching a family document collection — letters, postcards, and photographs from 1899 to 1950. Family members upload scans, transcribe handwritten text (Kurrent/Sütterlin), and read the archive from any device. + +--- + +## Subsystems + +- `frontend/` — SvelteKit 2 / Svelte 5 / TypeScript / Tailwind 4 web app (server-side rendered) +- `backend/` — Spring Boot 4 (Java 21) REST API; handles documents, persons, search, and user management +- `ocr-service/` — Python FastAPI microservice for OCR and handwritten text recognition (HTR); single-node by design — see [ADR-001](docs/adr/001-ocr-python-microservice.md). Not part of the default dev stack (see Quick start below) +- `infra/` — Gitea Actions CI/CD config; future home for infrastructure-as-code +- `scripts/` — operational and data-pipeline helpers (`reset-db.sh`, `clean-e2e-data.sh`, import scripts) + +--- + +## Quick start + +**Prerequisites:** Java 21, Node 24, Docker with the `docker compose` plugin (V2). + +### 1. Configure environment + +```bash +cp .env.example .env +# The defaults in .env.example work for local development without changes. +``` + +### 2. Start infrastructure + +```bash +# Starts PostgreSQL, MinIO (object storage), and Mailpit (dev mail catcher) +docker compose up -d db minio mailpit +``` + +### 3. Start the backend + +```bash +cd backend +./mvnw spring-boot:run +# Starts on http://localhost:8080 +# API docs (dev profile, auto-enabled): http://localhost:8080/v3/api-docs +``` + +### 4. Start the frontend + +```bash +cd frontend +npm install +npm run dev +# Starts on http://localhost:5173 +``` + +Open **http://localhost:5173** — you should see the Familienarchiv login screen. + +Default development credentials: + +``` +# local dev only — change before any network-exposed deployment +Email: admin@familyarchive.local +Password: admin123 +``` + +> **Development setup only.** The default `docker compose` config exposes the database port and uses root MinIO credentials. Do not connect this to a network without first reading `docs/DEPLOYMENT.md` _(coming: [DOC-5, #399](http://heim-nas:3005/marcel/familienarchiv/issues/399))_. + +### Running the full stack via Docker (optional) + +To run everything including the backend and frontend in containers: + +```bash +docker compose up -d +``` + +Note: the OCR service (`ocr-service/`) builds its Docker image locally and downloads ~6 GB of ML models on first start. Expect 30–60 minutes on a first run. The rest of the stack starts independently; OCR can be excluded with `--scale ocr-service=0` on memory-constrained machines (requires ≥ 12 GB RAM). + +--- + +## Where to go next + +| Resource | Purpose | +|---|---| +| [docs/architecture/c4-diagrams.md](docs/architecture/c4-diagrams.md) | C4 container and component diagrams (current system view) | +| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) _(coming: [DOC-2, #396](http://heim-nas:3005/marcel/familienarchiv/issues/396))_ | Full architecture guide with domain list | +| [docs/GLOSSARY.md](docs/GLOSSARY.md) | Overloaded terms: Person vs AppUser, Chronik vs Aktivität, etc. | +| [CONTRIBUTING.md](CONTRIBUTING.md) _(coming: [DOC-4, #398](http://heim-nas:3005/marcel/familienarchiv/issues/398))_ | How to add a domain, endpoint, or SvelteKit route | +| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) _(coming: [DOC-5, #399](http://heim-nas:3005/marcel/familienarchiv/issues/399))_ | Production deployment checklist and secrets guide | +| [docs/adr/](docs/adr/) | Architecture Decision Records — the "why" behind key choices | +| [Gitea issue tracker](http://heim-nas:3005/marcel/familienarchiv/issues) _(internal — home network only)_ | Bug reports, feature requests, and project planning | + +--- + +## License + +Private project — all rights reserved. Not licensed for redistribution.