adminbruno
/
docuseal
mirror of https://github.com/docusealco/docuseal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e5758a463d'
${ noResults }
docuseal/docs/prd/5-epic-and-story-structure.md

16 KiB
Raw Blame History

5. Epic and Story Structure

5.1 EPIC APPROACH

Epic Structure Decision: Single Comprehensive Epic with rationale

Rationale for Single Epic Structure:

Based on my analysis of the existing DocuSeal + FloDoc architecture, this enhancement should be structured as a single comprehensive epic because:

  1. Tightly Coupled Workflow: The 3-portal cohort management system is a single, cohesive workflow where:

    • TP Portal creates cohorts and initiates signing
    • Student Portal handles enrollment and document submission
    • Sponsor Portal completes the 3-party signature workflow
    • All three portals must work together for the workflow to function

  2. Sequential Dependencies: Stories have clear dependencies:

    • Database models must exist before any portal can be built
    • Core workflow logic must be in place before UI can be tested
    • Integration points must be validated before end-to-end testing

  3. Shared Infrastructure: All portals share:

    • Same database models (Cohort, CohortEnrollment, Institution)
    • Same authentication/authorization patterns
    • Same DocuSeal integration layer
    • Same design system and UI components

  4. Brownfield Context: This is an enhancement to existing DocuSeal functionality, not independent features. The integration with existing templates, submissions, and submitters must be maintained throughout.

Alternative Considered: Multiple epics (e.g., "TP Portal Epic", "Student Portal Epic", "Sponsor Portal Epic")

  • Rejected Because: Creates artificial separation. Each portal is useless without the others. The workflow is atomic.

Epic Goal: Transform DocuSeal into a specialized 3-portal cohort management system for training institutions while maintaining 100% backward compatibility with existing functionality.

5.2 STORY SEQUENCING STRATEGY

Critical Principles for Brownfield Development:

  1. Zero Regression: Every story must verify existing DocuSeal functionality still works
  2. Incremental Integration: Each story delivers value while maintaining system integrity
  3. Risk-First Approach: Prototype high-risk items early (TP signing duplication, sponsor email deduplication)
  4. Test-Driven: All stories include integration verification steps
  5. Rollback Ready: Each story must be reversible without data loss

Story Sequence Overview:

Phase 1: Foundation (Database + Core Models)
├── Story 1.1: Database Schema Extension
├── Story 1.2: Core Models Implementation
└── Story 1.3: Authorization Layer Extension

Phase 2: Backend Business Logic
├── Story 2.1: Cohort Lifecycle Service
├── Story 2.2: TP Signing Phase Logic (High Risk - Prototype First)
├── Story 2.3: Sponsor Email Deduplication (High Risk - Core Requirement)
├── Story 2.4: Student Enrollment Workflow
├── Story 2.5: Sponsor Portal Access Management
├── Story 2.6: TP Review & Verification Logic
├── Story 2.7: Bulk Download & ZIP Generation
└── Story 2.8: Excel Export (FR23)

Phase 3: API Layer
├── Story 3.1: Cohort Management Endpoints
├── Story 3.2: Student Portal API Endpoints
├── Story 3.3: Sponsor Portal API Endpoints
└── Story 3.4: Excel Export API

Phase 4: Frontend - TP Portal
├── Story 4.1: Institution Onboarding UI
├── Story 4.2: Cohort Dashboard UI
├── Story 4.3: 5-Step Cohort Creation Wizard
├── Story 4.4: Document Mapping Interface
├── Story 4.5: TP Signing Interface
├── Story 4.6: Student Enrollment Monitor
├── Story 4.7: Sponsor Access Monitor
├── Story 4.8: TP Review Dashboard (3-panel)
├── Story 4.9: Cohort Analytics UI
└── Story 4.10: Excel Export Interface
Phase 5: Frontend - Student Portal
├── Story 5.1: Student Invitation Landing
├── Story 5.2: Document Upload Interface
├── Story 5.3: Progress Tracking & Save Draft
├── Story 5.4: Submission Confirmation & Status
└── Story 5.5: Email Notifications & Reminders

