Architecture

Technical architecture documentation for Duckling.

Overview

Duckling is a full-stack web application with a clear separation between frontend and backend:

graph LR
    A[Browser] --> B[React Frontend]
    B --> C[Flask Backend]
    C --> D[Docling Engine]
    D --> E[(Storage)]

    style A fill:#3b82f6,color:#fff
    style B fill:#1e3a5f,color:#fff
    style C fill:#14b8a6,color:#fff
    style D fill:#8b5cf6,color:#fff
    style E fill:#f59e0b,color:#fff

Sections

Key Design Decisions

Separation of Concerns

• Frontend: React with TypeScript for type safety and modern UI
• Backend: Flask for simplicity and Python ecosystem access
• Engine: Docling for document conversion (IBM's library)

Async Processing

Document conversion is handled asynchronously:

1. Client uploads file
2. Server returns job ID immediately
3. Client polls for status
4. Server processes in background thread
5. Results available when complete

Job Queue

A thread-based job queue prevents memory exhaustion:

• Maximum 2 concurrent conversions
• Jobs queued when capacity reached
• Automatic cleanup of completed jobs

Settings Persistence

Settings are stored per-user session and applied per-conversion:

• Global defaults in config.py
• User settings stored in database (per session ID)
• Per-request overrides via API

Settings are isolated per user session, ensuring multi-user deployments don't interfere with each other's preferences.

Technology Stack

Frontend

Backend