┌─────────────────────────────────────────┐
│ User's Browser (http://localhost:5000)|
│ │
│ ┌─────────────────────────────────┐ │
│ │ 📓 Notebook to PDF Converter │ │
│ │ │ │
│ │ 📁 [Drag files here] │ │
│ │ │ │
│ │ [Convert to PDF Button] │ │
│ │ │ │
│ │ [Progress Bar] │ │
│ │ │ │
│ │ ✅ PDF Ready to Download │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
↕️ (HTTPS/HTTP)
┌─────────────────────────────────────────┐
│ Flask Backend (Port 5000) │
│ │
│ GET / → Serve UI │
│ POST /api/convert → Convert │
│ GET /api/health → Check status │
│ │
│ ┌──────────────────────────────┐ │
│ │ File Validation │ │
│ │ ├─ Check file type (.ipynb) │ │
│ │ ├─ Check file size (50MB) │ │
│ │ └─ Validate content │ │
│ └──────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────┐ │
│ │ nbconvert Library │ │
│ │ ├─ Parse notebook │ │
│ │ ├─ Process content │ │
│ │ └─ Generate intermediate │ │
│ └──────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────┐ │
│ │ Pandoc (System Binary) │ │
│ │ ├─ Convert to LaTeX │ │
│ │ ├─ Render PDF │ │
│ │ └─ Optimize output │ │
│ └──────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────┐ │
│ │ Return PDF File │ │
│ │ ├─ Set headers │ │
│ │ ├─ Stream download │ │
│ │ └─ Clean up temp files │ │
│ └──────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
USER JOURNEY FLOW
1. DISCOVERY
└─ User opens http://localhost:5000
├─ Sees beautiful purple/blue UI
├─ Notices upload area
└─ Reads instructions
2. UPLOAD
└─ User uploads .ipynb file (2 ways)
├─ Click and select file
└─ Drag and drop file
├─ Frontend validates file
├─ Shows file info
└─ Enables Convert button
3. CONVERSION
└─ User clicks "Convert to PDF"
├─ Shows progress bar
├─ Starts conversion process
├─ Backend validates file
├─ nbconvert processes notebook
├─ Pandoc generates PDF
└─ Progress reaches 100%
4. DOWNLOAD
└─ PDF automatically downloads
├─ Browser shows download
├─ User opens PDF
└─ Success message shows
5. REPEAT
└─ User can convert more files
CONVERSION PIPELINE
Input: notebook.ipynb (JSON file)
│
├─ Received by Flask
│
├─ Security Checks
│ ├─ File extension: .ipynb ✓
│ ├─ File size: < 50MB ✓
│ └─ File format: Valid JSON ✓
│
├─ Saved to temp folder
│
├─ nbconvert Processing
│ ├─ Parse notebook structure
│ ├─ Extract markdown cells
│ ├─ Extract code cells
│ ├─ Process output data
│ └─ Generate LaTeX intermediate
│
├─ Pandoc Processing
│ ├─ Read LaTeX input
│ ├─ Apply formatting
│ ├─ Render fonts & styles
│ ├─ Create PDF layout
│ └─ Optimize file size
│
├─ Cleanup
│ ├─ Remove temp notebook
│ └─ Keep only PDF
│
└─ Output: notebook.pdf (Binary file)
└─ Sent to browser
└─ Downloaded by user
APPLICATION LAYERS
┌──────────────────────────────────┐
│ PRESENTATION LAYER │
│ ├─ HTML Structure │
│ ├─ CSS Styling (Gradients) │
│ └─ JavaScript (Interactions) │
│ 📄 templates/index.html │
└──────────────────────────────────┘
↕️ JSON/HTTP
┌──────────────────────────────────┐
│ API LAYER │
│ ├─ Flask Routes │
│ ├─ Request Handling │
│ ├─ Response Generation │
│ └─ Error Management │
│ 🐍 app.py (Backend) │
└──────────────────────────────────┘
↕️ File I/O
┌──────────────────────────────────┐
│ PROCESSING LAYER │
│ ├─ File Validation │
│ ├─ nbconvert Integration │
│ ├─ Pandoc Execution │
│ └─ Output Generation │
│ 📦 External Libraries │
└──────────────────────────────────┘
↕️ System Calls
┌──────────────────────────────────┐
│ SYSTEM LAYER │
│ ├─ File System │
│ ├─ Process Management │
│ └─ Binary Execution │
│ 🖥️ Operating System │
└──────────────────────────────────┘
FEATURE OVERVIEW
┌─────────────────────────────────────┐
│ DRAG & DROP UPLOAD │
│ │
│ 📁 Click or drag files here │
│ ───────────────────────────── │
│ When hovering: Highlight ✨ │
│ Show file info: Name & Size │
│ Validation feedback │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ FILE VALIDATION │
│ │
│ ✓ File type check (.ipynb) │
│ ✓ File size check (50MB max) │
│ ✓ Show errors if invalid │
│ ✓ Enable/disable buttons │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ REAL-TIME PROGRESS │
│ │
│ 30% - Starting conversion │
│ 70% - Processing content │
│ 100% - PDF ready! │
│ ▓▓▓▓▓░░░░░░░░░░░░░░░░ Progress │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ AUTO DOWNLOAD │
│ │
│ ✅ PDF auto-downloads to device │
│ ✅ Temp files auto-cleaned │
│ ✅ Success message shown │
│ ✅ Form resets for next file │
└─────────────────────────────────────┘
SECURITY MEASURES
User File Upload
↓
┌───────────────────┐
│ VALIDATION LAYER │
├───────────────────┤
│ Check Extension │ → ❌ Not .ipynb? Reject
│ (Only .ipynb) │ → ✅ Is .ipynb? Continue
└───────────────────┘
↓
┌───────────────────┐
│ SIZE CHECK │
├───────────────────┤
│ Check file size │ → ❌ > 50MB? Reject
│ (Max 50MB) │ → ✅ < 50MB? Continue
└───────────────────┘
↓
┌───────────────────┐
│ FILENAME HANDLER │
├───────────────────┤
│ Sanitize name │ ✓ Remove path traversal
│ (werkzeug) │ ✓ Remove special chars
│ │ ✓ Prevent injection
└───────────────────┘
↓
┌───────────────────┐
│ TEMP FILE MGMT │
├───────────────────┤
│ Save to temp │ ✓ Isolated location
│ Process safely │ ✓ No write to app dir
│ Delete after use │ ✓ Auto cleanup
└───────────────────┘
↓
✅ Safe PDF Output
READY FOR MULTIPLE DEPLOYMENT OPTIONS
LOCAL DEVELOPMENT:
python app.py
↓
Runs on http://localhost:5000
Perfect for testing
DOCKER CONTAINER:
docker build . -t notebook-converter
docker run -p 5000:5000 notebook-converter
↓
Containerized, portable
CLOUD DEPLOYMENT:
AWS EC2 / Heroku / DigitalOcean
↓
Scalable, production-ready
VPS HOSTING:
nginx + gunicorn + app.py
↓
Professional setup
EXPECTED PERFORMANCE
File Size Processing Time Output Size
──────────────────────────────────────────
1 MB 1-2 seconds 0.8 MB
5 MB 3-5 seconds 4.2 MB
10 MB 5-8 seconds 8.5 MB
25 MB 10-15 seconds 22 MB
50 MB 20-30 seconds 45 MB
(Actual times vary based on notebook content)
RESOURCE USAGE:
• Memory: ~50-100 MB per conversion
• Disk: Temp files auto-cleaned
• CPU: 100% during conversion (brief)
WHAT USERS SEE
┌─────────────────────────────────────────┐
│ │
│ 📓 Notebook to PDF │
│ Convert Jupyter Notebooks Instantly │
│ │
│ ┌─────────────────────────────────┐ │
│ │ │ │
│ │ 📁 Click or drag to upload │ │
│ │ .ipynb files (max 50MB) │ │
│ │ │ │
│ └─────────────────────────────────┘ │
│ │
│ [CONVERT TO PDF] (Disabled initially) │
│ │
│ ════════════════════════════════════ │
│ ✓ Fast & Secure conversion │
│ ✓ Supports all notebook content │
│ ✓ No file size limits hassle │
│ ✓ High-quality PDF output │
│ │
└─────────────────────────────────────────┘
PROJECT COMPLETION CHECKLIST
✅ Backend
├─ Flask server running
├─ API endpoints working
├─ File handling secure
└─ Error handling proper
✅ Frontend
├─ UI displaying correctly
├─ Drag & drop working
├─ Progress tracking visible
└─ Downloads functioning
✅ Conversion
├─ nbconvert processing files
├─ Pandoc generating PDFs
├─ Output files valid
└─ Performance acceptable
✅ Documentation
├─ Setup guide complete
├─ API documented
├─ Troubleshooting guide included
└─ Code well commented
✅ Testing
├─ Sample file converts successfully
├─ Error handling tested
├─ File validation verified
└─ UI responsive on mobile
YOUR JOURNEY
NOW: Ready to Use ✅
├─ Code complete
├─ Docs complete
└─ Project ready
PHASE 1: Get It Running
├─ pip install -r requirements.txt
├─ python app.py
└─ Open http://localhost:5000
PHASE 2: Test It
├─ Upload sample_notebook.ipynb
├─ Convert to PDF
└─ Verify output
PHASE 3: Customize (Optional)
├─ Modify UI colors
├─ Change port number
├─ Adjust file size limit
└─ Add custom features
PHASE 4: Deploy (Optional)
├─ Docker containerization
├─ Cloud deployment
└─ Setup CI/CD
PHASE 5: Monitor & Maintain
├─ Track usage
├─ Update dependencies
└─ Collect feedback
Ready to start? See START_HERE.md or QUICK_START.md!