86c13a230c
Processes all 7 CLAUDE.md files according to the 3-bucket classification. Migration targets (CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/DEPLOYMENT.md, domain READMEs) are introduced by DOC-2/4/5/6 — this PR must merge last. ### scripts/CLAUDE.md → scripts/README.md New `scripts/README.md` with full script documentation (preserving the ⚠️ destructive-operation warning on reset-db.sh). `scripts/CLAUDE.md` reduced to a pointer + "document new scripts in README.md" reminder. ### .devcontainer/CLAUDE.md → .devcontainer/README.md New `.devcontainer/README.md` with all configuration, usage, and limitations. `devcontainer/CLAUDE.md` reduced to a single pointer line. ### docs/CLAUDE.md → docs/README.md New `docs/README.md` covering the folder structure, ADR guide, infrastructure docs, and specs folder. `docs/CLAUDE.md` reduced to pointer + ADR reminder. ### ocr-service/CLAUDE.md Reduced to pointer to `ocr-service/README.md` (content migrated in DOC-6). Kept LLM reminders: single-node constraint, ALLOWED_PDF_HOSTS SSRF risk. ### backend/CLAUDE.md - Layering Rules → pointer to docs/ARCHITECTURE.md - Error Handling → pointer to CONTRIBUTING.md + reminder - Security/Permissions → pointer to docs/ARCHITECTURE.md + reminder - Package Structure → tagged TODO post-REFACTOR-1 - Fixed errors.ts path to frontend/src/lib/shared/errors.ts - Added ANNOTATE_ALL + BLOG_WRITE to permission list - Key Entities, Entity Code Style, Services → kept (Bucket-2) ### root CLAUDE.md - Stack, Infrastructure, Dev Container → pointers - Layering Rules, Error Handling, Security, OpenAPI, API Client, Date Handling, UI Components, Frontend Error Handling → pointers + reminders - Package Structure → tagged TODO post-REFACTOR-1 - Domain Model, Entity Code Style, Form Actions, Styling → kept (Bucket-2) ### frontend/CLAUDE.md - API Client Pattern, Date Handling → pointers + reminders - Key UI Components → pointer to domain READMEs - Styling, Form Actions, How to Run, Vite Proxy, i18n → kept (Bucket-2) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
87 lines
3.8 KiB
Markdown
87 lines
3.8 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
|
|
└── infrastructure/ # Production compose, CI config, S3 migration
|
|
```
|
|
|
|
## 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)
|