Phase 6: Frontend - Sponsor Portal
├── Story 6.1: Cohort Dashboard & Bulk Signing Interface
└── Story 6.2: Email Notifications & Reminders

Phase 7: Integration & Testing
├── Story 7.1: End-to-End Workflow Testing
├── Story 7.2: Mobile Responsiveness Testing
├── Story 7.3: Performance Testing (50+ students)
├── Story 7.4: Security Audit & Penetration Testing
└── Story 7.5: User Acceptance Testing

Phase 8: Deployment & Documentation
├── Story 8.1: Feature Flag Implementation
├── Story 8.2: Deployment Pipeline Update
├── Story 8.3: API Documentation
└── Story 8.4: User Documentation

5.3 INTEGRATION REQUIREMENTS

Integration Verification Strategy:

Each story must include verification that:

  1. Existing DocuSeal functionality remains intact (templates, submissions, submitters)
  2. New FloDoc features integrate correctly with existing infrastructure
  3. Performance impact is within acceptable limits (<20% increase per NFR1)
  4. Security is maintained (no new vulnerabilities introduced)
  5. Data integrity is preserved (no corruption or loss)

Critical Integration Points:

  1. Template → Cohort Mapping:

    • Templates become cohorts
    • Existing template builder must still work
    • New cohort metadata must not break template rendering

  2. Submission → Student Mapping:

    • Submissions represent students in cohorts
    • Existing submission workflows must continue
    • New state management must not conflict with existing states

  3. Submitter → Signatory Mapping:

    • Submitters are participants (TP, Students, Sponsor)
    • Existing submitter logic must adapt to cohort context
    • New email rules must override existing behavior

  4. Storage Integration:

    • Cohort documents use existing Active Storage
    • Bulk downloads must not interfere with existing document access
    • Excel exports must use same storage backend

  5. Email System Integration:

    • Sponsor single-email rule must override DocuSeal's default
    • Student invitations must use existing email infrastructure
    • Cohort notifications must not conflict with existing emails

Rollback Strategy for Each Story:

Every story must include:

  • Database migration: Reversible with down method
  • Code changes: Can be disabled via feature flag
  • Data preservation: No deletion of existing data
  • Testing verification: Script to confirm rollback success

5.4 RISK-MITIGATED STORY PRIORITIZATION

Critical Path (High Risk, High Priority):

  1. Story 1.1 (Database) - Foundation blocker
  2. Story 1.2 (Models) - Foundation blocker
  3. Story 2.2 (TP Signing) - HIGHEST RISK - Must prototype early
  4. Story 2.3 (Sponsor Email) - HIGHEST RISK - Core requirement
  5. Story 2.1 (Cohort Service) - Enables all other stories
  6. Story 3.1 (Cohort API) - Enables frontend development

Why This Order?

  • Database and models are prerequisites
  • TP signing and sponsor email are the two highest-risk items per Section 4.5
  • Early validation prevents wasted effort on dependent stories
  • If these fail, the entire epic needs rethinking

Parallel Workstreams (Low Risk, Independent):

  • Stream A: Student Portal (Stories 5.x) - Can proceed once API is ready
  • Stream B: Excel Export (Story 2.8 + 3.4 + 4.10) - Independent feature
  • Stream C: Documentation (Story 8.3 + 8.4) - Can run in parallel

5.5 ACCEPTANCE CRITERIA FRAMEWORK

All stories must follow this acceptance criteria pattern:

Functional Criteria:

  1. Story-specific functionality works as specified
  2. All related FRs/NFRs from Section 2 are satisfied
  3. Edge cases are handled (empty states, errors, validation)

Integration Criteria:

  1. Existing DocuSeal functionality verified working (see IV1-3 below)
  2. No breaking changes to existing APIs
  3. Database migrations are reversible
  4. Performance impact measured and acceptable

