# openprinting/cups architecture

> Architecture diagram of the GitHub repository openprinting/cups, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openprinting/cups
- Repository: https://github.com/openprinting/cups

## Overview

##### Project Type and Purpose
- CUPS is a modular, daemon-based printing system (not a traditional “frontend/backend web app”).
- Purpose: Provide IPP-based printing services via a central scheduler (cupsd), C API (libcups), CLI tools (“lp”, “lpadmin”, “lpr”), a web/CGI admin interface, filter pipeline, backends for device I/O, and support for PPD and IPP-Everywhere.

##### File Structure
- Top-level modules/directories map to major components:
– scheduler/         → cups daemon (cupsd), request processing, job scheduling, policy, network listener
– cups/              → core library (libcups), IPP/HTTP protocol, JSON, TLS, authentication
– backend/           → device backends (USB, IPP, LPD, socket, pseudo, dnssd)
– filter/            → filter pipeline (PostScript→raster, raster conversions, gzip handling)
– cgi-bin/           → web interface CGI programs, templates under templates/
– ppdc/              → PPD compiler (ppdc) for legacy drivers
– monitor/, notifier/→ event/notification subsystems (RSS, mailto, DBus)
– tools/, examples/, test/, doc/ → CLI utilities, example jobs, tests, and documentation
- Configuration files (conf/, cups-files.conf, cupsd.conf.in) define runtime behavior.
- Packaging, systemv, vcnet, xcode support various platforms.

##### README for Insights
- Confirms the components above and the protocols used (IPP, HTTP, DNS-SD).
- Mentions command-line interfaces, C API, web admin UI, filters, drivers, backends.

##### Main Components
a. Clients
– CLI Tools (“lp”, “lpr”, “lpadmin”, “ippfind”, “ipptool”)
– Applications linking against libcups (C API)
– Web-admin UI (served via CGI programs + HTML templates under templates/)
b. Core Service
– cups daemon (cupsd) listens on port 631 (HTTP/IPP)
– Authentication & authorization (PAM, certs)
– Job scheduler, policy engine, logging
c. Plugin Subsystems
– Filter pipeline (chain of filter modules) for format conversion
– Backends for transport to device or network (USB, IPP, LPD, socket)
– PPD compiler (ppdc) for parsing/merging PostScript Printer Descriptions
– Notifier and Monitor for events (email, DBus, RSS)
d. Data & Configuration
– PPD files, MIME database, printers.conf, classes.conf
– Locales under locale/, documentation under doc/
e. External Services/Devices
– Printers (USB-attached or networked via IPP or LPD)
– DNS-SD/Bonjour for auto-discovery
– SNMP supply status queries

##### Relationships & Interactions
– cupsd → filter modules (stdin/stdout pipelines)
– filter modules → backends (pipes or exec)
– backends → physical printer or network URI
– cupsd ↔ ppdc (when generating/compiling PPDs)
– cupsd → notifier/monitor (on job events)
– External discovery (cupsd ↔ DNS-SD subsystem)

##### Architectural Patterns & Principles
- Client-server (daemon) with API (libcups)
- Plugin architecture: filters & backends loaded per job
- Pipeline pattern: sequential filter processing
- Microkernel-like core (cupsd) + loadable modules
- Separation of configuration, code, locale, docs, tests

##### Technologies & Frameworks to Annotate
– C (ANSI C) and C++ (ppdc) code
– HTTP/IPPS (port 631), IPP protocol
– PAM, GnuTLS/OpenSSL for auth/TLS
– JSON support, LDAP/SNMP for supplies
– CGI (web UI), HTML templates, gettext (locale)
– Makefiles, autoconf, Docker container support

