# Document Quality Plan
**Goal:** Every generated document looks professional. PDF preview enables easy printing and email attachment.
## Audit Findings (June 16, 2026)
### Current State
- 10 templates: stripe, hubspot, notion, classic, modern, professional, minimal, bold, receipt, customer_portal
- PDF generation via WeasyPrint — functional but not polished
- Preview modal: iframe-based, no print button, download opens new tab
- Default layout: stripe ✓
- Fonts: Inter (full family), DejaVu, Liberation, JetBrains Mono, Source Serif 4 — all installed
### Issues Identified
| # | Issue | Severity | Effort |
|---|-------|----------|--------|
| 1 | Fontconfig cache dir not writable — noisy logs on every PDF gen | Low | 5 min |
| 2 | Preview modal lacks print button, iframe is awkward for "print/attach" | High | 15 min |
| 3 | Classic template: basic styling, lacks professional polish | Med | 30 min |
| 4 | Modern template: inconsistent spacing, needs tightening | Med | 20 min |
| 5 | Professional template: underwhelming for the name | Med | 30 min |
| 6 | Minimal template: too sparse, needs subtle refinement | Low | 15 min |
| 7 | Bold template: good contrast but needs spacing work | Low | 15 min |
| 8 | Receipt template: functional but narrow — could be wider | Low | 15 min |
| 9 | No end-to-end test for PDF generation across all layouts | High | 20 min |
| 10 | No sample PDFs generated for quality review | Med | 10 min |
## Implementation Plan
### Phase 1: Infrastructure Fixes
#### T1. Fix fontconfig cache directory
- **File:** `Dockerfile`
- **Change:** Add `RUN mkdir -p /var/cache/fontconfig && chown appuser:appuser /var/cache/fontconfig`
- **Why:** Eliminates "No writable cache directories" spam on every PDF generation
- **Test:** `docker exec agentforms-relay fc-cache -fv 2>&1 | head -5` — no errors
#### T2. Enhance preview modal with print + better UX
- **File:** `app/templates/documents_dashboard.html`
- **Changes:**
- Add "Print" button to preview toolbar (calls `window.print()` on iframe)
- Add "Open Full Screen" button that opens PDF directly in new tab (`/documents/<id>/preview`)
- The full-screen tab gives browser native toolbar: print, download, email
- Keep modal for quick peek, but make full-screen the primary "work with it" flow
- **Test:** Click preview → verify toolbar has Print + Open Full Screen buttons
### Phase 2: Template Quality Audit
#### T3. Audit and polish each template
**Stripe** — Already strong. Reference quality. Minor tweak: ensure logo section handles empty name gracefully.
**HubSpot** — Strong. Color band header is distinctive. Verify print colors render correctly.
**Notion** — Strong. Sidebar accent, editorial feel. Check long line item descriptions don't overflow.
**Classic** — Needs work:
- Add subtle header band (thin colored line)
- Improve typography hierarchy (document number too small)
- Add border to line items table
- Tighten spacing between sections
**Modern** — Needs work:
- Inconsistent spacing between sections
- Card-style sections need box-shadow for depth
- Totals section needs visual weight (larger font, border)
**Professional** — Needs work:
- Name doesn't match quality — currently looks like a slightly dressed-up Classic
- Needs: colored sidebar accent, larger header, refined typography
- Make this the "corporate" option — think law firm / accounting firm quality
**Minimal** — Needs refinement:
- Too sparse — needs subtle dividers and better whitespace
- Current: almost blank. Target: Apple invoice quality (clean but intentional)
- Add thin horizontal rules, subtle section labels
**Bold** — Minor polish:
- Good high-contrast approach
- Needs: better spacing in line items, tighter totals section
- Verify color contrast passes accessibility
**Receipt** — Functional improvement:
- Currently narrow (receipt-style). Make it wider (letter/A4) but keep compact layout
- Add receipt number prominently
- Add "Thank you" footer
**Customer Portal** — Already strong. Customer-facing design is good. Verify it renders well as PDF.
### Phase 3: Testing
#### T4. End-to-end PDF generation test
- **Script:** `tests/test_document_all_layouts.py`
- Generate one invoice per layout with identical test data
- Save to `/tmp/doc-test-{layout}.pdf`
- Verify each PDF:
- File exists and > 10KB
- Contains expected text (customer name, totals, line items)
- No WeasyPrint errors in stderr
- Renders to A4 page size
#### T5. Generate sample PDFs for quality review
- Generate all 10 layouts with the same test invoice
- Send to Telegram as images (first page) for visual comparison
- Identify which templates need the most work
### Phase 4: Polish
#### T6. Consistency pass
- All templates should have:
- Consistent `@page` rules (A4, proper margins)
- `-webkit-print-color-adjust: exact` for background colors
- Logo support (graceful fallback to initials)
- Watermark support
- Payment link button
- Status badge (Paid/Pending/Overdue/Draft)
- Notes section (hidden when empty)
- Footer with company name
#### T7. Docker rebuild and deploy
- Rebuild with fontconfig fix
- Test PDF generation in running container
- Verify no fontconfig warnings in logs
## Success Criteria
- [ ] Fontconfig warnings eliminated from PDF generation logs
- [ ] Preview modal has Print + Open Full Screen buttons
- [ ] All 10 templates produce professional-looking PDFs
- [ ] End-to-end test passes for all layouts
- [ ] Sample PDFs reviewed and approved
## Estimated Effort
| Phase | Tasks | Time |
|-------|-------|------|
| Phase 1 | T1-T2 | 20 min |
| Phase 2 | T3 | 2-3 hours |
| Phase 3 | T4-T5 | 30 min |
| Phase 4 | T6-T7 | 30 min |
| **Total** | | **~3.5 hours** |