docling-studio/docs/design/195-copy-paste-image-verify-mode.md

Design: Copy paste image in Verify mode

• Issue: #195
• Title on issue: [ENHANCEMENT] Copy paste image in Verify mode
• Author: Pier-Jean Malandrino
• Date: 2026-04-23
• Status: Accepted
• Target milestone: 0.5.0
• Impacted layers: <backend: domain | api | services | persistence | infra> · <frontend: features/ | shared | app> · · <infra/CI>
• Audit dimensions likely touched: <pick from: Hexagonal Architecture · DDD · Clean Code · KISS · DRY · SOLID · Decoupling · Security · Tests · CI/Build · Documentation · Performance>
• ADR spawned?: (write an ADR when choosing a library, moving a boundary, or deciding not to do something — see docs/architecture/adr-guide.md)

---

1. Problem

TODO: Why this issue exists. Link the user story, incident, or upstream discussion that motivates it.

Today in Verify mode regarding image handling: TODO — describe the current baseline (upload-only? no paste target? no drag-drop?).

2. Goals

Users should be able to copy/paste images directly into Verify mode (e.g. from clipboard) instead of only via file upload.

• Define paste source (OS clipboard, drag-drop, screenshot)
• Define target area in Verify mode UI
• Define supported image formats and size limits
• Size / type limits are env-var configurable, carry sane defaults, and are documented in README.md + docs/deployment/* (e.g. MAX_PASTE_IMAGE_SIZE_MB, PASTE_ALLOWED_IMAGE_TYPES)

3. Non-goals

• ...
• ...

4. Context & constraints

SQLite & storage limits (must be enforced upstream of the DB)

Pasted images follow the existing documents pattern: bytes land on disk under UPLOAD_DIR, the row stores storage_path: TEXT. We do not store base64 or BLOBs. Even so, app-level size guards must stay below SQLite's structural limits so a malformed request can never wedge the engine.

Relevant SQLite defaults (see https://www.sqlite.org/limits.html):

SQLite limit	Default	Relevance
SQLITE_MAX_LENGTH	1 GB (1 × 10⁹ bytes)	Max size of any single TEXT / BLOB cell. Irrelevant as long as we keep bytes off the DB.
SQLITE_MAX_SQL_LENGTH	1 MB	Max length of an SQL statement incl. inlined literals. Always use parameter binding — never inline image bytes.
Page cache / WAL growth	n/a	Large writes bloat WAL until checkpoint; another reason to stay off-DB.

Our own app-level limits guard against ever reaching those ceilings. All such limits must: (1) carry a sane default in infra/settings.py, (2) be overridable via env var, (3) be documented in README.md and docs/deployment/*. This is consistent with how MAX_FILE_SIZE_MB (default 50) is handled today.

5. Proposed design

5.1 Domain

5.2 Persistence

5.3 Infra adapters

Extend document-parser/infra/settings.py with paste-specific limits. Follow the existing MAX_FILE_SIZE_MB pattern: typed field on the settings dataclass, os.environ.get(...) with a string default, cast at load time.

Setting	Env var	Default	Allowed	Notes
max_paste_image_size_mb	MAX_PASTE_IMAGE_SIZE_MB	10	positive int, 0 = unlimited	Must be ≤ MAX_FILE_SIZE_MB; upload validator rejects larger payloads before any DB write.
paste_allowed_image_types	PASTE_ALLOWED_IMAGE_TYPES	image/png,image/jpeg,image/webp	comma-separated MIME list	Enforced server-side; frontend uses the same list via /api/health.

Validation happens in the API layer (upload handler) before the bytes reach persistence. Any future move to BLOB storage would still rely on these guards — they are the contract that prevents us ever approaching SQLITE_MAX_LENGTH.

5.4 Services

5.5 API

5.6 Frontend — feature module

5.7 Cross-cutting (feature flags, i18n, shared types)

6. Alternatives considered

Alternative A —

• Summary:
• Why not:

Alternative B —

• Summary:
• Why not:

7. API & data contract

8. Risks & mitigations

Risk	Audit dimension	Likelihood	Impact	How we notice	Mitigation / rollback

9. Testing strategy

10. Rollout & observability

11. Open questions

• ...
• ...

12. References

• Issue: https://github.com/scub-france/Docling-Studio/issues/195
• Related PRs / commits:
• ADRs: <ADR-NNN or "none planned">
• Project docs:
  • Architecture: docs/architecture.md
  • Coding standards: docs/architecture/coding-standards.md
  • ADR guide / template: docs/architecture/adr-guide.md, docs/architecture/adr-template.md
  • Audit master: docs/audit/master.md
  • E2E conventions: e2e/CONVENTIONS.md
• External: <specs, upstream issues, dashboards, third-party docs>