Reservation Pattern (Phase 1)

The system implements a Metadata-First Upload Pattern (Reservation Pattern). This architectural choice decouples the heavy I/O operation of file transfer from the transactional integrity of the database schema.

By creating "Order" entities and file "placeholders" prior to binary transfer, referential integrity is ensured. A client-generated tags (UUID) serves as a correlation token to map server-generated IDs back to client-side file objects without requiring complex server-side session state.

The following Sequence Diagram illustrates the workflow, capturing interactions between the User, Client, and Server.

Architectural Overview

This design prioritizes atomicity within a stateless API environment.

1. Correlation Strategy: The system employs a Client-Side Correlation ID (tags). Since database IDs are generated during initialization, the client utilizes the echoed UUID in the response to associate binary data with the corresponding database record.
2. Directory Abstraction: Orders are represented as virtual directory and has directories with mime type application/vnd.notaryos.directory within the files table. This normalization allows consistent ACL/RBAC application across both order containers and individual files.
3. Form Handling: Forms are treated as files with a specific MIME type application/vnd.notaryos.form. This unifies the storage treatment of structured data and unstructured binary objects.

Recommendation for Partial Failure Handling:

To address potential partial failures during bulk upload (Step 13), a final status update step is recommended:

• Client -> Server: PATCH /order/{id}/status (mark as COMPLETE)

This ensures the system explicitly registers the successful completion of the bulk upload.