e63adb964d
- backend/workspaces/backend/ → backend/ - backend/workspaces/frontend/ → frontend/ - backend/.devcontainer/ + .vscode/ → repo root (where VS Code expects them) - loose scripts/SQL files → scripts/ - replace nested git repo with single repo at project root - update docker-compose.yml build context and devcontainer.json path - add root .gitignore Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
# 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
|
|
```bash
|
|
# From repo root — starts PostgreSQL, MinIO, and Spring Boot backend
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Backend (Spring Boot)
|
|
```bash
|
|
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)
|
|
```bash
|
|
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.
|