familienarchiv/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Familienarchiv is a family document archival system — a full-stack web app for digitizing, organizing, and searching family documents. Key features: file uploads (stored in MinIO/S3), metadata management, Excel batch import, full-text search, conversation threads between family members, and role-based access control.

Stack

• Backend: Spring Boot 4.0 (Java 21, Maven, Jetty, JPA/Hibernate, Flyway, Spring Security, Spring Session JDBC)
• Frontend: SvelteKit 2 with Svelte 5, TypeScript, Tailwind CSS 4, Paraglide.js (i18n: de/en/es)
• Database: PostgreSQL 16
• Object Storage: MinIO (S3-compatible)
• Infrastructure: Docker Compose

Common Commands

Running the Full Stack

# From repo root — starts PostgreSQL, MinIO, and Spring Boot backend
docker-compose up -d

Backend (Spring Boot)

cd backend

./mvnw spring-boot:run          # Run locally
./mvnw clean package            # Build JAR (with tests)
./mvnw clean package -DskipTests
./mvnw test                     # Run all tests
./mvnw test -Dtest=ClassName    # Run a single test class

Frontend (SvelteKit)

cd frontend

npm install
npm run dev         # Dev server (port 3000)
npm run build       # Production build
npm run preview     # Preview production build

npm run lint        # Prettier + ESLint check
npm run format      # Auto-fix formatting
npm run check       # svelte-check (type checking)
npm run test        # Vitest unit tests

Architecture

Backend (backend/src/main/java/org/raddatz/familienarchiv/)

Layered architecture:

• model/ — JPA entities: Document, Person, AppUser, UserGroup, Tag, DocumentStatus (enum: PLACEHOLDER → UPLOADED → TRANSCRIBED → REVIEWED → ARCHIVED)
• repository/ — Spring Data repositories + DocumentSpecifications for complex filtered queries
• service/ — Core business logic: DocumentService (uploads, search, Excel import), FileService (MinIO/S3), ExcelService, MassImportService, UserService
• controller/ — REST endpoints: DocumentController, PersonController, UserController, AdminController, GroupController, TagController
• security/ — SecurityConfig (HTTP Basic + form login, CSRF disabled), PermissionAspect (AOP enforcement of @RequirePermission), CustomUserDetailsService
• config/ — MinioConfig (creates S3Client, validates connectivity on startup), AsyncConfig

Database migrations live in src/main/resources/db/migration/ (Flyway). Configuration in src/main/resources/application.properties — most values injected from environment variables (DB credentials, MinIO endpoint/credentials/bucket, upload limits, Excel column mappings).

Frontend (backend/workspaces/frontend/src/)

• hooks.server.ts — Central middleware: reads auth_token cookie, injects it into all API calls to the backend, loads current user context
• routes/ — File-based routing. Main pages: / (search/home), /documents/[id], /documents/[id]/edit, /persons, /persons/[id], /conversations, /admin, /login
• routes/api/ — SvelteKit API endpoints for typeahead (persons, tags) — these call the Spring Boot backend
• lib/components/ — PersonTypeahead.svelte, TagInput.svelte
• messages/ — Paraglide.js translation files (de.json, en.json, es.json)

Authentication: form login → backend sets session → auth_token cookie → hooks.server.ts injects into all backend requests.

Key Design Patterns

• Search: DocumentSpecifications (Spring Data JPA Specification pattern) enables composable, dynamic query building for the document search endpoint
• Permissions: @RequirePermission annotation processed by PermissionAspect (AOP) — checks user's UserGroup permissions at the method level
• Excel Import: Configurable column index mapping in application.properties; ExcelService parses → MassImportService upserts documents
• File Storage: FileService wraps AWS SDK v2 S3Client with path-style access for MinIO compatibility

Infrastructure

The docker-compose.yml at the repo root orchestrates everything. A MinIO MC helper container runs at startup to create the archive-documents bucket and set permissions. The backend container depends on both db and minio being healthy before starting.

API Testing

HTTP test files are in backend/api_tests/ (Document.http, User.http) for use with the VS Code REST Client extension.

Dev Container

A .devcontainer/ config is available (Java 21 + Node 24, with ports 8080 and 3000 forwarded). Use VS Code's "Reopen in Container" to get a pre-configured environment with Spring Boot Tools, Lombok support, and database/MinIO services running.