2e6cc346ab
Adds a second binding invariant section to ADR-012 covering the duplicate-id mechanism named in #553's follow-up investigation: same resolved module URL referenced via two distinct vi.mock id strings → @vitest/browser-playwright leaks an orphan Playwright route → birpc-closed crash in the next session. Records the rule (one canonical id per mocked module, prefer the spelling production uses, no-extension for .svelte rune modules), the in-suite detector (no-duplicate-mock-ids.test.ts), and the patch-package backport of vitest PR #10267 with its removal trigger. Extends the existing Consequences enforcement list from four layers to six, adding the duplicate-id detector and the patch-package layer. Refs: #553 · vitest-dev/vitest#9957 · vitest-dev/vitest#10267 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/
Project documentation organised 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)
├── ARCHITECTURE.md # Human-readable architecture overview (DOC-2)
├── DEPLOYMENT.md # Day-1 checklist and operational reference (DOC-5)
├── GLOSSARY.md # Domain terminology (DOC-3)
├── security-guide.md # Security policies and hardening guide
└── STYLEGUIDE.md # Coding and design style guide
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:
- Status (Proposed / Accepted / Deprecated / Superseded)
- Context (forces at play)
- Decision (what we decided)
- Consequences (trade-offs)
- Alternatives Considered (table format)
ADRs are sequential (NNN-descriptive-name.md). Do not reuse numbers.
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 diagrams (c4-diagrams.md). Gitea renders these automatically.
For the human-readable architecture narrative, see docs/ARCHITECTURE.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 and VPS provisioning |
s3-migration.md |
Migrating documents between S3 buckets |
self-hosted-catalogue.md |
Self-hosted software catalogue |
For the day-1 deployment checklist, see docs/DEPLOYMENT.md.
Specs (specs/)
High-fidelity UI/UX specifications written as standalone HTML files. These are design documents describing 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
Before implementing a feature, check specs/ for an existing specification.
Style Guide
docs/STYLEGUIDE.md covers:
- Code formatting and linting rules
- Component naming conventions
- Color palette and typography
- Accessibility standards (WCAG 2.1 AA)