SaaS-PDF/docs/feature-editor.md

Feature: Critical Maintenance & Editor Foundation

Branch: feature/critical-maintenance-and-editor

---

Block A — Critical Maintenance (Sprint 1)

A1 — Dynamic Upload Limits (/api/config)

Backend:

• GET /api/config returns plan-aware file-size limits and usage summary.
• Registered as config_bp at /api/config.
• Anonymous users receive free-tier limits; authenticated users receive limits according to their plan plus a usage summary.

Frontend:

• useConfig hook (src/hooks/useConfig.ts) fetches limits from the config endpoint with a fallback to the hardcoded TOOL_LIMITS_MB.
• HeroUploadZone and PdfEditor consume dynamic limits via useConfig.

A2 — Image Resize Tool

Frontend page: src/components/tools/ImageResize.tsx
Route: /tools/image-resize
Backend endpoint: POST /api/image/resize (already existed)

Features:

• Width / height inputs with lock-aspect-ratio toggle.
• Quality slider (1–100, default 85).
• Accepts files from the homepage smart-upload handoff (via fileStore).
• i18n keys added for en, ar, fr.

A3 — SMTP & Forgot / Reset Password

Config keys (set via environment variables):

Variable	Default	Description
SMTP_HOST	""	SMTP server hostname
SMTP_PORT	587	SMTP server port
SMTP_USER	""	SMTP login
SMTP_PASSWORD	""	SMTP password
SMTP_FROM	"noreply@example.com"	Sender address
SMTP_USE_TLS	true	Use STARTTLS
FRONTEND_URL	http://localhost:5173	Used in reset-email link

Endpoints:

Method	Path	Rate limit	Description
POST	/api/auth/forgot-password	5/hour	Sends reset email (always returns 200)
POST	/api/auth/reset-password	10/hour	Consumes token, sets new password

Database tables added:

• password_reset_tokens — stores hashed tokens with 1-hour expiry.
• file_events — audit log for file-lifecycle events (see A4).

Frontend pages:

• /forgot-password — email form
• /reset-password?token=… — new-password form

A4 — Celery Beat Cleanup Task

Task: app.tasks.maintenance_tasks.cleanup_expired_files
Schedule: Every 30 minutes via Celery Beat (crontab(minute="*/30")).
Behaviour: Scans UPLOAD_FOLDER and OUTPUT_FOLDER for sub-directories older than FILE_EXPIRY_SECONDS (default 1800 s). Deletes them and logs a cleanup event to file_events.

Docker: A celery_beat service was added to docker-compose.yml.

---

Feature Flag

Variable	Default	Description
FEATURE_EDITOR	false	Gates Block-B editor features (OCR, Remove BG, PDF Editor). Not used by Block-A features.

---

Test Coverage

File	Tests	Status
test_config.py	3	✅ Passed
test_password_reset.py	8	✅ Passed
test_maintenance_tasks.py	8	✅ Passed
Full suite	158	✅ All passed

---

Files Changed / Created

Backend — New

• app/routes/config.py
• app/services/email_service.py
• app/tasks/maintenance_tasks.py
• tests/test_config.py
• tests/test_password_reset.py
• tests/test_maintenance_tasks.py

Backend — Modified

• app/__init__.py — registered config_bp
• config/__init__.py — SMTP settings, FRONTEND_URL, FEATURE_EDITOR
• app/extensions.py — Celery Beat schedule
• app/routes/auth.py — forgot/reset password endpoints
• app/services/account_service.py — reset-token & file-event helpers, new tables
• celery_worker.py — imports maintenance_tasks

Frontend — New

• src/hooks/useConfig.ts
• src/components/tools/ImageResize.tsx
• src/pages/ForgotPasswordPage.tsx
• src/pages/ResetPasswordPage.tsx

Frontend — Modified

• src/App.tsx — 3 new routes
• src/components/shared/HeroUploadZone.tsx — uses useConfig
• src/components/tools/PdfEditor.tsx — uses useConfig
• src/pages/HomePage.tsx — Image Resize tool card
• src/pages/AccountPage.tsx — "Forgot password?" link
• src/utils/fileRouting.ts — imageResize in tool list

---

Block B — OCR, Background Removal, PDF Editor (Sprint 2)

