Software Architect Specialist

Illustrative preview: this representative editorial result is not a recorded runtime session.

ArchitectureSpec — cancellation-safe invoice exports

task_id: software-architect-example-1; artifact_id: ArchitectureSpec-EX-1; version: 0.1.0. IDs identify this representative artifact, not a runtime execution.

Status: DRAFT. Producer: Software Architect; recipient: implementation owner. Objective: one export per intentional request, owner-scoped access and cancellation that remains authoritative. Grounding: the supplied system description; base_ref unknown. No code or deployment was inspected.

Recommendation

Keep the existing application, database and worker. Add an export lifecycle and an atomic request-identity contract. A separately deployed export service would add network and operational failure without a stated isolation or scaling need. Revisit that choice only when measured resource interference or independent ownership justifies it.

Rules and boundaries

REQ-1: request identity is scoped to authenticated owner plus operation. The client supplies a fresh identity for each intentional export and reuses it after an uncertain timeout. The server stores identity, canonical parameters and job ID atomically with job creation. A repeat with matching parameters returns that job; a parameter mismatch is rejected. Identity retention must cover the seven-day job lifecycle. This is a proposed API contract, not an inspected existing one.

REQ-2: resolve owner from trusted authentication, never from client-submitted owner_id. Every status, cancellation and download lookup checks the authenticated actor against the stored owner. Cross-owner lookups disclose neither metadata nor storage URLs. Storage remains private.

REQ-3: proposed states are queued, running, completed, cancelled, failed and expired. Cancellation sets a durable cancellation marker in a transaction. Completion may attach an object reference only if cancellation has not been accepted; conditional state change resolves the race. If upload already occurred, cleanup removes that object, but download authorization denies it immediately. Cancellation acknowledgement therefore depends on the durable marker, not on worker interruption.

REQ-4: status returns state, safe progress if supported and permitted next actions. Failed work is retryable only through a defined action; blind worker retry must not create a second export. The worker checks cancellation before expensive work and before publishing completion. Unknown upload outcomes are reconciled by recorded job/object identity.

REQ-5: expiry denies download at the server after seven days and schedules object deletion. Decide whether job metadata survives file expiry before implementing its retention policy; that policy is not supplied.

Acceptance and failure signals

AC-1: concurrent submissions with the same owner, identity and parameters create one job; any second job fails the contract. AC-2: distinct intentional identities may create distinct jobs even with identical parameters. AC-3: a matching retry after a simulated response timeout returns the original job. AC-4: another user cannot read, cancel or download the job. AC-5: both completion/cancellation orderings leave download denied after accepted cancellation; an accessible object fails the invariant. AC-6: expiry denies download and cleanup can be retried without reviving the export. All checks are proposed, not executed.

Delivery and recovery

Slice 1: inspect current callers/worker, add lifecycle and identity storage, then prove AC-1–4. Slice 2: add cancellation/completion race enforcement and cleanup, prove AC-5. Slice 3: expiry enforcement and reconciliation, prove AC-6. If existing clients omit identities, a coexistence policy is required before changing POST semantics. Back out new creation through a feature control while retaining lifecycle records for outstanding jobs; a code rollback does not undo existing object or data effects.

Next owner/action: implementation owner inspects current transaction and worker boundaries and closes metadata retention and legacy-client coexistence. Independent contract design can proceed. Those gaps keep the affected delivery slice DRAFT; this specification is not implementation or release approval.