familienarchiv/docs/CLAUDE.md

Docs — Familienarchiv

Overview

Project documentation organized into four categories: architecture decision records (ADRs), system architecture diagrams, infrastructure runbooks, and detailed UI/UX specifications.

Folder Structure

docs/
├── adr/                     # Architecture Decision Records
├── architecture/            # C4 model diagrams and system architecture docs
├── infrastructure/          # Deployment, CI/CD, and ops guides
├── specs/                   # UI/UX feature specifications (HTML)
├── app-analysis-*.md        # Application analysis reports
├── mail.md                  # Mail system documentation
├── security-guide.md        # Security policies and hardening guide
├── STYLEGUIDE.md            # Coding and design style guide
├── TODO-backend.md          # Backend backlog
└── TODO-frontend.md         # Frontend backlog

ADR (adr/)

Architecture Decision Records capture major technical decisions and their rationale.

ADR	Title	Status
001-ocr-python-microservice.md	OCR as a separate Python container	Accepted
002-polygon-jsonb-storage.md	Polygon coordinates in JSONB columns	Accepted
003-chronik-unified-activity-feed.md	Unified activity feed (Chronik)	Accepted

When making a significant architectural change (new service, data model change, technology swap), write a new ADR following the format:

• Status (Proposed / Accepted / Deprecated / Superseded)
• Context (forces at play)
• Decision (what we decided)
• Consequences (trade-offs)
• Alternatives Considered (table format)

Architecture (architecture/)

Contains C4 model diagrams describing the system at different zoom levels:

• Context diagram — How Familienarchiv fits into the user and system ecosystem
• Container diagram — The high-level technology choices (Spring Boot, SvelteKit, PostgreSQL, MinIO, OCR service)
• Component diagram — Major structural components within the backend

Written in Markdown with embedded Mermaid or PlantUML diagrams (c4-diagrams.md).

Infrastructure (infrastructure/)

Operational documentation for running Familienarchiv in production and CI.

Document	Purpose
ci-gitea.md	Gitea CI/CD pipeline configuration
production-compose.md	Production Docker Compose setup
s3-migration.md	Migrating documents between S3 buckets
self-hosted-catalogue.md	Self-hosted software catalogue

Specs (specs/)

High-fidelity UI/UX specifications written as standalone HTML files. These are design documents that describe exact layout, interactions, and responsive behavior before implementation.

Each spec typically includes:

• Visual mockups with CSS-in-HTML styling
• Interaction flows and state transitions
• Responsive breakpoint behavior
• Accessibility requirements

Examples of active spec areas:

• Document detail page (document-topbar-*.html, documents-page-spec.html)
• Admin interfaces (admin-redesign-*.html, admin-tag-overhaul.html)
• Transcription workflows (inline-transcription-*.html, annotation-transcription-*.html)
• Dashboard and activity feeds (dashboard-*.html, chronik-spec.html)
• OCR admin (ocr-admin-spec.html)

How to Use

1. Before implementing a feature, check specs/ for an existing specification.
2. When proposing a new architecture, draft an ADR in adr/ and discuss before coding.
3. When deploying, follow infrastructure/production-compose.md.
4. Keep TODO files updated — they serve as lightweight backlogs.

Style Guide

STYLEGUIDE.md covers:

• Code formatting and linting rules
• Component naming conventions
• Color palette and typography
• Accessibility standards (WCAG 2.1 AA)

Contributing

• ADRs should be sequential (NNN-descriptive-name.md).
• Specs should be self-contained HTML files viewable in a browser.
• Infrastructure docs should include copy-pasteable commands.