All Block B routes are gated behind FEATURE_EDITOR=true. Returns 403 when disabled.

B1 — OCR (Optical Character Recognition)

Backend:

• Service: app/services/ocr_service.py — ocr_image(), ocr_pdf() using pytesseract
• Tasks: app/tasks/ocr_tasks.py — ocr_image_task, ocr_pdf_task
• Route: app/routes/ocr.py — Blueprint ocr_bp at /api/ocr

Method	Path	Rate limit	Description
POST	/api/ocr/image	10/min	Extract text from image
POST	/api/ocr/pdf	5/min	Extract text from scanned PDF
GET	/api/ocr/languages	—	List supported OCR languages

Supported languages: English (eng), Arabic (ara), French (fra).

Frontend: src/components/tools/OcrTool.tsx — /tools/ocr

• Mode selector (Image / PDF), language selector, text preview with copy, download.

B2 — Background Removal

Backend:

• Service: app/services/removebg_service.py — remove_background() using rembg + onnxruntime
• Task: app/tasks/removebg_tasks.py — remove_bg_task
• Route: app/routes/removebg.py — Blueprint removebg_bp at /api/remove-bg

Method	Path	Rate limit	Description
POST	/api/remove-bg	5/min	Remove background (outputs transparent PNG)

Frontend: src/components/tools/RemoveBackground.tsx — /tools/remove-background

• Upload image → AI processing → download PNG with transparency.

B3 — PDF Editor (Text Annotations)

Backend:

• Service: app/services/pdf_editor_service.py — apply_pdf_edits() using ReportLab overlay + PyPDF2
• Task: app/tasks/pdf_editor_tasks.py — edit_pdf_task
• Route: app/routes/pdf_editor.py — Blueprint pdf_editor_bp at /api/pdf-editor

Method	Path	Rate limit	Description
POST	/api/pdf-editor/edit	10/min	Apply text annotations to PDF

Accepts file (PDF) + edits (JSON array, max 500). Each edit: { type, page, x, y, content, fontSize, color }.

DevOps Changes

Dependencies added (requirements.txt):

• pytesseract>=0.3.10,<1.0
• rembg>=2.0,<3.0
• onnxruntime>=1.16,<2.0

Dockerfile: Added tesseract-ocr, tesseract-ocr-eng, tesseract-ocr-ara, tesseract-ocr-fra to apt-get.

Celery task routing (extensions.py):

• ocr_tasks.* → image queue
• removebg_tasks.* → image queue
• pdf_editor_tasks.* → pdf_tools queue

Block B Test Coverage

File	Tests	Status
test_ocr.py	8	✅ Passed
test_removebg.py	3	✅ Passed
test_pdf_editor.py	7	✅ Passed
test_ocr_service.py	4	✅ Passed
Full suite	180	✅ All passed

Block B Files Created

Backend — New:

• app/services/ocr_service.py
• app/services/removebg_service.py
• app/services/pdf_editor_service.py
• app/tasks/ocr_tasks.py
• app/tasks/removebg_tasks.py
• app/tasks/pdf_editor_tasks.py
• app/routes/ocr.py
• app/routes/removebg.py
• app/routes/pdf_editor.py
• tests/test_ocr.py
• tests/test_removebg.py
• tests/test_pdf_editor.py
• tests/test_ocr_service.py

Frontend — New:

• src/components/tools/OcrTool.tsx
• src/components/tools/RemoveBackground.tsx

Backend — Modified:

• app/__init__.py — registered 3 new blueprints (18 total)
• app/extensions.py — 3 new task routing rules
• celery_worker.py — 3 new task module imports
• requirements.txt — pytesseract, rembg, onnxruntime
• Dockerfile — tesseract-ocr packages

Frontend — Modified:

• src/App.tsx — 2 new lazy routes (/tools/ocr, /tools/remove-background)
• src/pages/HomePage.tsx — OCR + RemoveBG tool cards
• src/utils/fileRouting.ts — OCR + RemoveBG in tool arrays
• src/i18n/en.json — tools.ocr + tools.removeBg keys
• src/i18n/ar.json — Arabic translations
• src/i18n/fr.json — French translations
• src/services/api.ts — text + char_count added to TaskResult
• src/i18n/en.json, ar.json, fr.json — new keys

Infrastructure

• docker-compose.yml — celery_beat service