How gauravm512/docuflex works
Read the file tree as architecture signals
Top-level cues from the tree:
• main.py → app bootstrap; includes FastAPI instance, mounts static, includes routers, template engine setup
• routes/ → API/controller layer (FastAPI routers): convert.py, pdf_utils.py, ocr.py, qr.py
• services/ → business logic layer: convert_service.py, pdf_service.py, ocr_service.py, plus file_utils.py for validation/storage/cleanup
• templates/ + static/ → server-rendered UI + JS-enhanced upload/download behavior
• routes/pdf_utils.py and services/pdf_service.py indicate PDF ops are separated from “conversion”
• routes/qr.py exists but README says QR is frontend-only at /qr → route likely serves the page; generation logic is in static/app.js or template JS
• requirements.txt / pyproject.toml → Python packaging + dependencies (PyMuPDF, Pillow, pdf2docx, pytesseract)
This structure strongly suggests a clean 3-layer separation:
UI (templates/static) → Routes (FastAPI routers) → Services (processing + file utils)
Use the README to anchor “truth”
• “Stateless processing” (no DB)
• “Temporary local storage during processing” (uploads/outputs) then delete
• “Client submits files using HTML/JS”
• “Service layer performs processing using PyMuPDF, Pillow, OCR”
• “Output returned as download response”
• “QR codes generated directly in the browser using JavaScript”
• Security: size limits, type validation, UUID filenames, auto-cleanup
Browser POST /ocr/pdf with UploadFile
2. routes/ocr.py → file_utils.validate() + file_utils.save_upload() → writes to uploads/uuid.pdf
ocr_service.ocr_pdf()
• uses PyMuPDF to render pages → temp images
• calls pytesseract/Tesseract per page → aggregated text
file_utils.cleanup() deletes temp input/output
Flow example: PDF Merge
Return output → cleanup
Flow example: QR generation
Browser JS generates QR locally (no backend processing)
These flows make the “no DB, ephemeral filesystem” design unmissable.
Main components to include (separate into as many as possible)
• Browser UI
• HTML pages (templates)
• JS upload/download logic (static/app.js)
• QR generator (client-side)
• FastAPI Application
• Router: Convert
• Router: PDF Utils
• Router: OCR
• Router: QR page
• Service modules
• Convert Service
• PDF Service
• OCR Service
• File Utils (validation + storage + cleanup) *(this is a key shared component)*
• Temp Storage
• uploads/
• outputs/
• External/native dependencies
• Tesseract OCR binary
• Browser → FastAPI: GET / pages, POST /convert/* uploads, POST /pdf/*, POST /ocr/*
• FastAPI Routes → file_utils: validate type/size, generate UUID filename, save/delete
• Routes → Services: invoke processing functions
• Services → Temp Storage: read input, write output
• OCR Service → Tesseract: OCR invocation
• FastAPI → Browser: download response (FileResponse/StreamingResponse)
• validation failure → HTTP 400/415
• size limit exceeded → HTTP 413
• OCR engine missing → HTTP 500 with message (or explicit “dependency not installed”)
Architectural patterns/design principles to highlight (project-specific)
• Stateless request processing (no persistence, no sessions)
• Layered architecture: Routes/Controllers vs Services vs Utilities
• Shared cross-cutting concern: file_utils for security + cleanup
• Privacy-by-design: temp-only storage + deletion
• Client-side feature isolation: QR generation entirely in browser (reduced server load/security surface)
Diagramming conventions (make it principal-engineer grade)
Include:
• Clear labels: endpoint groups, modules, and responsibilities
• Blue: UI (Browser, templates, static)
• Green: FastAPI routes/controllers
• Orange: Services/business logic
• Purple: external dependencies (Tesseract)
• Trust boundaries:
• “Client machine” vs “Server runtime”
• Optionally “Container boundary” if Docker deployment is used