ccopeland/red
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: create milestone v1.2 roadmap (4 phases)

Browse Source
This commit is contained in:
Chandler Copeland
2026-04-03 14:59:31 -06:00
parent 64ccb750fa
commit 4d69253a94
3 changed files with 141 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
.planning/ROADMAP.md
View File

@@ -6,10 +6,13 @@ A dual-product build: a public real estate marketing site for a solo Utah agent
v1.1 extends the platform with AI-assisted field placement, expanded field types (text, checkbox, initials, date, agent signature), agent saved signature with draw-once-reuse workflow, and a filled document preview before sending.
v1.2 extends the platform to multiple signers in parallel and ships a production-ready Docker Compose deployment with correct SMTP and secret injection.
## Milestones
- ✅ **v1.0 Core Document Signing Platform** - Phases 1-7 (shipped 2026-03-21)
- 🚧 **v1.1 Smart Document Preparation** - Phases 8-13 (in progress)
- 📋 **v1.2 Multi-Signer and Deployment Hardening** - Phases 14-17 (planned)
## Phases
@@ -167,6 +170,15 @@ Plans:
- [x] **Phase 12.1: Per-Field Text Editing and Quick-Fill (INSERTED)** - Agent clicks a text field box to edit its value inline; PreparePanel shows quick-fill suggestions (client name, address, etc.) when a field is selected; text fill data is keyed by field ID (completed 2026-03-21)
- [ ] **Phase 13: AI Field Placement and Pre-fill** - One-click AI auto-placement of all field types plus pre-fill of text fields from client profile data
### 📋 v1.2 Multi-Signer and Deployment Hardening (Planned)
**Milestone Goal:** A single document can be sent to multiple signers in parallel, each receiving their own link and seeing only their own fields, with automatic completion notifications — plus a production-ready Docker Compose setup that correctly passes secrets so email works reliably.
- [ ] **Phase 14: Multi-Signer Schema** - Additive DB migration enabling multi-signer field routing, per-signer token identity, and race-safe completion detection
- [ ] **Phase 15: Multi-Signer Backend** - Token creation loop, signer-aware signing flow, atomic completion detection, parallel email dispatch and final PDF delivery
- [ ] **Phase 16: Multi-Signer UI** - PreparePanel signer list, FieldPlacer signer assignment and color-coding, send-block validation, per-signer dashboard status
- [ ] **Phase 17: Docker Deployment** - Three-stage Dockerfile, docker-compose.yml with named uploads volume and env_file secrets, health endpoint, SMTP fix
## Phase Details
### Phase 8: Schema Foundation and Signing Page Safety
@@ -295,10 +307,60 @@ Plans:
- [ ] 13-03-PLAN.md — UI wiring: aiPlacementKey prop in FieldPlacer + PdfViewerWrapper thread-through; "AI Auto-place Fields" button (violet) in PreparePanel; DocumentPageClient handleAiAutoPlace with textFillData merge and preview reset
- [ ] 13-04-PLAN.md — Integration test with full 20-page Utah REPC + full Phase 13 human verification checkpoint
### Phase 14: Multi-Signer Schema
**Goal**: The database schema is ready for multi-signer documents — signers are first-class records on documents, tokens carry signer identity, and the completion guard column prevents race conditions — with zero breakage to existing single-signer documents
**Depends on**: Phase 13
**Requirements**: MSIGN-08
**Success Criteria** (what must be TRUE):
1. Drizzle migration applies cleanly to the production Neon database with no data loss on existing documents or signing tokens
2. Existing single-signer documents continue to prepare, send, and sign exactly as before — the new nullable columns are invisible to the legacy code paths
3. `SignatureFieldData` TypeScript interface has an optional `signerEmail` field; `signingTokens` table has a nullable `signerEmail` TEXT column; `documents` table has `signers` JSONB and `completionTriggeredAt` TIMESTAMP columns
4. The `completionTriggeredAt` guard column is present and its purpose is verified: an `UPDATE ... WHERE completionTriggeredAt IS NULL RETURNING` query atomically claims it exactly once per document
**Plans**: TBD
**UI hint**: no
### Phase 15: Multi-Signer Backend
**Goal**: The server correctly creates one signing token per signer, filters each signer's signing page to their own fields, and detects completion atomically — all signers receive their links at once, and when the last signer signs all parties get the final PDF
**Depends on**: Phase 14
**Requirements**: MSIGN-05, MSIGN-06, MSIGN-07, MSIGN-10, MSIGN-11
**Success Criteria** (what must be TRUE):
1. When the agent sends a two-signer document, both signers receive their unique signing links in a single send operation (parallel email dispatch, no sequential dependency)
2. Each signer's GET /api/sign/[token] response contains only the fields tagged to that signer's email — fields belonging to other signers are absent from the response
3. The POST /api/sign/[token] handler rejects any field submission where the field's signerEmail does not match the token's signerEmail (server-enforced ownership)
4. When the last signer submits, `completionTriggeredAt` is claimed atomically — only one handler triggers final PDF assembly regardless of concurrent submissions
5. Agent receives a notification email and all signers receive the final merged PDF link when all signing tokens for the document are claimed
**Plans**: TBD
**UI hint**: no
### Phase 16: Multi-Signer UI
**Goal**: Agent can name and add multiple signers from PreparePanel, assign each field to a specific signer in FieldPlacer with color-coded visual distinction, and cannot accidentally send a document with unassigned client-facing fields
**Depends on**: Phase 15
**Requirements**: MSIGN-01, MSIGN-02, MSIGN-03, MSIGN-04, MSIGN-09
**Success Criteria** (what must be TRUE):
1. Agent can add two or more signer email addresses in PreparePanel before sending — signers are saved to the document record and the list is editable until send
2. Each field placed in FieldPlacer has a signer assignment dropdown; selecting a signer changes the field's color to that signer's assigned color
3. If the agent clicks Send with any client-facing field (signature, initials, date, text) having no signer assigned, the send is blocked and a clear error message identifies the unassigned fields
4. The dashboard document detail view shows a per-signer completion row for each signer (who has signed, who hasn't, with timestamps)
**Plans**: TBD
**UI hint**: yes
### Phase 17: Docker Deployment
**Goal**: The application runs reliably in a Docker container on the production server — secrets are injected at runtime, email delivers correctly, uploaded files survive container restarts, and a health check confirms database connectivity
**Depends on**: Phase 16
**Requirements**: DEPLOY-01, DEPLOY-02, DEPLOY-03, DEPLOY-04, DEPLOY-05
**Success Criteria** (what must be TRUE):
1. `docker compose up` starts the application and `GET /api/health` returns 200 OK with a successful database ping
2. SMTP credentials are read from `.env.production` via `env_file:` in docker-compose.yml — a signing link email and a completion notification email both deliver successfully from the running container
3. The `APP_BASE_URL` variable (renamed from `NEXT_PUBLIC_BASE_URL`) is injected at container runtime — signing link URLs in emails contain the correct production domain, not localhost
4. Uploaded PDF files written inside the container persist after `docker compose down && docker compose up` (named Docker volume mounted at /app/uploads)
5. The Docker image uses `node:20-slim` (Debian-based) — `@napi-rs/canvas` native binary loads without errors at container startup
**Plans**: TBD
**UI hint**: no
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 13
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 11.1 → 12 → 12.1 → 13 → 14 → 15 → 16 → 17
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
@@ -309,11 +371,15 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
| 5. PDF Fill and Field Mapping | v1.0 | 4/4 | Complete | 2026-03-21 |
| 6. Signing Flow | v1.0 | 6/6 | Complete | 2026-03-21 |
| 7. Audit Trail and Download | v1.0 | 3/3 | Complete | 2026-03-21 |
| 8. Schema Foundation and Signing Page Safety | 2/2 | Complete | 2026-03-21 | - |
| 9. Client Property Address | 1/1 | Complete | 2026-03-21 | - |
| 8. Schema Foundation and Signing Page Safety | v1.1 | 2/2 | Complete | 2026-03-21 |
| 9. Client Property Address | v1.1 | 1/1 | Complete | 2026-03-21 |
| 10. Expanded Field Types End-to-End | v1.1 | 3/3 | Complete | 2026-03-21 |
| 11. Agent Saved Signature and Signing Workflow | 3/3 | Complete | 2026-03-21 | - |
| 11.1. Agent and Client Initials (INSERTED) | 3/3 | Complete | 2026-03-21 | - |
| 12. Filled Document Preview | 2/2 | Complete | 2026-03-21 | - |
| 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | 2/2 | Complete | 2026-03-21 | - |
| 13. AI Field Placement and Pre-fill | 3/4 | In Progress| | - |
| 11. Agent Saved Signature and Signing Workflow | v1.1 | 3/3 | Complete | 2026-03-21 |
| 11.1. Agent and Client Initials (INSERTED) | v1.1 | 3/3 | Complete | 2026-03-21 |
| 12. Filled Document Preview | v1.1 | 2/2 | Complete | 2026-03-21 |
| 12.1. Per-Field Text Editing and Quick-Fill (INSERTED) | v1.1 | 2/2 | Complete | 2026-03-21 |
| 13. AI Field Placement and Pre-fill | v1.1 | 3/4 | In Progress | - |
| 14. Multi-Signer Schema | v1.2 | 0/TBD | Not started | - |
| 15. Multi-Signer Backend | v1.2 | 0/TBD | Not started | - |
| 16. Multi-Signer UI | v1.2 | 0/TBD | Not started | - |
| 17. Docker Deployment | v1.2 | 0/TBD | Not started | - |