69 lines
3.3 KiB
Markdown
69 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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
|
|
```
|
|
|
|
1. Extract Adobe template (metadata, fields, roles, workflows)
|
|
2. Pass to transform/mapping functions (per field/role/conditional)
|
|
3. Generate canonical model; attempt creation in DocuSign
|
|
4. Log result; pull DocuSign result and validate against input
|
|
5. 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.
|
|
|
|
```mermaid
|
|
graph TD
|
|
Browser -->|HTTP| FastAPI
|
|
FastAPI -->|OAuth| AdobeSign[Adobe Sign API]
|
|
FastAPI -->|OAuth/JWT| 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)
|
|
|
|
**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.*
|