Reza DocuHandshake — User Flows

Flow 1 — User Submits a Document

Step 1 — Magic-Link Verification

1. User visits https://docu.r32a.com/.
2. The AuthForm component asks for an email address.
3. Frontend calls POST /api/auth/magic-link/request.
4. Backend inserts a one-time token hash into magic_link_tokens and sends a Resend email.
5. The email links to /auth/verify?token=....
6. AuthVerifyPage calls POST /api/auth/magic-link/verify.
7. Backend marks the token as used and sets the rdh_user_session HTTP-only cookie.
8. Frontend checks session state with GET /api/auth/session and shows the upload form.

Step 2 — Document Upload

1. User sees DocumentUploadCard.
2. User selects or drags in a PDF.
3. Client validation allows only PDF files up to 10 MB.
4. User enters an optional description.
5. Optional: user enables SignatureAreaMarker and clicks on the PDF preview to mark suggested signature locations.
6. Frontend submits multipart form-data to POST /api/documents/upload.

Step 3 — Upload Processing

1. requireUser verifies the session cookie.
2. Backend saves the file under: documents/{timestamp}-{uuid}-{sanitized-filename}
3. Backend inserts a row into documents with:
   • status = 'pending'
   • comment
   • suggested_signature_positions
4. Backend inserts an audit entry with action = 'document_uploaded'.
5. Backend attempts to email Reza about the new upload.
6. If notification email fails, the upload still succeeds and the warning is logged server-side.

Step 4 — Thank-You Page

1. Frontend navigates to /thank-you.
2. User sees confirmation that the document was received.
3. Clicking "Back to Main Page" signs the user out through POST /api/auth/logout and returns to /.

Flow 2 — Admin Reviews and Signs a Document

Step 1 — Admin Sign-In

1. Reza visits /admin.
2. AdminAuth checks the entered password against VITE_ADMIN_PASSWORD.
3. After frontend sign-in succeeds, the dashboard loads documents through POST /api/admin/list-documents.
4. Backend validates the password against ADMIN_PASSWORD before returning data.

Step 2 — Dashboard List View

The admin dashboard includes:

• Search by filename or uploader email
• Pagination with 6 documents per page
• Active vs archived toggle based on documents.archived
• Status badges for pending, signed, and completed
• Analytics view
• Settings view
• Bulk ZIP download of signed documents

Step 3 — Settings View

The Settings view lets Reza define a reusable signature preset:

• Text signature mode
• Image upload signature mode
• Adjustable signature scale

The preset is stored in the backend as the shared source of truth and also cached in browser localStorage under rdh_admin_signature_preset_v1.

That means:

• desktop and mobile now use the same saved signature preset
• an older desktop-only local preset can seed the shared backend preset the first time the admin signs in after the update

Step 4 — Document Viewer and Analysis

1. Reza opens a document from the list.
2. Frontend loads the PDF from: GET /api/documents/:id/file?adminPassword=...
3. react-pdf renders the file in-browser.
4. DocumentAnalysis can extract text from the loaded PDF in the browser and call POST /api/admin/analyze-document.
5. The backend sends the extracted text to OpenAI gpt-4o-mini.
6. The analysis result currently returns:
   • summary
   • keyPoints
   • reviewAreas
   • risks
   • riskAssessment

Step 5 — Placing Signature Markers

1. Reza enters "Place Signature" mode.
2. Clicking the page adds signature markers for the current PDF page.
3. Existing markers can be dragged to fine-tune placement.
4. Markers can be removed individually or cleared all at once.
5. If the uploader supplied suggested positions, the admin can load them with "Use Suggested Positions".
6. Page navigation and zoom controls are available while reviewing the document.

Step 6 — Completing the Signature

All PDF editing happens in the browser:

1. Frontend downloads the original PDF bytes from the secure document URL.
2. signPdfBytes() loads the file with pdf-lib.
3. For each marker, the app renders either:
   • the configured signature image, or
   • a text signature fallback
4. The app also draws a small footer with signer name plus signed date/time.
5. The finished PDF is uploaded to POST /api/admin/upload-signed-file.
6. Backend stores the signed file under: signed/{documentId}/{timestamp}_{sanitized-filename}
7. Frontend calls POST /api/admin/update-document to set:
   • status = 'signed'
   • signed_at
   • signature_data (JSON string of signature positions)
   • file_path (the signed file path)
8. The same update request can write an audit entry with action = 'signed'.
9. Frontend calls POST /api/notifications/send with type = 'document_signed'.
10. Backend attaches the signed PDF to the email and also includes a tokenized public download link valid for 20 minutes.

Step 7 — Post-Signing Actions

After review, Reza can:

• Resend the signed document email
• Download the signed PDF directly
• Reject the document with a reason

Current rejection behavior:

1. Frontend sets status = 'completed'.
2. Backend inserts an audit entry with action = 'rejected'.
3. Frontend calls POST /api/notifications/send with type = 'document_rejected'.
4. The rejection email tells the uploader to resubmit via the main portal.

Signed documents are locked in the viewer and marker editing is disabled.

Flow 3 — Bulk Download All Signed Documents

1. Reza clicks "Download All Signed (N)" in the dashboard.
2. Frontend filters the current document set to rows where status === 'signed'.
3. Each signed PDF is fetched through the secure document endpoint.
4. Files are added to a JSZip archive using: {first8DocumentId}_{originalFilename}
5. If a filename collides, a counter is appended.
6. Browser download starts as: signed-documents-YYYY-MM-DD.zip

Flow 4 — Analytics View

Analytics are computed client-side from non-archived documents and support these time filters:

• All time
• Today
• Last 7 days
• Last 30 days
• Last 90 days
• Last year

Displayed metrics:

• Trees saved estimate
• Time saved estimate
• Unique senders
• Completion rate
• Average processing time
• Top senders
• Document type distribution
• Status distribution
• Monthly submission trends
• Peak submission days
• File size distribution
• Largest documents
• Recent activity