6.3 KiB
2. Requirements
2.1 FUNCTIONAL REQUIREMENTS
FR1: The system shall support a single training institution that can manage multiple training cohorts independently.
FR2: The system shall provide three distinct portal interfaces: TP Portal (Training Provider admin), Student Portal (for enrolled students), and Sponsor Portal (for program sponsors).
FR3: The TP Portal shall support cohort creation via a 5-step multi-form:
- Step 1: Cohort name
- Step 2: Program type (learnership/internship/candidacy)
- Step 3: Student emails (manual entry or bulk upload)
- Step 4: Sponsor email (required - single email for all cohort documents)
- Step 5: Upload main SETA agreement + additional supporting docs + specify required student uploads (ID, Matric, Tertiary Qualifications)
FR4: The system shall allow TP to map signatories (Learner, Sponsor, TP) to document sections using DocuSeal's existing mapping capabilities with tweaks for bulk operations.
FR5: The system shall enable TP Signing Phase where:
- TP signs the first student's document
- System duplicates the completed submission (not empty template) to remaining students
- TP's fields and signatures are auto-filled across all student submissions
- This eliminates the need for TP to sign each submission individually
- Prevents duplicate sponsor emails through workflow state management
- Note: DocuSeal's native multi-submission duplicates empty templates; FloDoc will duplicate the signed submission instead
FR6: The system shall generate unique invite links for students via bulk email invitations.
FR7: The system shall allow students to upload required documents (ID, Matric, Tertiary Qualifications) as specified during cohort creation.
FR8: The system shall allow students to fill and sign assigned documents using DocuSeal's existing form builder.
FR9: The system shall implement state management for each student enrollment with states: "Waiting", "In Progress", "Complete".
FR10: The system shall prevent sponsor access until all students in a cohort have completed their submissions.
FR11: The system shall provide sponsor portal with 3-panel layout:
- Left: List of all students in cohort
- Middle: Document viewer (currently selected document)
- Right: Vertical list of thumbnail representations of all documents for the currently selected student
FR12: The system shall allow sponsor to review and sign each student's documents individually OR bulk sign after first completion.
FR13: The system shall enforce single email rule: Sponsor receives ONE email per cohort, regardless of how many students they're assigned to.
FR14: The system shall allow sponsor to submit all signatures to finalize their portion of the workflow.
FR15: The system shall allow TP to review all completed documents from students and sponsor after sponsor submission.
FR16: The system shall enable TP to finalize 3-party agreements after review.
FR17: The system shall provide bulk download functionality with ZIP structure:
Cohort_Name/
├── Student_1/
│ ├── Main_Agreement_Signed.pdf
│ ├── ID_Document.pdf
│ ├── Matric_Certificate.pdf
│ ├── Tertiary_Qualifications.pdf
│ └── Audit_Trail.pdf
├── Student_2/
│ └── ...
FR18: The system shall provide email notifications for:
- Cohort creation (TP only)
- Student invitations (bulk email)
- Submission reminders (configurable)
- Sponsor access notification (when all students complete)
- State change updates
FR19: The system shall provide real-time dashboard showing cohort completion status for all three portals.
FR20: The system shall maintain audit trail for all document actions with timestamps.
FR21: The system shall store all documents using DocuSeal's existing storage infrastructure.
FR22: The system shall maintain 100% backward compatibility with existing DocuSeal form builder and signing workflows.
FR23: The system shall allow TP to export cohort data to Excel format containing: cohort name, student name, student surname, student age, student race, student city, program type, sponsor company name, disability status, and gender.
2.2 NON-FUNCTIONAL REQUIREMENTS
NFR1: The system must maintain existing performance characteristics and not exceed current memory usage by more than 20%.
NFR2: The system must be mobile-optimized and support all existing DocuSeal UI languages.
NFR3: The system must leverage existing DocuSeal authentication infrastructure (Devise + JWT) with role-based access control.
NFR4: The system must integrate seamlessly with existing DocuSeal email notification system.
NFR5: The system must support concurrent cohort management without data leakage between cohorts.
NFR6: The system must provide audit trails for all document verification actions (rejections, approvals).
NFR7: The system must maintain document integrity and signature verification capabilities.
NFR8: The system must support background processing for email notifications and document operations via Sidekiq.
NFR9: The system must comply with South African electronic document and signature regulations.
NFR10: The system must provide comprehensive error handling and user feedback for all portal interactions.
NFR11: The system must implement single email rule for sponsors (no duplicate emails regardless of multiple student assignments).
NFR12: The system must support bulk operations to minimize repetitive work for TP and Sponsor.
2.3 COMPATIBILITY REQUIREMENTS
CR1: API Compatibility: All new endpoints must follow existing DocuSeal API patterns and authentication mechanisms. No breaking changes to existing public APIs.
CR2: Database Schema Compatibility: New tables and relationships must not modify existing DocuSeal core schemas. Extensions should use foreign keys and new tables only.
CR3: UI/UX Consistency: All three portals must use custom TailwindCSS design system (replacing DaisyUI) while maintaining mobile-first responsive design principles.
CR4: Integration Compatibility: The system must work with existing DocuSeal integrations (webhooks, API, embedded forms) without requiring changes to external systems.