50b18f0849
- docs/README.md: remove duplicate infrastructure/ entry at end of folder tree - ocr-service/CLAUDE.md: add **LLM reminder:** prefix to ALLOWED_PDF_HOSTS SSRF warning (consistent with all other machine-readable instructions) - backend/CLAUDE.md: restore ResponseStatusException note for simple controller validation — avoids LLMs reaching for DomainException for trivial checks Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# 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`](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`](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`](STYLEGUIDE.md) covers:
|
|
|
|
- Code formatting and linting rules
|
|
- Component naming conventions
|
|
- Color palette and typography
|
|
- Accessibility standards (WCAG 2.1 AA)
|