Security Criteria:

  1. Authorization checks on all new endpoints
  2. Input validation on all user-facing fields
  3. No SQL injection, XSS, or CSRF vulnerabilities
  4. Audit logging for all sensitive operations

Quality Criteria:

  1. Minimum 80% test coverage for new code
  2. RuboCop/ESLint pass with no new warnings
  3. Design system compliance (per Section 3.1)
  4. Mobile-responsive on all breakpoints

Integration Verification (IV) Template:

Each story must include these IV steps:

IV1: Existing Functionality Verification

  • "Verify that [existing DocuSeal feature] still works after this change"
  • Example: "Verify that existing template creation still works"
  • Example: "Verify that existing submission workflows complete successfully"

IV2: Integration Point Verification

  • "Verify that new [feature] integrates correctly with [existing system]"
  • Example: "Verify that new Cohort model links correctly to existing Template model"
  • Example: "Verify that new API endpoints follow existing DocuSeal patterns"

IV3: Performance Impact Verification

  • "Verify that performance impact is within acceptable limits"
  • Example: "Verify that cohort dashboard loads in <2 seconds with 50 students"
  • Example: "Verify that memory usage does not exceed 20% increase"

5.6 STORY DEPENDENCIES AND CRITICAL PATH

Dependency Graph:

Story 1.1 (DB Schema) ──┐
                         ├─→ Story 1.2 (Models) ──┐
Story 1.3 (Auth) ───────┘                        │
                                                 ├─→ Story 2.1 (Cohort Service)
                                                  └─→ Story 2.2 (TP Signing - Critical Path)
                                                      └─→ Story 2.3 (Sponsor Email - Critical Path)
                                                          └─→ All subsequent stories...

Critical Path Duration Estimate:

  • Stories 1.1-1.3: 3-5 days
  • Stories 2.1-2.3: 5-8 days (includes prototyping high-risk items)
  • Stories 2.4-2.8: 5-7 days
  • Stories 3.1-3.4: 3-5 days
  • Stories 4.1-4.10: 8-12 days (TP Portal)
  • Stories 5.1-5.5: 5-7 days (Student Portal)
  • Stories 6.1-6.6: 5-7 days (Sponsor Portal)
  • Stories 7.1-7.5: 5-7 days (Integration & Testing)
  • Stories 8.1-8.4: 3-5 days (Deployment)

Total Estimated Duration: 42-63 days (8-12 weeks)

Milestones:

  • Milestone 1 (Week 2): Foundation Complete (Stories 1.x)
  • Milestone 2 (Week 4): Backend Complete (Stories 2.x, 3.x)
  • Milestone 3 (Week 8): All Portals Built (Stories 4.x, 5.x, 6.x)
  • Milestone 4 (Week 10): Testing Complete (Story 7.x)
  • Milestone 5 (Week 12): Production Ready (Story 8.x)

5.7 TECHNICAL DEBT MANAGEMENT

Stories Must Address Existing Technical Debt:

From Section 4.5, we identified:

  1. No coding standards documentation → Covered in Section 4.3
  2. No technical debt analysis → Covered in Section 4.5
  3. Partial implementation (Cohort/Sponsor models referenced but not created) → Stories 1.2 will fix

New Technical Debt Prevention:

Each story must include:

  • Documentation: Code comments, API docs, workflow diagrams
  • Testing: Unit, integration, and system tests
  • Refactoring: Clean code following existing patterns
  • Review: Peer review checklist for quality gates

Debt Paydown Stories:

If technical debt is discovered during implementation:

  • Story 9.1: Refactor for clarity
  • Story 9.2: Add missing tests
  • Story 9.3: Update documentation
  • Story 9.4: Performance optimization

These are tracked separately from main epic but must be completed before epic closure.

5.8 AGENT COORDINATION REQUIREMENTS

BMAD Agent Roles (Corrected):

