contract-upload

Contract Upload — Complete Guide

A contract upload page is the first step of the signature process. Users upload contract PDFs, the system scans them and detects signature fields, and users can edit those fields before proceeding to signature assignment. The page displays contract groups with their documents, a file upload area per group, and action buttons at the bottom.

Architecture

Page (server) → SubPageHeader + PageContent wrapper
                                    ↓
                              ContractsPageContent (client)
                                    ↓
                              Contract Group × N
                              ├── Group title + description
                              ├── ContractDocument × N per group (from @finstreet/ui)
                              ├── ContractFileUpload (file input per group)
                              └── ContractActionButtons (at bottom, once)

Data Flow

Page (server)
  ├── fetches contracts via getContracts(product)
  ├── fetches signingHeader via getSigningHeader(product)
  └── fetches editorStatus via getEditorStatus(product)
        ↓
ContractsPageContent (client)
  ├── useContracts hook (polls for scan updates every 5s)
  ├── renders ContractDocument per document
  ├── renders ContractFileUpload per contract group
  └── renders ContractActionButtons (uses useEditorStatus hook)

Directory Structure

The feature components live under src/features/contracts/. The backend layer (schema, server/client fetch functions) is assumed to already exist or be created with the secure-fetch skill — this skill only covers the server actions, the polling hook, and the UI components.

src/features/contracts/
  └── components/
      ├── ContractsPageContent.tsx       ← main content component
      ├── ContractFileUpload.tsx         ← file upload per contract group
      ├── ContractActionButtons.tsx      ← back/continue buttons + warning banner
      └── ContractsLoading.tsx           ← skeleton loading state

src/shared/backend/models/contracts/
  ├── uploadContractAction.ts            ← server action: checksum → direct upload → Google Cloud
  ├── deleteContractAction.ts            ← server action: delete contract
  └── hooks/
      └── useContracts.ts                ← React Query hook with auto-polling

Assumed to already exist (created via secure-fetch skill or manually):

• schema.ts — Zod schemas and types
• server.ts — server-side fetch functions (product-parameterized)
• client.ts — client-side fetch function for polling

File Creation Order

1. Server actions — uploadContractAction.ts, deleteContractAction.ts
2. Hook — useContracts.ts
3. Components — ContractFileUpload → ContractActionButtons → ContractsPageContent
4. Loading — ContractsLoading.tsx
5. Page — the route page.tsx + loading.tsx

Step-by-Step Reference

• For the 3 page content components (ContractsPageContent, ContractFileUpload, ContractActionButtons), see components.md
• For the server actions and polling hook, see backend.md

Product Parameterization

All backend functions take a product: Product parameter. The product determines the API path segment via productPath[product]. The page components themselves are product-agnostic — they get product from the useProduct() context hook.

The continue button behavior in ContractActionButtons may vary by product. Some products may start signing directly (bypassing signature assignment), while others navigate to a signature assignment page. Adapt the handleClick logic to the product's requirements.

Rules

1. ContractsPageContent is "use client" — it uses hooks (useContracts, useProduct, useQueryClient, useTranslations, useRouter)
2. ContractFileUpload does NOT have "use client" directive — it's already rendered inside a client component boundary
3. ContractActionButtons is "use client" — it's imported by ContractsPageContent which is also client, but has its own directive
4. The page is a server component that fetches 3 things: contracts, signing header, editor status
5. The page wraps ContractsPageContent inside <PageContent> from @finstreet/ui
6. After upload or delete, invalidate both ["contracts", financingCaseId] and ["editorStatus", financingCaseId] query keys
7. After upload or delete, also call documentExchangeRefetchAction(financingCaseId) to sync document exchange
8. Translation namespace is signatureProcess.startSignatureProcess for all components
9. Use useTranslations from next-intl (not useExtracted)
10. Use arrow function exports (export const) for components
11. The useContracts hook auto-polls every 5 seconds while any document is still scanning or signature fields aren't editable — stops when all documents are clean
12. The loading skeleton re-exports from the feature directory into the route's loading.tsx