98 lines
3.9 KiB
Markdown
98 lines
3.9 KiB
Markdown
# 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.
|