# 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** |