Reza DocuHandshake — Architecture & Data Reference

Frontend Routes

Route	Component	Purpose
/	IndexPage	User portal: magic-link auth + upload
/auth/verify	AuthVerifyPage	Token verification
/thank-you	ThankYouPage	Post-submission confirmation
/admin	SigningDashboardPage	Admin dashboard
/login	redirect to /	Alias
/signin	redirect to /	Alias
/auth	redirect to /	Alias
/upload	redirect to /	Alias
/start	redirect to /	Alias
/home	redirect to /	Alias
/index.html	redirect to /	Alias
/auth/*	redirect to /	Alias catch-all
*	NotFoundPage	404

Backend Utility and API Routes

Route	Purpose
/	Small backend utility page for local testing
/api	API info payload
/api/health	Health check

PostgreSQL Schema

Table: documents

Column	Type	Description
id	uuid	Primary key
user_email	text	Uploader email
user_phone	text	Optional, unused in current UI
filename	text	Original filename
file_path	text	Relative path to the current file on disk
file_size	bigint	File size in bytes
mime_type	text	Currently application/pdf
status	text	pending, signed, completed
comment	text	Upload description
suggested_signature_positions	jsonb	Optional array of signature positions
signature_data	text	JSON string of the final placed signature positions
signed_at	timestamptz	When signing completed
archived	boolean	Archive toggle used by dashboard filter
created_at	timestamptz	Insert timestamp
updated_at	timestamptz	Auto-maintained update timestamp

Table: document_audit_trail

Column	Type	Description
id	uuid	Primary key
document_id	uuid	FK to documents.id
action	text	document_uploaded, signed, rejected
user_email	text	Actor email
timestamp	timestamptz	Event time
ip_address	inet	Optional metadata
user_agent	text	Optional metadata

Table: magic_link_tokens

Column	Type	Description
id	uuid	Primary key
email	text	Recipient email
token_hash	text	SHA-256 hash of the magic-link token
expires_at	timestamptz	Expiration timestamp
used_at	timestamptz	Set once token is consumed
created_at	timestamptz	Creation timestamp

Table: app_settings

Column	Type	Description
key	text	Setting key
value	jsonb	Setting payload
updated_at	timestamptz	Last update time

Trigger

set_documents_updated_at() keeps documents.updated_at current on every update.

File Storage

Storage is filesystem-based under STORAGE_ROOT (default: storage/).

Relative Path Pattern	Content
documents/{timestamp}-{uuid}-{sanitized-name}	Original uploaded PDF
signed/{documentId}/{timestamp}_{sanitized-name}	Signed PDF

documents.file_path always points at the file currently used for download. After signing, it is updated to the signed file path.

Backend API

All API routes are mounted in server/index.ts.

Auth Routes

• POST /api/auth/magic-link/request
  • Body: { email }
  • Creates a token record and sends a magic link email
• POST /api/auth/magic-link/verify
  • Body: { token }
  • Marks the token used and sets the session cookie
• GET /api/auth/session
  • Returns the current signed-in user or null
• POST /api/auth/logout
  • Clears the session cookie

Document Routes

• POST /api/documents/upload
  • Auth: user session cookie required
  • Multipart fields: file, comment, suggestedSignaturePositions
• GET /api/documents/:id/file
  • Auth: owner session cookie or valid admin password
  • Admin callers use the query string or x-admin-password header
• GET /api/documents/public/download/:token
  • Auth: signed JWT download token
  • Used for public download links in signed-document emails

Admin Routes

• POST /api/admin/list-documents
  • Auth: admin password required
• POST /api/admin/get-document-audit-trail
  • Auth: admin password required
• POST /api/admin/get-signature-preset
  • Auth: admin password required
• POST /api/admin/update-signature-preset
  • Auth: admin password required
• POST /api/admin/update-document
  • Auth: admin password required
  • Allowed update fields: archived, status, signed_at, signature_data, file_path
• POST /api/admin/upload-signed-file
  • Auth: admin password required
  • Multipart upload of the final signed PDF
• POST /api/admin/analyze-document
  • Current auth behavior: no admin password required
  • Sends extracted PDF text to OpenAI gpt-4o-mini
• POST /api/admin/generate-signature
  • Current auth behavior: no admin password required
  • Returns an OpenAI-generated handwritten signature or SVG fallback

Notification Route

• POST /api/notifications/send
  • Current auth behavior: no auth required
  • Types:
    • document_received
    • document_signed
    • document_rejected

Environment Variables

Frontend

• VITE_API_BASE_URL
• VITE_ADMIN_PASSWORD

Backend Required

• DATABASE_URL

Backend Commonly Set

• PORT
• HOST
• APP_BASE_URL
• API_BASE_URL
• JWT_SECRET
• ADMIN_PASSWORD
• OTP_EXPIRY_SECONDS
• SESSION_EXPIRY_DAYS
• STORAGE_ROOT

Optional Integrations

• RESEND_API_KEY
• RESEND_FROM_EMAIL
• REZA_EMAIL
• OPENAI_API_KEY

Current Behavioral Notes

• User session cookie name is rdh_user_session.
• Magic links default to a 24-hour expiry.
• Signed download links expire after 20 minutes.
• Rejected documents currently use status = 'completed'; the rejection reason is delivered by email rather than stored in a dedicated column.