# Product Specification

## Project: Adobe Sign to DocuSign Template Migrator

### Purpose
Develop an agent/toolkit that can programmatically extract template data and field logic from Adobe Sign ("library documents"), map/transform into DocuSign's template model, and create new DocuSign templates to reduce manual migration effort.

---

### High-Level Goals
- Download all template structure (PDFs, fields/tabs, roles, routing, logic) from Adobe Sign
- Generate best-approximation DocuSign templates programmatically
- Handle all basic field types and recipient roles
- Detect and warn on features needing special/manual handling (complex logic, custom validations, non-mappable features)
- Produce a structured migration report with successes, warnings, and manual-fix items

---

### Architecture

#### Components
- **Adobe Sign Client** (`src/adobe_api.py`) — authenticated API calls, template listing/download
- **DocuSign Client** (`src/upload_docusign_template.py`, `src/docusign_auth.py`) — OAuth auth, template upsert
- **Normalized Schema Model** (`src/models/normalized_template.py`) — platform-agnostic intermediate representation
- **Mapping Service** (`src/services/mapping_service.py`) — field type, recipient role, coordinate translation; produces `NormalizedTemplate`
- **Validation Service** (`src/services/validation_service.py`) — blocker and warning checks on the normalized schema
- **Compose** (`src/compose_docusign_template.py`) — converts `NormalizedTemplate` → DocuSign `envelopeTemplate` JSON; emits `FieldIssue` objects for partial/dropped features
- **Report Builder** (`src/reports/report_builder.py`) — structured success/warning/error output per template
- **Web API** (`web/`) — FastAPI endpoints for browser-based orchestration; full pipeline orchestration lives in `web/routers/migrate.py`
- **Frontend** (`web/static/`) — side-by-side template browser, migration UI

#### Service Separation
```
src/
  models/
    normalized_template.py      # intermediate schema
    field_issue.py              # structured field-issue model + issue codes
  services/
    mapping_service.py          # field/role/coord transformations
    validation_service.py       # pre/post migration checks
  reports/
    report_builder.py           # structured report output
  utils/
    retry.py                    # exponential backoff retry helpers
    log_sanitizer.py            # secret redaction from logs
```

> Note: pipeline orchestration (download → normalize → validate → compose → upload → report) is
> implemented inline in `web/routers/migrate.py` (`_migrate_one()`) for the web layer and in
> `src/migrate_template.py` for the CLI. There is no shared `migration_service.py` orchestration
> layer — this is a known divergence from the original spec that is acceptable for the current scope.

---

### High-Level Migration Flow

1. Authenticate to both Adobe Sign and DocuSign (OAuth)
2. List and select Adobe Sign templates
3. Extract: metadata, formFields, recipients, documents, workflows
4. **Normalize** into platform-agnostic intermediate schema
5. **Validate** normalized schema — blockers stop migration; warnings are logged
6. Map to DocuSign template payload
7. Upsert (create or update) in DocuSign
8. Generate migration report

---

### Internal Normalized Schema

Use an intermediate model so the tool is not tightly coupled to either platform. This enables future support for additional eSign platforms.

#### Schema Structure
```json
{
  "template": {
    "name": "Sales Agreement",
    "description": "Migrated from Adobe Sign",
    "emailSubject": "Please sign: Sales Agreement",
    "emailMessage": "",
    "documents": [],
    "roles": [
      { "name": "Customer", "order": 1, "actionType": "SIGN" },
      { "name": "Company",  "order": 2, "actionType": "SIGN" }
    ],
    "fields": [
      {
        "type": "signature",
        "page": 1,
        "x": 120, "y": 540,
        "width": 140, "height": 28,
        "required": true,
        "roleName": "Customer"
      }
    ],
    "reminderEnabled": false,
    "expirationDays": null
  }
}
```

---

### Core Entities to Migrate

| Entity            | Adobe Sign Source           | DocuSign Target             |
|-------------------|-----------------------------|-----------------------------|
| Template name     | `name`                      | `name`                      |
| Description       | `message`                   | `description`               |
| Documents (PDFs)  | `libraryDocumentId` → bytes | `documents[]`               |
| Recipient roles   | `participantSetsInfo`       | `recipients.signers[]`      |
| Routing order     | `participantSetsInfo.order` | `routingOrder`              |
| Form fields       | `formFields`                | `tabs` per recipient        |
| Email subject     | `emailSubject`              | `emailSubject`              |
| Reminders         | `reminderFrequency`         | `reminders`                 |
| Expiration        | `daysUntilSigningDeadline`  | `expirationDateTime`        |