##### Essential Elements
– Clear labels for all components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        CLI["CLI Tools"]:::clients
        API["Applications (libcups API)"]:::clients
        WebUI["Web Admin UI (CGI)"]:::clients
        Templates["Web UI Templates"]:::data
    end

    %% Core Daemon Layer
    subgraph "Core Daemon" 
        direction TB
        Daemon["cupsd Scheduler & Core Service"]:::core
        LibCups["Core Library (libcups)"]:::core
    end

    %% Plugin Subsystems
    subgraph "Plugin Subsystems" 
        direction TB
        Filter["Filter Pipeline"]:::plugins
        Backend["Backends"]:::plugins
        PPDC["PPD Compiler (ppdc)"]:::plugins
        Monitor["Monitor Subsystem"]:::plugins
        Notifier["Notifier Subsystem"]:::plugins
    end

    %% Data & Configuration
    subgraph "Data & Configuration" 
        direction TB
        Conf["Configuration Files"]:::config
        DataDB["Data & PPD Database"]:::config
        Locale["Localization"]:::config
        Doc["Documentation"]:::config
    end

    %% Examples, Tests, Packaging
    subgraph "Utilities & Support"
        direction TB
        Examples["Example Jobs & Drivers"]:::config
        Tests["Test Suites"]:::config
        Packaging["Packaging & Platform Support"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        DNS["DNS-SD / Bonjour"]:::external
        Printers["Printers (USB/Network)"]:::external
        SNMP["SNMP Supervisors"]:::external
    end

    %% Connections
    CLI -->|HTTP/Unix Socket| Daemon
    API -->|libcups API| Daemon
    WebUI -->|HTTP/CGI| Daemon
    Daemon -->|loads| LibCups

    Daemon -->|spawns STDIN→STDOUT| Filter
    Filter -->|pipes| Backend
    Daemon -->|invokes| PPDC
    Daemon -->|notifies| Monitor
    Daemon -->|sends events| Notifier

    Daemon -->|reads/writes| Conf
    Daemon -->|reads| DataDB
    Daemon -->|uses| Locale
    Daemon -->|references| Doc

    Packaging -->|builds| Daemon
    Tests -->|tests| Daemon
    Examples -->|provides| Filter

    Daemon -->|DNS-SD API| DNS
    Backend -->|USB, IPP, LPD| Printers
    Daemon -->|SNMP Queries| SNMP

    %% Click Events
    click Daemon "https://github.com/openprinting/cups/tree/master/scheduler/"
    click LibCups "https://github.com/openprinting/cups/tree/master/cups/"
    click Backend "https://github.com/openprinting/cups/tree/master/backend/"
    click Filter "https://github.com/openprinting/cups/tree/master/filter/"
    click WebUI "https://github.com/openprinting/cups/tree/master/cgi-bin/"
    click Templates "https://github.com/openprinting/cups/tree/master/templates/"
    click PPDC "https://github.com/openprinting/cups/tree/master/ppdc/"
    click Monitor "https://github.com/openprinting/cups/tree/master/monitor/"
    click Notifier "https://github.com/openprinting/cups/tree/master/notifier/"
    click CLI "https://github.com/openprinting/cups/tree/master/berkeley/"
    click CLI "https://github.com/openprinting/cups/tree/master/systemv/"
    click CLI "https://github.com/openprinting/cups/tree/master/tools/"
    click Conf "https://github.com/openprinting/cups/tree/master/conf/"
    click DataDB "https://github.com/openprinting/cups/tree/master/data/"
    click Locale "https://github.com/openprinting/cups/tree/master/locale/"
    click Doc "https://github.com/openprinting/cups/tree/master/doc/"
    click Examples "https://github.com/openprinting/cups/tree/master/examples/"
    click Tests "https://github.com/openprinting/cups/tree/master/test/"
    click Packaging "https://github.com/openprinting/cups/tree/master/packaging/"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#006064
    classDef plugins fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20
    classDef config fill:#fff3e0,stroke:#e65100,color:#e65100
    classDef clients fill:#f3e5f5,stroke:#4a148c,color:#4a148c
    classDef data fill:#fff8e1,stroke:#ff8f00,color:#ff8f00
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f
```
