Document Conversion Service
An API-driven document workflow for uploading files, processing conversions in the background, tracking status, and retrieving completed results.
What I delivered
- → Implemented file upload, status, and result retrieval APIs
- → Designed the persistent conversion-job lifecycle
- → Built background processing outside the request path
- → Added retries, failure handling, cancellation, and stale-job recovery
- → Implemented document and spreadsheet conversion providers
- → Added real-time completion notifications
- → Managed temporary files, working directories, and cleanup
- → Structured the service with clear application and provider boundaries
A backend service that accepted business documents, created persistent processing jobs, converted files asynchronously, and allowed clients to track progress and retrieve completed results.
The service was designed around a platform-specific conversion dependency that could not safely run as ordinary parallel request code.
The problem
Users needed to submit files for conversion without keeping the original API request open for the entire operation.
Conversions could take time, fail, or be interrupted. The underlying document-processing technology also introduced operating-system and concurrency constraints that had to be handled explicitly.
The system therefore needed durable job state, background execution, recovery behavior, and a clear separation between file submission and result retrieval.
Solution
I designed the conversion workflow as a persistent asynchronous job pipeline.
The API accepted a file, validated the request, and created a job record. A background worker claimed pending jobs and executed the conversion outside the request lifecycle.
Job states recorded progress, completion, failure, cancellation, and retry history. Clients could poll the status API or receive a real-time notification when processing completed.
The platform-specific conversion component was isolated behind a provider boundary so its limitations did not spread through the rest of the application:
How it fits together
The API, application logic, persistence, background host, and conversion providers were separated into clear architectural boundaries.
Key features
Technical challenges
The main challenge was safely coordinating long-running file processing around a platform-specific dependency with limited concurrency support.
The conversion operation could not be treated as a normal stateless API call. It required isolated execution, controlled job claiming, reliable state transitions, cleanup, and recovery when processing stopped unexpectedly.
File-system management was another important concern because uploads, temporary files, converted outputs, and failed jobs all required predictable lifecycle rules.
Outcome
The service separated document submission from long-running processing and gave clients a reliable way to monitor and retrieve conversion results.
Its architecture made the platform-specific dependency manageable while keeping the surrounding API, persistence, job management, and notification layers maintainable and extensible.
Need reliable async processing?
Tell me about the workflow you want to move off the request path.