Drawing release register
CJ Ackley | SWE | Project brief

STATUS
Document workflow brief; release rules to agree. Implementation and tests are planned.

THE PROBLEM
An engineering team shares PDFs through folders and email. Similar filenames make it difficult to tell which revision was approved and why it changed. This application keeps immutable uploads, review decisions, and a current-release pointer for each drawing.

DESIGN QUESTION
Can a reader trace the released file to its exact review without confusing it with a draft?

SCOPE
- Use a TypeScript web application, PostgreSQL metadata, and private object storage.
- Hash uploaded PDFs and bind approvals to an immutable revision, not a mutable filename.
- Provide draft review, approval history, superseded revisions, and permission-checked downloads.

CONSTRAINTS
Roles: Author, reviewer, and read-only consumer
Release: Only a verified upload and its approved revision can be released
History: Revisions are retained; corrections create a new revision
Scope: PDF documents and metadata; no CAD parsing or design approval automation

ENGINEERING DECISIONS (PROPOSED)
Upload verification and release transactions
Create a pending revision, upload to a unique object key, and verify its digest before allowing review. Approval names that revision and digest. Publishing changes the current-release pointer in a transaction after rechecking the expected revision.

ALTERNATIVE
Overwriting a file at a stable URL simplifies downloads, but disconnects the approval record from the bytes a reader receives.

TRADEOFF
Database and object storage do not share a transaction. A reconciliation job must find abandoned uploads and missing objects; immutable revision history needs an explicit retention policy.

PROPOSED TOOLS AND METHODS
TypeScript, PostgreSQL, Private object storage

VERIFICATION SCENARIO (NOT YET RUN)
The upload succeeds but finalization fails
Complete an object upload, fail the database transition, and retry it. In parallel, have two reviewers try to release different revisions of one drawing.

PASS CONDITION
An unverified revision never becomes current. A retry reuses its revision identity. One release wins the version check, while the other requires a fresh review of the current state.

EVIDENCE TO RETAIN
Storage fault injection, release-state tests, an object-to-revision reconciliation report, and an authorization matrix exercised through the API.

MEASUREMENT AND LIMITS
Check direct revision URLs as well as the interface. Downloads require authorization; any signed link is short-lived. Test that a superseded revision stays traceable and a reader cannot approve a release.

COMPLETION CRITERIA (PLANNED)
- The seeded author, reviewer, and reader can complete their permitted workflows.
- Partial uploads, competing releases, and cross-document access tests pass.
- Backup and export can reconstruct a revision history with its exact file digests.

VERIFICATION PLAN
Stale approval
Upload a new revision during review; the old approval cannot release it.

Partial failure
Fail an upload or database write; no incomplete revision becomes current.

Authorization
A reader cannot approve, replace, or access another restricted drawing.

PLANNED DELIVERABLES
- Document application, revision API, and storage adapter
- Release-state, concurrent-review, and permission tests
- Local setup, seeded examples, and a backup/export procedure

SCOPE NOTE
The register records reviewers' decisions. Reviewers remain responsible for the drawing content.

NEXT STEP
Agree on drawing identifiers, review roles, and the release state transitions.