---

### Mapping Logic

#### 1. Recipient and Role Mapping
- Map Adobe Sign participant sets → DocuSign template roles
- Preserve routing order
- Map action types: SIGN → signer, APPROVE → approver, CC → carbonCopy

#### 2. Field Type Mapping
```json
{
  "SIGNATURE":   "signHere",
  "INITIALS":    "initialHere",
  "TEXT":        "text",
  "CHECKBOX":    "checkbox",
  "RADIO":       "radioGroup",
  "DROPDOWN":    "list",
  "DATE":        "dateSigned",
  "ATTACHMENT":  "signerAttachment"
}
```
(Full mapping table: see `field-mapping.md`)

#### 3. Coordinate Mapping
- Normalize to PDF points
- Account for page rotation
- Transform coordinate origin if needed
- Validate field overlap after placement

#### 4. DocuSign Payload Fields
The tool must populate:
- Template name and description
- Email subject and message defaults
- Envelope/template documents (with document checksums)
- Template roles with routing order
- Tabs grouped by recipient
- Reminder and expiration settings where supported

---

### Unsupported / Flagged Features (Manual Review Required)
- Conditional recipient routing rules
- Advanced workflow branching
- Calculated fields
- Custom JavaScript validators
- Niche authentication methods (e.g., KBA, phone auth)
- Field validations with no direct DocuSign equivalent
- Webhook / event associations tied to template lifecycle

---

### Migration Options (API)

`POST /api/migrate` accepts:
```json
{
  "sourceTemplateIds": ["tpl_1001", "tpl_1002"],
  "targetFolder": "Migrated Templates",
  "options": {
    "overwriteIfExists": false,
    "dryRun": true,
    "includeDocuments": true
  }
}
```

- **dryRun** — validate and report without creating DocuSign templates
- **overwriteIfExists** — when `false`, skip templates already migrated (default: false)
- **includeDocuments** — embed PDFs in DocuSign template (default: true)
- **targetFolder** — DocuSign folder for created templates

---

### Validation Layer

Pre-migration checks (blockers and warnings):
- Field count before vs. after mapping
- Recipient count and routing order integrity
- Fields missing role assignments
- Unsupported feature detection
- Document checksum comparison (before upload vs. after download confirmation)

Post-migration checks:
- DocuSign template field count vs. normalized schema count
- Recipient role count match
- Migration report includes pass/warn/fail per template

---

### Implementation Considerations

#### Authentication
- OAuth for both Adobe Sign and DocuSign (with token auto-refresh)
- Support admin-consent flows where required
- Securely store tokens (never in logs or plaintext files)

#### Rate Limits
- Batch API requests carefully
- Retries with exponential backoff on 429/5xx
- Use idempotency (upsert pattern) where possible

#### File Handling
- Preserve original PDFs locally in `downloads/`
- Checksum documents before and after upload
- Keep document-page metadata for accurate tab placement

#### Security
- Redact secrets and tokens from all log output
- Encrypt token storage where possible
- Maintain audit trail for all migration operations (template ID, timestamp, status, user)

---

### MVP Feature Set (Phase 1)
- Authenticate to both systems (CLI + Web)
- List and select Adobe Sign templates
- Migrate basic templates (standard roles + common fields)
- Normalized intermediate schema as pipeline bridge
- Validation layer (field/recipient counts, missing roles)
- Migration report (success / warning / error per template)
- Dry-run mode
- Idempotent re-runs (overwrite prevention)

### Phase 2 Features
- Batch migration (multiple templates in one request)
- Retry failed templates
- Coordinate validation preview
- Duplicate detection
- Folder / category mapping
- Audit logging
- Rate limit handling with backoff

### Phase 3 Features
- UI preview for field placements
- Manual correction workflow
- Side-by-side template comparison (visual diff)
- Webhook recreation
- Advanced workflow translation

---

### Out of Scope (MVP)
- Agreement instance migration (templates only)
- Custom integrations outside API surface
- Real-time collaborative editing

---

*Updated: 2026-04-21 (Blueprint alignment — added normalized schema, validation layer, migration options, security/rate-limit requirements, Phase 2/3 feature set, architecture detail)*