080e8eb55f
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>
94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
# 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.
|