The Engineering Principle of Ephemeral Storage
Document conversion and structured text extraction do not require permanent data archiving. Once a user uploads a file and downloads the converted result, the server copy has fulfilled its operational function.
Rather than storing customer files in permanent cloud buckets or database records, PDFparse writes all incoming uploads to a local temporary server directory configured for automated cleanup. This design ensures that processing infrastructure handles files ephemerally, eliminating long-term data custody.
Temporary Directory and Unique UUID File Paths
When a document upload arrives at the application backend, the storage service generates a dedicated file path within a temporary scratch directory. As defined in system configuration (settings.temp_dir), this scratch storage is hosted at a designated filesystem path (by default, /tmp/converted).
To prevent namespace collisions and separate concurrent user uploads, each incoming file is assigned a randomized UUID (Universally Unique Identifier) version 4 string. The storage handler combines this unique identifier with the sanitized base name of the uploaded document and the target extension.
For example, an uploaded document titled 'lease_agreement.pdf' is written to the temporary directory under a filename such as 'a8b1c2d3-e4f5-4a7b-8c9d-0e1f2a3b4c5d_lease_agreement.pdf'. By prefixing each upload with a unique UUID, concurrent processing jobs do not collide or overwrite one another on disk.
The 2-Hour Retention Window and Unlink Deletion
Every uploaded file and generated conversion artifact is governed by a strict retention threshold: system configuration (settings.file_retention_hours) enforces a maximum retention window of 2 hours. This duration provides users with an adequate operational window to download converted spreadsheets, document summaries, or merged files, even over slower network connections.
When an expired file is identified, the storage service invokes a safe unlinking operation (file_path.unlink()) directly on the filesystem path. If an unexpected filesystem lock or transient access event occurs, the exception is safely caught and logged while allowing the cleanup sweep to continue across remaining files. The cleanup routine records the exact number of deleted files upon completing each sweep.
Automated Cleanup Loop Running Every 10 Minutes
Automated deletion is executed by a background cleanup loop running continuously within the application lifecycle. At server startup and at recurring 10-minute intervals (every 600 seconds), the cleanup service inspects the temporary storage directory.
During each sweep, the cleanup routine calculates a strict cutoff threshold by subtracting the 2-hour retention interval from the current system timestamp (cutoff_time = datetime.now() - timedelta(hours=2)).
The routine iterates through each file in the temporary directory and inspects its filesystem modification timestamp (st_mtime). Any file whose modification timestamp is older than the 2-hour cutoff threshold is immediately unlinked and removed from disk.
The cleanup loop is launched at application startup as an asynchronous background worker and repeats every 600 seconds until server shutdown, ensuring that expired files are purged reliably.
Operational Boundaries and Expired Download Links
Because all files are automatically removed after 2 hours, download links provided to users are time-limited. Users should download their converted Excel workbooks, Word documents, or JSON records immediately upon job completion.
If a user attempts to access a download link after the 2-hour retention window has elapsed, the server returns a 404 Not Found response because the underlying filesystem artifact has been unlinked. This automated lifecycle ensures deterministic data disposal without requiring manual administrative intervention.
Key Takeaway
By combining randomized UUID file naming, dedicated temporary storage directories, a 2-hour retention limit, and an automated unlinking loop running every 10 minutes, PDFparse ensures uploaded documents are deleted deterministically from our servers.