Based on the BMAD brownfield workflow, the correct agent roles are:

  • Product Manager (PM): Creates PRD, prioritizes features, validates business alignment
  • Scrum Master (SM): Creates individual stories from sharded PRD/Architecture docs
  • Developer (Dev): Implements approved stories, writes code and tests
  • QA/Test Architect: Reviews implementation, creates test strategies, manages quality gates
  • Architect (Winston): Designs system architecture, validates technical feasibility
  • Product Owner (PO): Validates story alignment, runs master checklists, manages backlog

Story Creation Process (Brownfield Workflow):

  1. SM Agent creates stories from sharded PRD using *create task
  2. User reviews and approves story (updates status: Draft → Approved)
  3. Dev Agent implements approved story in new clean chat
  4. QA Agent reviews implementation, may refactor, appends QA Results
  5. User verifies completion, approves for production

Story Handoff Protocol:

Each story must include:

  • Clear acceptance criteria (per Section 5.5)
  • Integration verification steps (IV1-3)
  • Design system references (if UI involved)
  • API endpoint specifications (if backend involved)
  • Test data requirements
  • Rollback procedure

Critical Context Management:

  • ALWAYS use fresh, clean chat sessions when switching agents
  • SM → Dev → QA each in separate conversations
  • Powerful model for SM story creation (thinking models preferred)
  • Dev agent loads: devLoadAlwaysFiles from core-config.yaml

Implementation Order:

Stories must be implemented in the sequence defined in Section 5.2. No jumping ahead, even if later stories seem "easier." This ensures:

  • Foundation is solid before building on it
  • High-risk items are validated early
  • Dependencies are respected
  • Rollback is possible at each stage

5.9 SUCCESS METRICS

Epic Success Criteria:

  1. Functional: All 23 FRs and 12 NFRs from Section 2 are met
  2. Technical: Zero regression in existing DocuSeal functionality
  3. Performance: <20% performance degradation (NFR1)
  4. Security: No new vulnerabilities, sponsor portal security audited
  5. User Experience: All three portals meet UI consistency requirements (Section 3.3)
  6. Documentation: Complete API docs, user guides, and technical documentation
  7. Deployment: Successful production deployment with feature flag control

Story Success Criteria:

Each story is successful when:

  • Acceptance criteria are met
  • Integration verification passes
  • Tests pass with >80% coverage
  • Code review approved
  • Design system compliance verified (if UI)
  • Rollback tested and documented

5.10 NEXT STEPS

Decision Point:

Per your instruction, we're going with Option D: Keep Section 5 as-is (structure and strategy are correct), clarify the exact data-copying mechanism in Section 6 when writing detailed stories.

Before Creating Individual Stories:

  1. User Approval: Confirm this epic structure aligns with your vision ✅ (pending)
  2. Document Sharding: PO agent shards docs/prd.md into docs/prd/ folder
  3. Story Detailing: SM agent creates detailed stories for Phase 1 from sharded docs
  4. Technical Spikes: Dev agent prototypes high-risk items (TP signing, sponsor email)
  5. Design Validation: Verify design system assets are complete and accessible

Transition to Epic Details (Section 6):

Section 6 will provide detailed stories for Phase 1 (Foundation):

  • Story 1.1: Database Schema Extension
  • Story 1.2: Core Models Implementation
  • Story 1.3: Authorization Layer Extension

What Section 6 Will Include:

  • Full user stories (As a... I want... so that...)
  • Detailed acceptance criteria (per Section 5.5 framework)
  • Integration verification steps (IV1-3)
  • Technical implementation notes (including data-copying mechanism clarification)
  • Test requirements and strategies
  • Rollback procedures
  • Risk mitigation details

Critical BMAD Workflow Compliance:

Section 6 stories will follow the brownfield-fullstack workflow:

  1. SM creates story from sharded PRD
  2. User approves (Draft → Approved)
  3. Dev implements in clean chat
  4. QA reviews and validates
  5. User verifies completion