familienarchiv/CONTRIBUTING.md

Contributing to Familienarchiv

For the full collaboration rules (issue workflow, PR process, Red/Green TDD, commit conventions) see COLLABORATING.md. For coding style see CODESTYLE.md. For the system architecture see docs/ARCHITECTURE.md (introduced in DOC-2; until that PR merges, see docs/architecture/c4-diagrams.md). For domain terminology see docs/GLOSSARY.md.

---

1. Environment setup

Prerequisites: Java 21 (SDKMAN), Node 24 (nvm), Docker

Activate SDKMAN and nvm before running java, mvn, node, or npm:

source "$HOME/.sdkman/bin/sdkman-init.sh"
export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

---

2. Daily development workflow

Startup order — services must start in this sequence:

# 1. Start PostgreSQL and MinIO
docker compose up -d db minio

# 2. Start the backend (separate terminal)
cd backend && ./mvnw spring-boot:run

# 3. Start the frontend (separate terminal)
cd frontend && npm install && npm run dev

npm install also wires up the Husky pre-commit hook via the prepare script. Run it before your first commit, or the hook will fail to execute.

Do not use docker-compose.ci.yml locally — it disables the bind mounts that the dev workflow depends on.

Regenerate TypeScript types after any backend API change:

# Backend must be running with dev profile
cd frontend && npm run generate:api

⚠️ Forgetting this step is the most common cause of "where did my TypeScript type go?" — always regenerate after changing models or endpoints.

Test commands:

cd backend && ./mvnw test                 # backend unit + slice tests
cd frontend && npm run test               # Vitest unit tests
cd frontend && npm run check              # svelte-check (type errors)
cd frontend && npx playwright test        # Playwright e2e tests

Branch naming: <type>/<issue-number>-<short-description>, e.g. feat/398-contributing

Commits: one logical change per commit; reference the Gitea issue:

feat(person): add aliases endpoint

Closes #42
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Test-type decision matrix

What you're testing	Test type	Tool
Service business logic, calculations	Unit test	JUnit + @ExtendWith(MockitoExtension.class)
HTTP contract, request validation, error codes	Controller slice test	@WebMvcTest
Server load function	Vitest unit	Import directly, mock fetch
Shared UI component	Vitest browser-mode	render() + getByRole()
Full user-facing flow, navigation, forms	E2E	Playwright

---

3. Walkthrough A — Add a new domain

Example: adding a citation domain (formal references to documents).

Both the backend and frontend are organised domain-first. A new domain means adding a package on both sides under the same name.

Backend

1. Create backend/src/main/java/org/raddatz/familienarchiv/citation/

2. Add entity, repository, service, controller, and DTOs flat in the package:

   • Entity Citation.java — annotate with @Entity @Data @Builder @NoArgsConstructor @AllArgsConstructor; use @GeneratedValue(strategy = GenerationType.UUID) for the id field; add @Schema(requiredMode = REQUIRED) on every field the backend always populates
   • Repository CitationRepository.java — extends JpaRepository<Citation, UUID>
   • Service CitationService.java — @Service @RequiredArgsConstructor; write methods @Transactional, read methods unannotated; cross-domain data goes through the other domain's service, never its repository
   • Controller CitationController.java — @RestController @RequestMapping("/api/citations")

3. Add @RequirePermission(Permission.WRITE_ALL) on every POST, PUT, PATCH, and DELETE endpoint — this is not optional. Read-only GET endpoints stay unannotated.

4. Add a Flyway migration: backend/src/main/resources/db/migration/V{n}__{description}.sql (use the next sequential number after the highest existing one).

5. Write failing tests before any implementation (Red step):

   • Service unit test for business logic (@ExtendWith(MockitoExtension.class))
   • @WebMvcTest slice test for each HTTP endpoint

6. Rebuild with --spring.profiles.active=dev and run npm run generate:api in frontend/.

Frontend

7. Create frontend/src/lib/citation/ — domain-specific Svelte components and TypeScript utilities go here.

8. Add routes under frontend/src/routes/citations/ as needed.

9. Add a per-domain README.md in both the backend package folder and frontend/src/lib/citation/ (per DOC-6).

Documentation

10. Update docs/ARCHITECTURE.md Section 2 to include the new domain.
11. Update docs/GLOSSARY.md if new terms are introduced.
12. Update the ESLint boundary allow-list in frontend/eslint.config.js if the domain needs to import from another domain.

---

4. Walkthrough B — Add a new endpoint

Example: POST /api/persons/{id}/aliases — attach a name alias to an existing person.

Red (write failing tests first)

1. Write a failing @WebMvcTest controller slice test:

   @Test
   void addAlias_returns201_whenAliasCreated() { ... }
   

2. Write a failing service unit test:

   @Test
   void addAlias_throwsNotFound_whenPersonDoesNotExist() { ... }
   

Green (implement)

3. Add the service method in PersonService.java:

   @Transactional
   public PersonNameAlias addAlias(UUID personId, PersonNameAliasDTO dto) { ... }
   

4. Add the controller method in PersonController.java:

   @PostMapping("/{id}/aliases")
   @RequirePermission(Permission.WRITE_ALL)
   public ResponseEntity<PersonNameAlias> addAlias(@PathVariable UUID id,
                                                   @RequestBody PersonNameAliasDTO dto) { ... }
   

   @RequirePermission(Permission.WRITE_ALL) on every state-mutating endpoint — not optional.

