Architecture Decision Records (ADR)¶
Key architectural decisions for the Prolexio project. Full details in _bmad-output/planning-artifacts/architecture.md.
Document Generation¶
ADR-DOC-001: Single Export Engine — docx-rs Hybrid + Gotenberg¶
Decision: Single export engine for all document types.
- DOCX export: Hybrid approach — pre-configured DOCX template + docx-rs for dynamic body content
- PDF export: Gotenberg (Docker/LibreOffice) converts DOCX → PDF (~500ms-1.5s per conversion)
- Typography: Arial Narrow 10px universally
- Fonts: Bundled in
server/assets/fonts/, included in Gotenberg Docker image
Rationale: Single engine simplifies codebase. DOCX is the source of truth for user editing. Typst was abandoned for document export (only used for technical memoir PDF).
Documentation¶
ADR-DOC-002: Documentation Anti-Obsolescence Architecture¶
Decision: Documentation treated as code with three enforcement levels.
- Automatic — Rustdoc/TypeDoc auto-generated, DB schema auto-generated, Playwright screenshots auto-updated
- Semi-automatic (CI) — Each doc file has frontmatter
covers:with glob patterns. CI detects drift (code changed but doc not updated) and orphan files (code with no covering doc) - Human — Definition of Done includes doc update. CLAUDE.md rule enforced
Key tools:
docs/scaffolding-rules.yaml— Auto-creates doc stubs for new handlers/components/pagesdocs/scaffold.sh— Generates stubs from code filesdocs/doc-ci.sh— CI drift and orphan detection
ADR-DOC-003: Three-Level Documentation Tooling¶
Decision: Three distinct documentation portals per audience.
| Portal | Tool | Location | Hosting |
|---|---|---|---|
| Developer docs | MkDocs Material | docs/dev/ |
Cloudflare Pages |
| User docs | Docusaurus | docs/user/ |
Cloudflare Pages |
| Technical memoir | Typst | docs/memoir/ |
CI artifact (PDF) |
| In-app help | HelpPanel (Svelte) | Embedded in Tauri | Offline |
Rationale: Each audience has fundamentally different needs. Single tool inadequate. MkDocs chosen over mdBook: better search, richer plugins.
ADR-DOC-004: In-App Help Enrichment¶
Decision: Enrich existing HelpPanel (not replace) with:
- Steps section — Numbered step-by-step process guides
- External doc link — "En savoir plus" button opens docs.prolexio.fr
- Consequence tooltips — Critical actions show hover tooltip explaining consequences
ADR-DOC-005: Demo Seed and Automated Screenshots¶
Decision: Dedicated demo seed with 100% fictional data.
- All names, SIRET, RCS, addresses are fictional
- Playwright automated screenshots at 1280x800 viewport
- Serves: user docs, technical memoir, commercial demos, dev docs
- Critical: Never real client data (RGPD compliance)
Infrastructure¶
Core Architectural Decisions¶
| Decision | Choice | Rationale |
|---|---|---|
| Backend framework | Axum | Async, tower middleware ecosystem |
| Database | PostgreSQL | JSON support, full-text search, enum types |
| ORM | sqlx | Compile-time query checking, no runtime overhead |
| Frontend framework | SvelteKit + Svelte 5 | Runes reactivity, small bundle, fast |
| Desktop wrapper | Tauri 2 | Rust-native, smaller than Electron |
| Auth | JWT + Argon2 + TOTP | Stateless auth, strong hashing, 2FA |
| DI pattern | Arc<dyn Trait> in AppState |
Testable, flexible, no macro magic |
| Locking | Optimistic (version column) |
No deadlocks, simple conflict detection |
| IDs | UUID v7 | Time-ordered, better index performance |