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 in JSON and applied per-conversion:

• Global defaults in config.py
• User settings in user_settings.json
• Per-request overrides via API

Technology Stack¶

Frontend¶

Backend¶