5. Validate user-supplied inputs at the controller boundary:

   if (dto.name() == null || dto.name().isBlank())
       throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "name is required");
   

   Validate at system boundaries; trust internal service code.

6. Use DomainException for domain errors:

   DomainException.notFound(ErrorCode.PERSON_NOT_FOUND, "Person not found: " + id)
   

   If you need a new error code, add it to ErrorCode.java, mirror it in frontend/src/lib/shared/errors.ts, and add translation keys in messages/{de,en,es}.json.

7. Mark every field the backend always populates with @Schema(requiredMode = REQUIRED) — this drives TypeScript type generation.

Types and tests

8. Rebuild with --spring.profiles.active=dev, then npm run generate:api in frontend/.

   ⚠️ Always regenerate types after any API change. This is the #1 cause of "where did my TypeScript type go?"

9. Run the full test suite — all green before committing.

---

5. Walkthrough C — Add a new frontend page

Example: /persons/[id]/timeline — a chronological event timeline for one person.

Red (write failing test first)

1. Write a failing Playwright E2E test for the user flow:

   test('timeline shows events in chronological order', async ({ page }) => {
       await page.goto('/persons/1/timeline');
       // assertions...
   });
   

Green (implement)

2. Create frontend/src/routes/persons/[id]/timeline/+page.svelte

3. Add frontend/src/routes/persons/[id]/timeline/+page.server.ts for the SSR load:

   import { createApiClient } from '$lib/shared/api.server';
   export const load: PageServerLoad = async ({ params, fetch }) => {
       const api = createApiClient(fetch);
       const result = await api.GET('/api/persons/{id}', { params: { path: { id: params.id } } });
       if (!result.response.ok) throw error(result.response.status, '...');
       return { person: result.data! };
   };
   

4. Domain-specific components (e.g. TimelineEntry.svelte) → frontend/src/lib/person/

5. Shared primitives (e.g. a generic date-range display) → frontend/src/lib/shared/primitives/

6. UI patterns to follow:

   • Back navigation: import BackButton from '$lib/shared/primitives/BackButton.svelte'
   • Date display: always append T12:00:00 — new Intl.DateTimeFormat('de-DE', …).format(new Date(val + 'T12:00:00')) — prevents UTC off-by-one errors
   • Brand colors: brand-navy, brand-mint, brand-sand (defined in src/routes/layout.css)
   • Accessibility: touch targets ≥ 44 px (min-h-[44px]); focus rings (focus-visible:ring-2 focus-visible:ring-brand-navy); aria-label on icon-only buttons; aria-live="polite" on dynamic status messages

7. Add Paraglide i18n keys in messages/de.json, messages/en.json, messages/es.json.

8. If adding a new error code: mirror in frontend/src/lib/shared/errors.ts and add translation keys.

9. Make all tests green before committing.

---

6. Conventions reference

Error handling

Scenario	Pattern
Domain entity not found	DomainException.notFound(ErrorCode.X, "…")
Permission denied	DomainException.forbidden("…")
Concurrent edit conflict	DomainException.conflict(ErrorCode.X, "…")
Infrastructure failure	DomainException.internal(ErrorCode.X, "…")
Simple controller validation	throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "…")

New error code: ErrorCode.java → frontend/src/lib/shared/errors.ts → messages/{de,en,es}.json.

DTOs

• Input DTOs live flat in the domain package (e.g. PersonUpdateDTO.java)
• Responses are the entity itself — no separate response DTOs
• @Schema(requiredMode = REQUIRED) on every field the backend always populates

Frontend API client

const api = createApiClient(fetch); // from $lib/shared/api.server
const result = await api.GET('/api/persons/{id}', { params: { path: { id } } });
if (!result.response.ok) {
    const code = (result.error as unknown as { code?: string })?.code;
    throw error(result.response.status, getErrorMessage(code));
}
return { person: result.data! }; // non-null assertion is safe after the ok check

For multipart/form-data (file uploads): bypass the typed client and use raw fetch — the client cannot handle it.

Date handling

Context	Pattern
Form display	German dd.mm.yyyy with auto-dot insertion via handleDateInput()
Wire format	ISO 8601 via a hidden <input type="hidden" name="documentDate" value={dateIso}>
Display	new Intl.DateTimeFormat('de-DE', …).format(new Date(val + 'T12:00:00'))

Security checklist (new endpoint)

• @RequirePermission(Permission.WRITE_ALL) on every POST, PUT, PATCH, DELETE — required, not optional
• Validate all user-supplied inputs at the controller boundary before passing to the service
• Parameterised queries only — never interpolate user input into JPQL/SQL strings
• No raw user input in log messages — use {} placeholders: log.warn("Not found: {}", id)
• Validate content-type and size on upload endpoints before reading the stream

Accessibility baseline (new frontend page)

• Touch targets ≥ 44 px on all interactive elements (min-h-[44px])
• Focus rings on all focusable elements (focus-visible:ring-2 focus-visible:ring-brand-navy)
• aria-label on every icon-only button
• aria-live="polite" on dynamic status messages
• Color is never the sole status indicator

Full WCAG 2.1 AA reference: docs/STYLEGUIDE.md.

Lint and format

# Frontend
cd frontend && npm run lint     # Prettier + ESLint check
cd frontend && npm run format   # Auto-fix formatting
cd frontend && npm run check    # svelte-check (type errors)

# Backend — no standalone lint tool; compilation and test runs catch style issues
cd backend && ./mvnw test       # compile + test
cd backend && ./mvnw clean package -DskipTests  # compile-only check