3.9 KiB

Raw Blame History

Architecture & Design Overview

System Components

Extraction Layer: Handles authentication, API calls, and raw data retrieval from Adobe Sign. Input: .env credentials. Output: JSON metadata + field data.
Mapping/Transform Layer: Pure logic between raw Adobe template objects and canonical DocuSign template model. Handles all 1:1, many:1, and lossy mappings. Logging of ambiguities.
DocuSign Ingest Layer: Authenticates, creates/updates templates in DocuSign using mapped objects. Handles feedback, errors, and reporting.
Validation/QA Layer: Compares final artifacts, runs coverage and correctness checks, supports dry-run/test modes.
Testing/Scenario Folder: Sample templates and responses (see /sample-templates/) and mapping/transform test cases.

Data Flow

graph TD
  A[Adobe Sign API] -->|Extract| B[Raw JSON]
  B -->|Transform/Map| C[Canonical Model]
  C -->|Ingest| D[DocuSign API]
  D -->|Validate| E[QA/Reporting]
  E -->|Feedback| B

Extract Adobe template (metadata, fields, roles, workflows)
Pass to transform/mapping functions (per field/role/conditional)
Generate canonical model; attempt creation in DocuSign
Log result; pull DocuSign result and validate against input
Drop all validated or problematic test scenarios in /sample-templates/ or a new tests/ folder for regression & future QA

Key Design Decisions & Logger

Focus on batch/parallelization via pipelined scripts/modules
Use local cache of all raw API payloads for traceability
Mapping module must be testable with static samples (no account needed at first)
Agent harness structure for project traceability, autonomous improvement
Decision Log (expand as project runs):
- [2026-04-14] Start with static JSON tests and pure transforms before integrating live API. Document all lossy mappings inline in mapping functions & doc.
- [2026-04-14] Capture all feature-mapping challenges (fields, roles) as they appear in real-world test cases and update this doc.

Extensibility

Designed for: new field types, more templates, transform plugins
Support “mapping hints” or forced overrides for ambiguous/complex field cases

v2 Architecture — Web UI (2026-04-17)

The pipeline is extended with a FastAPI web layer that wraps all existing src/ modules.

graph TD
  Browser -->|HTTP| FastAPI
  FastAPI -->|OAuth| AdobeSign[Adobe Sign API]
  FastAPI -->|OAuth| DocuSign[DocuSign API]
  FastAPI -->|calls| Compose[compose_docusign_template.py]
  FastAPI -->|calls| Upload[upload_docusign_template.py]
  Upload -->|upsert| DocuSign
  FastAPI -->|reads/writes| History[migration-output/.history.json]

New layers:

web/routers/auth.py — browser-initiated OAuth for Adobe Sign and DocuSign
web/routers/templates.py — template listing + migration status computation
web/routers/migrate.py — triggers pipeline; records history
web/static/ — vanilla HTML/JS SPA (no build step)

Template issue status: GET /api/templates/status drives the Templates and Issues & Warnings pages. Its summary status combines pre-migration validation and DocuSign composition analysis:

blockers: validation failures that stop migration.
warnings: validation warnings that allow migration but need review.
field_issues: field mapping caveats emitted by composition, such as skipped field types or unsupported conditional logic.

The list-level "Clean" label should only appear when all three collections are empty, so summary rows match the template detail and migration result views.

Idempotent Upload (v2): upload_docusign_template.py now searches for an existing DocuSign template by exact name match and updates the most recently modified one (PUT). Falls back to create (POST) if no match. --force-create flag bypasses upsert.

Update as architecture/requirements change. Generated by Cleo (2026-04-14). Updated 2026-04-17.

3.9 KiB Raw Blame History