Evidence repository for the SuperDocs open task “The integration postmortem.”
This repository contains the defect log, supporting product report, and source Markdown behind my published engineering postmortem:
Five Integration Failures I Hit While Building on SuperDocs
The article documents five real integration problems encountered while building document workflows on SuperDocs, including the observed behavior, root cause, fix, and verification for each.
The goal of the task was not to write a successful API tutorial.
It was to document the parts that required actual debugging judgment:
what I misunderstood
→ what failed
→ why it failed
→ what fixed it
→ how I proved the fix
→ what the next developer should know
The findings come from real implementation work across two SuperDocs-based projects:
- Closing Document Reconciliation — document upload, extraction, reconciliation, approval-gated editing, and DOCX export.
- PaperForge — multi-document research synthesis with a controlled SuperDocs human-review workflow.
This repository is supporting evidence for the published article. The public DEV article is the primary open-task submission artifact.
A live pending_changes object contained valid review fields plus additional provider-owned diagnostics.
My first implementation validated the complete provider object directly against a strict application model using extra="forbid".
Root cause: I treated the provider response model and my persisted domain model as the same contract.
Fix: project provider responses onto the fields PaperForge owns, then validate that smaller internal contract strictly.
A SuperDocs async job can already exist even when the local HTTP request does not finish successfully.
Restarting the workflow blindly could create duplicate provider work.
Root cause: I treated local request failure as proof that the external side effect had not occurred.
Fix: persist the provider job_id and recover/poll that exact job on retry instead of starting another one.
Per-change approval decisions looked semantically sufficient, but the working approval request also required an envelope-level approved value.
Root cause: I inferred the write contract from the shape of the pending-change response.
Fix: keep exact SuperDocs request construction inside the provider adapter instead of reconstructing it throughout application code.
A small semantic edit could still contain a large amount of surrounding HTML.
Displaying the provider representation directly made the approval UI harder to inspect.
Root cause: I assumed a correct provider representation was automatically a good human presentation model.
Fix: preserve the full provider proposal but derive a separate text-only, bounded Before/After window for human review.
Provider completion and a successful export prove workflow and transport success, but the consuming application may still need stronger evidence before claiming the reviewed artifact is ready.
Root cause: I defined application-level success too early.
Fix: inspect the exported DOCX independently and verify the narrow semantic property PaperForge promises:
- approved create/edit text must be present;
- approved deleted text must be absent.
Only then is the final reviewed DOCX exposed as available.
I deliberately distinguish between:
- SuperDocs API-contract details I misunderstood, and
- defects in my own application assumptions around the integration.
I do not classify every item as a SuperDocs product bug.
The defect log only includes issues for which I could point to implementation evidence, a regression test, a real workflow, or preserved code showing the resulting fix.
No hypothetical failure was promoted into the primary five simply because it made a better story.
superdocs-integration-postmortem/
│
├── README.md
│ └── Overview and evidence map
│
├── defect-log.md
│ └── Detailed engineering defect log:
│ goal, symptom, evidence, assumption,
│ root cause, fix, verification, takeaway
│
├── postmortem.md
│ └── Source Markdown for the published article
│
├── evidence/
│ └── superdocs-product-report.md
│ Concise product-facing version of the same findings
│
└── screenshots/
└── Reserved for local supporting evidence when needed
Repository:
https://github.com/Kalpesh1Sharma/paperforge
Relevant areas include:
backend/app/integrations/superdocs/
backend/app/services/review_service.py
backend/app/models/review.py
backend/tests/test_review_service.py
frontend/src/utils/diff.ts
frontend/src/components/DiffView.tsx
frontend/src/App.test.tsx
PaperForge uses SuperDocs as the controlled document-action and human-review layer:
source-grounded report
→ precise proposed edit
→ explicit human review
→ approved/rejected decision
→ verified DOCX
Implementation:
This build exercised:
document upload
→ asynchronous SuperDocs edit
→ pending changes
→ explicit approval/rejection
→ reviewed DOCX export
It also provided the earlier integration evidence around approval request shape and continue_prompt handling.
The open-task brief also asked for the defect log to be sent to SuperDocs as a product report.
The concise report is preserved at:
evidence/superdocs-product-report.md
It uses the same five findings as the published article but separates:
observed behavior
root cause
fix in my integration
product feedback
The recurring mistake across all five defects was allowing the external API boundary to leak too far into the rest of the application.
The more reliable shape became:
SuperDocs
│
▼
narrow provider adapter
│
normalize + validate
│
▼
application-owned state
│
explicit workflow state machine
│
▼
human-readable review surface
│
explicit decision
│
▼
artifact export
│
independent postcondition check
▼
completed
The provider owns the document-editing primitives.
The application still owns the meaning of its state, retries, human decisions, presentation, and product-level completion criteria.
- Published engineering postmortem: complete
- Five primary defects documented: complete
- Root cause and verification for each: complete
- Product report: complete
- Supporting implementation links: included
Kalpesh Sharma