Files

Marcel 080e8eb55f docs(legibility): write human-targeted README.md at repo root — DOC-1

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 <noreply@anthropic.com>

2026-05-06 07:01:16 +02:00

3.7 KiB

Raw Blame History

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. 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

cp .env.example .env
# The defaults in .env.example work for local development without changes.

2. Start infrastructure

# Starts PostgreSQL, MinIO (object storage), and Mailpit (dev mail catcher)
docker compose up -d db minio mailpit

3. Start the backend

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

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).

Running the full stack via Docker (optional)

To run everything including the backend and frontend in containers:

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	C4 container and component diagrams (current system view)
docs/ARCHITECTURE.md (coming: DOC-2, #396)	Full architecture guide with domain list
docs/GLOSSARY.md	Overloaded terms: Person vs AppUser, Chronik vs Aktivität, etc.
CONTRIBUTING.md (coming: DOC-4, #398)	How to add a domain, endpoint, or SvelteKit route
docs/DEPLOYMENT.md (coming: DOC-5, #399)	Production deployment checklist and secrets guide
docs/adr/	Architecture Decision Records — the "why" behind key choices
Gitea issue tracker (internal — home network only)	Bug reports, feature requests, and project planning

3.7 KiB Raw Blame History Unescape Escape