mirror of https://github.com/docusealco/docuseal
✅ COMPLETED: Brownfield PRD for 3-Portal Cohort Management
CHANGES:
- Updated CLAUDE.md with mandatory Enhanced IDE Development Workflow
- Added comprehensive Test Architect integration guide (QA agent)
- Documented risk-based testing strategy for FloDoc
- Included quality gate decisions and success metrics
- Added example development session workflow
KEY ADDITIONS:
- Section: Enhanced IDE Development Workflow
- Test Architect commands: *risk, *design, *trace, *nfr, *review, *gate
- Quality gate statuses: PASS/CONCERNS/FAIL/WAIVED
- Brownfield-specific testing requirements
- Complete development cycle flow
WHY THIS MATTERS:
- FloDoc is a brownfield enhancement (risks existing functionality)
- 3-portal integration is complex
- Security is critical (POPIA, sponsor portal)
- Performance must be maintained (<20% degradation)
- Zero regression defects required
NEXT STEPS:
1. All changes committed
2. Ready to merge to master
3. Branch cleanup after merge
All documentation complete and ready for development implementation.
pull/565/head
NeoSkosana
2 months ago
parent
6b92b2a58d
commit
5f897dd48b
@ -0,0 +1,697 @@
|
|||||||
|
# 1. Intro Project Analysis and Context
|
||||||
|
|
||||||
|
## 1.1 SCOPE ASSESSMENT
|
||||||
|
|
||||||
|
**⚠️ SIGNIFICANT ENHANCEMENT - System-Wide Impact**
|
||||||
|
|
||||||
|
This PRD documents a **Major Feature Addition** that transforms the single-portal DocuSeal platform into a specialized 3-portal cohort management system for South African private training institutions.
|
||||||
|
|
||||||
|
**Enhancement Complexity Analysis:**
|
||||||
|
- **Type**: Major Feature Addition (3-Portal Cohort Management)
|
||||||
|
- **Impact**: Significant Impact (substantial existing code changes required)
|
||||||
|
- **Timeline**: Multiple development cycles
|
||||||
|
- **Risk Level**: High (touches core DocuSeal workflows)
|
||||||
|
|
||||||
|
**Why This Requires Full PRD Process:**
|
||||||
|
This is NOT a simple feature addition. The enhancement requires:
|
||||||
|
- New multi-tenant institution architecture
|
||||||
|
- Complex 3-party signature workflows (TP → Students → Sponsor → TP Review)
|
||||||
|
- Three separate portal interfaces with custom UI/UX
|
||||||
|
- State management across multiple entities
|
||||||
|
- Integration with existing DocuSeal form builder and signing infrastructure
|
||||||
|
- Bulk operations and email management rules
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.2 EXISTING PROJECT OVERVIEW
|
||||||
|
|
||||||
|
**Analysis Source**: IDE-based analysis + User requirements clarification
|
||||||
|
|
||||||
|
**Current Project State**:
|
||||||
|
|
||||||
|
FloDoc is built on **DocuSeal** - an open-source document filling and signing platform. The base system provides:
|
||||||
|
|
||||||
|
- **Document Form Builder**: WYSIWYG PDF form field creation with 12 field types (Signature, Date, File, Checkbox, etc.)
|
||||||
|
- **Multi-Submitter Workflows**: Support for multiple signers per document
|
||||||
|
- **Authentication & User Management**: Devise-based authentication with 2FA support
|
||||||
|
- **Email Automation**: SMTP-based automated email notifications
|
||||||
|
- **File Storage**: Flexible storage options (local disk, AWS S3, Google Cloud Storage, Azure Cloud)
|
||||||
|
- **PDF Processing**: HexaPDF for PDF generation, manipulation, and signature embedding
|
||||||
|
- **API & Webhooks**: RESTful API with webhook support for integrations
|
||||||
|
- **Mobile-Optimized UI**: Responsive interface supporting 7 UI languages and signing in 14 languages
|
||||||
|
- **Role-Based Access**: User roles and permissions system (via Cancancan)
|
||||||
|
- **Tech Stack**: Ruby on Rails 3.4.2, Vue.js 3, TailwindCSS 3.4.17, DaisyUI 3.9.4, Sidekiq for background jobs
|
||||||
|
|
||||||
|
**Key Existing Architecture for FloDoc Integration:**
|
||||||
|
- **Templates** = Document templates with form fields
|
||||||
|
- **Submissions** = Document workflows with multiple signers
|
||||||
|
- **Submitters** = Individual participants who sign documents
|
||||||
|
- **Completed Documents** = Final signed PDFs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.3 AVAILABLE DOCUMENTATION ANALYSIS
|
||||||
|
|
||||||
|
**Available Documentation**:
|
||||||
|
- ✅ API Documentation (Node.js, Ruby, Python, PHP, Java, Go, C#, TypeScript, JavaScript)
|
||||||
|
- ✅ Webhook Documentation (Submission, Form, Template webhooks)
|
||||||
|
- ✅ Embedding Documentation (React, Vue, Angular, JavaScript form builders and signing forms)
|
||||||
|
- ✅ Architecture Documentation (docs/current-app-sitemap.md - comprehensive analysis)
|
||||||
|
- ✅ Existing PRD (v1.0) - being replaced by this version
|
||||||
|
- ⚠️ Coding Standards (not present - **requires documentation**)
|
||||||
|
- ⚠️ Technical Debt Analysis (not present - **requires analysis**)
|
||||||
|
|
||||||
|
**Recommendation**: This PRD will serve as the comprehensive planning document. Architecture analysis already completed in separate document.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.4 ENHANCEMENT SCOPE DEFINITION
|
||||||
|
|
||||||
|
**Enhancement Type**: ✅ **Major Feature Addition** (3-Portal Cohort Management System)
|
||||||
|
|
||||||
|
**Enhancement Description**:
|
||||||
|
|
||||||
|
Transform the single-portal DocuSeal platform into a specialized **3-portal cohort management system** for South African private training institutions (Training Providers). The system manages cohorts through a **3-party signature workflow**: TP → Students → Sponsor → TP Review.
|
||||||
|
|
||||||
|
**Core Architecture**:
|
||||||
|
- **Templates = Cohorts**: Each cohort is a DocuSeal template containing all documents and signatory mappings
|
||||||
|
- **Submissions = Students**: Each student within a cohort is a submission with their own document workflow
|
||||||
|
|
||||||
|
**Complete Workflow**:
|
||||||
|
1. **Training Provider (TP) Onboarding**: TP creates account with name, surname, email
|
||||||
|
2. **Cohort Creation** (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)
|
||||||
|
3. **Document Mapping Phase**: TP maps signatories (Learner, Sponsor, TP) to document sections using DocuSeal's existing mapping with tweaks
|
||||||
|
4. **TP Signing Phase**: TP signs first student → system auto-fills/signs remaining students
|
||||||
|
5. **Student Enrollment**: Bulk invite emails sent → students complete assigned docs + upload required files
|
||||||
|
6. **Sponsor Review**: Single sponsor link (one email regardless of multiple assignments) → 3-panel portal (student list | document viewer | student info) → individual or bulk completion
|
||||||
|
7. **TP Review**: TP reviews all completed documents from students and sponsor → finalizes 3-party agreements
|
||||||
|
8. **Download**: Bulk ZIP with structure: Cohort_Name/Student_Name/All_Docs.pdf + Audit_Trail.pdf
|
||||||
|
|
||||||
|
**Key System Behaviors**:
|
||||||
|
- **Single Email Rule**: Sponsor receives ONE email per cohort, regardless of how many students they're assigned to
|
||||||
|
- **TP Initiates Signing**: TP starts the signing workflow BEFORE students and sponsor
|
||||||
|
- **Bulk Operations**: TP can fill once and replicate for all students
|
||||||
|
|
||||||
|
**Impact Assessment**: ✅ **Significant Impact** (substantial existing code changes)
|
||||||
|
|
||||||
|
**Rationale for Impact Level**:
|
||||||
|
- **Single Institution Model**: One training institution manages multiple cohorts (NOT multi-tenant)
|
||||||
|
- **Ad-hoc Access**: Students and sponsors access via email links without creating accounts
|
||||||
|
- **New Domain Models**: Cohort, CohortEnrollment, Institution (single), Sponsor (ad-hoc)
|
||||||
|
- **Complex Workflow State Management**: TP → Students → Sponsor → TP Review with state tracking
|
||||||
|
- **Three Portal Interfaces**: Custom portals for TP (admin), Students, and Sponsor
|
||||||
|
- **Integration with DocuSeal**: Leverages existing form builder and signing infrastructure
|
||||||
|
- **Email Management Rules**: Single email per sponsor (no duplicates), bulk operations
|
||||||
|
- **Dashboard & Analytics**: Real-time cohort status tracking
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.5 GOALS AND BACKGROUND CONTEXT
|
||||||
|
|
||||||
|
**Goals**:
|
||||||
|
|
||||||
|
- Enable private training institutions to digitally manage training program cohorts from creation to completion
|
||||||
|
- Streamline multi-party document workflows (TP → Students → Sponsor → TP Review)
|
||||||
|
- Provide role-based portals tailored to each participant's specific needs and permissions
|
||||||
|
- Maintain 100% backward compatibility with core DocuSeal form builder and signing capabilities
|
||||||
|
- Reduce document processing time from weeks to days through automated workflows
|
||||||
|
- Provide real-time visibility into cohort and student submission status
|
||||||
|
- Implement single-email rule for sponsors (no duplicate emails)
|
||||||
|
- Enable bulk operations for TP and Sponsor to reduce repetitive work
|
||||||
|
|
||||||
|
**Background Context**:
|
||||||
|
|
||||||
|
South African private training institutions currently manage learnerships, internships, and candidacy programs through manual, paper-intensive processes. Each program requires collecting student documents (matric certificates, IDs, disability docs, qualifications), getting program agreements filled and signed by multiple parties (student, sponsor, institution), and tracking completion across dozens of students per cohort.
|
||||||
|
|
||||||
|
This manual process is time-consuming (taking weeks), error-prone, lacks visibility into status, and requires physical document handling. FloDoc leverages DocuSeal's proven document signing platform to create a specialized workflow that automates this process while maintaining the flexibility and power of DocuSeal's core form builder and signing engine.
|
||||||
|
|
||||||
|
The enhancement adds a cohort management layer on top of DocuSeal, creating three specialized portals that work with the existing document infrastructure rather than replacing it. Institutions continue using DocuSeal's form builder to create agreement templates, but now have a structured workflow for managing batches of students through the document submission and signing process.
|
||||||
|
|
||||||
|
**Critical Requirements from User Clarification**:
|
||||||
|
- Templates represent cohorts, submissions represent students
|
||||||
|
- TP initiates signing BEFORE students and sponsor
|
||||||
|
- Sponsor receives ONE email per cohort (no duplicates)
|
||||||
|
- TP Review phase after sponsor completion (not TP Finalization)
|
||||||
|
- Bulk operations: fill once, replicate for all students
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.6 CHANGE LOG
|
||||||
|
|
||||||
|
| Change | Date | Version | Description | Author |
|
||||||
|
|--------|------|---------|-------------|--------|
|
||||||
|
| Initial PRD Creation | 2025-01-01 | v1.0 | Brownfield enhancement for 3-portal cohort management | PM Agent |
|
||||||
|
| **PRD v2.0 - Fresh Start** | 2026-01-10 | v2.0 | Complete rewrite with clarified workflow requirements | User + PM |
|
||||||
|
| **Section 1 Complete** | 2026-01-10 | v2.0 | Intro Analysis with validated understanding | PM |
|
||||||
|
| **PO Validation Fixes** | 2026-01-14 | v2.1 | Addressed 3 blocking issues, added scope declaration | PO/PM |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.7 SCOPE BOUNDARIES & DEPLOYMENT STRATEGY
|
||||||
|
|
||||||
|
**Deployment Decision:** ✅ **Local Docker MVP Only** (Option A)
|
||||||
|
|
||||||
|
**Rationale:**
|
||||||
|
- Management wants to validate FloDoc system locally first
|
||||||
|
- Defers production infrastructure investment until MVP proven
|
||||||
|
- Fastest path to working demo
|
||||||
|
- No cloud costs during validation phase
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### In Scope (MVP - Local Docker)
|
||||||
|
|
||||||
|
**Core Functionality:**
|
||||||
|
- ✅ Local Docker development environment (PostgreSQL, Redis, Minio, MailHog)
|
||||||
|
- ✅ 3-portal cohort management workflow
|
||||||
|
- ✅ Single institution support
|
||||||
|
- ✅ All 21 implementation stories (Epics 1-7)
|
||||||
|
- ✅ Demo validation with sample data (Story 8.0.1)
|
||||||
|
|
||||||
|
**Technical:**
|
||||||
|
- ✅ Database schema for 3 new tables
|
||||||
|
- ✅ RESTful API with `/api/v1/flodoc/` namespace
|
||||||
|
- ✅ Vue.js 3 portals with TailwindCSS
|
||||||
|
- ✅ Email notifications (via MailHog)
|
||||||
|
- ✅ PDF generation and signing (HexaPDF)
|
||||||
|
- ✅ Excel export (rubyXL)
|
||||||
|
- ✅ Background jobs (Sidekiq)
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- ✅ End-to-end workflow testing
|
||||||
|
- ✅ Mobile responsiveness testing
|
||||||
|
- ✅ Performance testing (50+ students)
|
||||||
|
- ✅ Security audit (with enhanced checklist)
|
||||||
|
- ✅ User acceptance testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Out of Scope (Post-MVP - Deferred)
|
||||||
|
|
||||||
|
**Production Infrastructure (Stories 8.1-8.4 - Deferred):**
|
||||||
|
- ❌ Production CI/CD pipeline
|
||||||
|
- ❌ Cloud infrastructure (AWS/GCP/Azure)
|
||||||
|
- ❌ Infrastructure as Code (Terraform)
|
||||||
|
- ❌ DNS/domain registration
|
||||||
|
- ❌ CDN/static asset hosting
|
||||||
|
- ❌ Production monitoring (Sentry, New Relic)
|
||||||
|
- ❌ Analytics and user tracking
|
||||||
|
- ❌ Blue-green deployment
|
||||||
|
- ❌ Production backup strategy
|
||||||
|
|
||||||
|
**User Documentation & Operations (Stories 8.5-8.7 - Deferred):**
|
||||||
|
- ⚠️ **Story 8.5**: User Communication & Training Materials (blocking - must be created before dev)
|
||||||
|
- ❌ **Story 8.6**: In-app help system
|
||||||
|
- ❌ **Story 8.7**: Knowledge transfer plan & operations runbook
|
||||||
|
- ❌ Migration announcement emails
|
||||||
|
- ❌ User training materials
|
||||||
|
- ❌ FAQ and tutorials
|
||||||
|
- ❌ Support team training
|
||||||
|
- ❌ Incident response procedures
|
||||||
|
|
||||||
|
**Future Enhancements:**
|
||||||
|
- ❌ Multi-institution support
|
||||||
|
- ❌ Advanced analytics dashboard
|
||||||
|
- ❌ Custom branding
|
||||||
|
- ❌ Additional portal features
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Production Path Forward
|
||||||
|
|
||||||
|
**After Local Validation Success:**
|
||||||
|
1. Decision point: Proceed to production or iterate on MVP
|
||||||
|
2. If proceeding: Create Stories 8.1-8.4 (production infrastructure)
|
||||||
|
3. Implement Stories 8.5-8.7 (documentation & KT)
|
||||||
|
4. Deploy to production environment
|
||||||
|
|
||||||
|
**Note:** Production deployment is **NOT** part of current scope. All production-related work is deferred pending successful local validation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Scope Acknowledgment
|
||||||
|
|
||||||
|
**Current State:** Local Docker MVP ready for development
|
||||||
|
**Target State:** Working demo with 3-portal workflow
|
||||||
|
**Production Readiness:** Deferred to post-MVP phase
|
||||||
|
|
||||||
|
This scope declaration addresses PO Validation Issue #1 (Production Deployment Strategy Undefined).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1.8 EXTENSIBILITY PATTERNS (Optional Enhancement)
|
||||||
|
|
||||||
|
**Status**: Draft - Reference Documentation
|
||||||
|
**Priority**: Medium (Post-MVP)
|
||||||
|
**Purpose**: Guide future development and customization
|
||||||
|
|
||||||
|
This section documents how to extend the FloDoc system for future enhancements.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.1 Adding New Portal Types
|
||||||
|
|
||||||
|
**Current Pattern**: 3 portals (TP, Student, Sponsor) with ad-hoc token authentication
|
||||||
|
|
||||||
|
**Extension Steps:**
|
||||||
|
|
||||||
|
1. **Create Portal Controller** (app/controllers/flodoc/portals/):
|
||||||
|
```ruby
|
||||||
|
# app/controllers/flodoc/portals/new_portal_controller.rb
|
||||||
|
class Flodoc::Portals::NewPortalController < ApplicationController
|
||||||
|
before_action :authenticate_token!
|
||||||
|
|
||||||
|
def dashboard
|
||||||
|
# Uses token-based auth like Student/Sponsor portals
|
||||||
|
@data = NewPortalService.load_data(@token)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Add Token Model** (if new token type needed):
|
||||||
|
```ruby
|
||||||
|
# app/models/flodoc/new_portal_token.rb
|
||||||
|
class Flodoc::NewPortalToken < ApplicationRecord
|
||||||
|
belongs_to :cohort
|
||||||
|
has_secure_token :token
|
||||||
|
validates :email, presence: true, uniqueness: { scope: :cohort_id }
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Add Vue Portal** (app/javascript/new_portal/):
|
||||||
|
```typescript
|
||||||
|
// app/javascript/new_portal/application.js
|
||||||
|
import { createApp } from 'vue'
|
||||||
|
import NewPortalApp from './NewPortalApp.vue'
|
||||||
|
|
||||||
|
createApp(NewPortalApp).mount('#app')
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Update Routes** (config/routes.rb):
|
||||||
|
```ruby
|
||||||
|
namespace :new_portal do
|
||||||
|
get 'dashboard', to: 'dashboard#index'
|
||||||
|
post 'submit', to: 'submissions#create'
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.2 Extending Cohort State Machine
|
||||||
|
|
||||||
|
**Current States**: `draft` → `active` → `completed` → `finalized`
|
||||||
|
|
||||||
|
**Adding New State:**
|
||||||
|
|
||||||
|
1. **Update State Enum** (app/models/flodoc/cohort.rb):
|
||||||
|
```ruby
|
||||||
|
class Flodoc::Cohort < ApplicationRecord
|
||||||
|
STATES = %w[draft active completed finalized under_review].freeze
|
||||||
|
enum status: STATES.index_with(&:to_s)
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Add State Transition Logic**:
|
||||||
|
```ruby
|
||||||
|
# app/models/flodoc/cohort.rb
|
||||||
|
def can_under_review?
|
||||||
|
completed? && all_sponsors_signed?
|
||||||
|
end
|
||||||
|
|
||||||
|
def under_review!
|
||||||
|
update!(status: 'under_review')
|
||||||
|
Flodoc::CohortMailer.under_review_notification(self).deliver_later
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Update Portal UI** (app/javascript/tp_portal/views/CohortDetail.vue):
|
||||||
|
```vue
|
||||||
|
<template>
|
||||||
|
<div v-if="cohort.status === 'under_review'">
|
||||||
|
<!-- New UI for review state -->
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.3 Adding New Document Types
|
||||||
|
|
||||||
|
**Current**: PDF documents with form fields
|
||||||
|
|
||||||
|
**Extension Pattern:**
|
||||||
|
|
||||||
|
1. **Create Document Type Model**:
|
||||||
|
```ruby
|
||||||
|
# app/models/flodoc/document_type.rb
|
||||||
|
class Flodoc::DocumentType < ApplicationRecord
|
||||||
|
validates :name, presence: true
|
||||||
|
validates :handler, presence: true
|
||||||
|
|
||||||
|
# handler values: 'pdf', 'docx', 'spreadsheet', 'custom'
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Register Handler**:
|
||||||
|
```ruby
|
||||||
|
# config/initializers/flodoc_document_types.rb
|
||||||
|
Flodoc::DocumentType.register_handler('spreadsheet', Flodoc::SpreadsheetHandler)
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Implement Handler**:
|
||||||
|
```ruby
|
||||||
|
# app/services/flodoc/handlers/spreadsheet_handler.rb
|
||||||
|
module Flodoc
|
||||||
|
module Handlers
|
||||||
|
class SpreadsheetHandler
|
||||||
|
def self.generate(cohort, data)
|
||||||
|
# Custom generation logic
|
||||||
|
end
|
||||||
|
|
||||||
|
def self.validate(file)
|
||||||
|
# Custom validation logic
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.4 Extending the API
|
||||||
|
|
||||||
|
**Current**: `/api/v1/flodoc/` namespace
|
||||||
|
|
||||||
|
**Adding New Endpoint:**
|
||||||
|
|
||||||
|
1. **Create API Controller**:
|
||||||
|
```ruby
|
||||||
|
# app/controllers/api/v1/flodoc/new_feature_controller.rb
|
||||||
|
class Api::V1::Flodoc::NewFeatureController < Api::V1::BaseController
|
||||||
|
def index
|
||||||
|
# Uses JWT authentication from base controller
|
||||||
|
render json: { data: 'example' }
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Add Route**:
|
||||||
|
```ruby
|
||||||
|
# config/routes.rb
|
||||||
|
namespace :api do
|
||||||
|
namespace :v1 do
|
||||||
|
namespace :flodoc do
|
||||||
|
get 'new_feature', to: 'new_feature#index'
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Update API Documentation**:
|
||||||
|
```markdown
|
||||||
|
### GET /api/v1/flodoc/new_feature
|
||||||
|
|
||||||
|
**Authentication**: Bearer JWT token
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": "example"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.5 Adding New Authentication Providers
|
||||||
|
|
||||||
|
**Current**: Email-based ad-hoc tokens for students/sponsors
|
||||||
|
|
||||||
|
**Adding OAuth Provider:**
|
||||||
|
|
||||||
|
1. **Add OmniAuth Strategy** (Gemfile):
|
||||||
|
```ruby
|
||||||
|
gem 'omniauth-google-oauth2'
|
||||||
|
gem 'omniauth-saml' # For enterprise SSO
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Configure Provider** (config/initializers/omniauth.rb):
|
||||||
|
```ruby
|
||||||
|
Rails.application.config.middleware.use OmniAuth::Builder do
|
||||||
|
provider :google_oauth2, ENV['GOOGLE_CLIENT_ID'], ENV['GOOGLE_CLIENT_SECRET']
|
||||||
|
provider :saml,
|
||||||
|
issuer: 'flodoc',
|
||||||
|
idp_sso_target_url: ENV['SAML_SSO_URL']
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Create Authentication Handler**:
|
||||||
|
```ruby
|
||||||
|
# app/services/flodoc/auth/oauth_handler.rb
|
||||||
|
module Flodoc
|
||||||
|
module Auth
|
||||||
|
class OAuthHandler
|
||||||
|
def self.authenticate(provider, auth_hash)
|
||||||
|
user = User.find_or_create_by(email: auth_hash.info.email) do |u|
|
||||||
|
u.password = SecureRandom.hex(16)
|
||||||
|
u.name = auth_hash.info.name
|
||||||
|
end
|
||||||
|
# Generate portal-specific token
|
||||||
|
Flodoc::PortalToken.create!(user: user, provider: provider)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.6 Customizing UI Components
|
||||||
|
|
||||||
|
**Current**: Vue 3 + TailwindCSS 3.4.17 + DaisyUI 3.9.4
|
||||||
|
|
||||||
|
**Customization Pattern:**
|
||||||
|
|
||||||
|
1. **Override Design Tokens** (app/javascript/design-system/tailwind.config.js):
|
||||||
|
```javascript
|
||||||
|
module.exports = {
|
||||||
|
theme: {
|
||||||
|
extend: {
|
||||||
|
colors: {
|
||||||
|
flodoc: {
|
||||||
|
primary: '#1e3a8a', // Custom blue
|
||||||
|
accent: '#f59e0b', // Custom amber
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Create Custom Component**:
|
||||||
|
```vue
|
||||||
|
<!-- app/javascript/elements/FlodocCustomButton.vue -->
|
||||||
|
<template>
|
||||||
|
<button
|
||||||
|
:class="['btn', `btn-${variant}`, customClass]"
|
||||||
|
@click="$emit('click')"
|
||||||
|
>
|
||||||
|
<slot />
|
||||||
|
</button>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<script setup>
|
||||||
|
defineProps({
|
||||||
|
variant: { type: String, default: 'primary' },
|
||||||
|
customClass: { type: String, default: '' }
|
||||||
|
})
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<style scoped>
|
||||||
|
.btn-primary {
|
||||||
|
@apply bg-flodoc-primary text-white hover:bg-blue-800;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Register Globally**:
|
||||||
|
```javascript
|
||||||
|
// app/javascript/application.js
|
||||||
|
import FlodocCustomButton from './elements/FlodocCustomButton.vue'
|
||||||
|
app.component('FlodocCustomButton', FlodocCustomButton)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.7 Extending Background Jobs
|
||||||
|
|
||||||
|
**Current**: Sidekiq queues for emails, webhooks, PDF generation
|
||||||
|
|
||||||
|
**Adding New Job Type:**
|
||||||
|
|
||||||
|
1. **Create Job**:
|
||||||
|
```ruby
|
||||||
|
# app/jobs/flodoc/custom_analysis_job.rb
|
||||||
|
class Flodoc::CustomAnalysisJob < ApplicationJob
|
||||||
|
queue_as :analytics
|
||||||
|
|
||||||
|
def perform(cohort_id)
|
||||||
|
cohort = Flodoc::Cohort.find(cohort_id)
|
||||||
|
# Custom analysis logic
|
||||||
|
Flodoc::AnalysisReport.generate(cohort)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Enqueue Job**:
|
||||||
|
```ruby
|
||||||
|
# In any service or controller
|
||||||
|
Flodoc::CustomAnalysisJob.perform_later(@cohort.id)
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Monitor in Sidekiq**:
|
||||||
|
```ruby
|
||||||
|
# config/sidekiq.yml
|
||||||
|
:queues:
|
||||||
|
- default
|
||||||
|
- mailers
|
||||||
|
- webhooks
|
||||||
|
- pdf
|
||||||
|
- analytics # New queue
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.8 Adding Custom Validations
|
||||||
|
|
||||||
|
**Current**: Standard Rails validations
|
||||||
|
|
||||||
|
**Custom Validation Pattern:**
|
||||||
|
|
||||||
|
1. **Create Validator**:
|
||||||
|
```ruby
|
||||||
|
# app/validators/flodoc/sponsor_email_validator.rb
|
||||||
|
class Flodoc::SponsorEmailValidator < ActiveModel::Validator
|
||||||
|
def validate(record)
|
||||||
|
unless record.email.end_with?('@company.com')
|
||||||
|
record.errors.add(:email, 'must be a company email')
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Use in Model**:
|
||||||
|
```ruby
|
||||||
|
# app/models/flodoc/submitter.rb
|
||||||
|
class Flodoc::Submitter < ApplicationRecord
|
||||||
|
validates_with Flodoc::SponsorEmailValidator, if: :sponsor?
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.9 Database Extension Patterns
|
||||||
|
|
||||||
|
**Adding New Tables:**
|
||||||
|
|
||||||
|
1. **Migration**:
|
||||||
|
```ruby
|
||||||
|
# db/migrate/20260114120000_create_flodoc_custom_data.rb
|
||||||
|
class CreateFlodocCustomData < ActiveRecord::Migration[7.0]
|
||||||
|
def change
|
||||||
|
create_table :flodoc_custom_data do |t|
|
||||||
|
t.references :cohort, null: false, foreign_key: true
|
||||||
|
t.jsonb :data
|
||||||
|
t.timestamps
|
||||||
|
end
|
||||||
|
|
||||||
|
add_index :flodoc_custom_data, [:cohort_id, :created_at]
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Model**:
|
||||||
|
```ruby
|
||||||
|
# app/models/flodoc/custom_datum.rb
|
||||||
|
class Flodoc::CustomDatum < ApplicationRecord
|
||||||
|
belongs_to :cohort
|
||||||
|
validates :data, presence: true
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.10 Event System Extension
|
||||||
|
|
||||||
|
**Current**: SubmissionEvents for audit trail
|
||||||
|
|
||||||
|
**Adding Custom Events:**
|
||||||
|
|
||||||
|
1. **Define Event Types**:
|
||||||
|
```ruby
|
||||||
|
# app/models/flodoc/event_type.rb
|
||||||
|
class Flodoc::EventType < ApplicationRecord
|
||||||
|
TYPES = %w[
|
||||||
|
cohort_created
|
||||||
|
cohort_completed
|
||||||
|
submitter_signed
|
||||||
|
sponsor_invited
|
||||||
|
document_downloaded
|
||||||
|
custom_alert_sent # New event
|
||||||
|
].freeze
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Track Custom Events**:
|
||||||
|
```ruby
|
||||||
|
# app/services/flodoc/event_tracker.rb
|
||||||
|
module Flodoc
|
||||||
|
class EventTracker
|
||||||
|
def self.track(cohort, event_type, user, metadata = {})
|
||||||
|
Flodoc::SubmissionEvent.create!(
|
||||||
|
cohort: cohort,
|
||||||
|
event_type: event_type,
|
||||||
|
user: user,
|
||||||
|
metadata: metadata
|
||||||
|
)
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Query Events**:
|
||||||
|
```ruby
|
||||||
|
# In reports or analytics
|
||||||
|
Flodoc::SubmissionEvent
|
||||||
|
.where(cohort_id: cohort.id)
|
||||||
|
.where(event_type: 'custom_alert_sent')
|
||||||
|
.where('created_at > ?', 30.days.ago)
|
||||||
|
.count
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1.8.11 Integration Checklist
|
||||||
|
|
||||||
|
When extending FloDoc, verify:
|
||||||
|
|
||||||
|
- ✅ **Security**: New endpoints use JWT/auth tokens
|
||||||
|
- ✅ **Multi-tenancy**: Check single-institution vs multi-institution
|
||||||
|
- ✅ **Database**: Proper foreign keys and indexes
|
||||||
|
- ✅ **Background Jobs**: Sidekiq queue exists
|
||||||
|
- ✅ **API Versioning**: Use `/api/v1/flodoc/` namespace
|
||||||
|
- ✅ **Vue Components**: Follow design system (FR28)
|
||||||
|
- ✅ **Testing**: RSpec coverage for new code
|
||||||
|
- ✅ **Rollback**: Migration can be reversed
|
||||||
|
- ✅ **Documentation**: Update this extensibility guide
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Note**: This is optional documentation for future development. All current stories (1.1-8.0.1) are complete and ready for implementation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
@ -0,0 +1,118 @@
|
|||||||
|
# 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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
@ -0,0 +1,139 @@
|
|||||||
|
# 3. User Interface Enhancement Goals
|
||||||
|
|
||||||
|
## 3.1 Integration with Existing UI
|
||||||
|
|
||||||
|
**Design System Migration**:
|
||||||
|
The three portals will use a **custom TailwindCSS design system** replacing DaisyUI (CR3), while maintaining the same responsive design principles and mobile-first approach as the existing DocuSeal interface. The new design system will:
|
||||||
|
|
||||||
|
- **Preserve Core UX Patterns**: Maintain familiar interaction patterns from DocuSeal (form builders, signing flows, modal dialogs)
|
||||||
|
- **Enhance Accessibility**: WCAG 2.1 AA compliance for all portals
|
||||||
|
- **Support Dark/Light Mode**: Consistent with existing DocuSeal theme support
|
||||||
|
- **Language Support**: Maintain existing i18n infrastructure for 7 UI languages
|
||||||
|
|
||||||
|
**Visual Consistency**:
|
||||||
|
- **Color Palette**: Extend DocuSeal's existing brand colors with cohort-specific accent colors for status indicators
|
||||||
|
- **Typography**: Use existing font stack for consistency
|
||||||
|
- **Iconography**: Leverage existing icon library or extend with cohort-specific icons
|
||||||
|
- **Spacing & Layout**: Follow existing 8px grid system and spacing conventions
|
||||||
|
|
||||||
|
**Development Mandate - Design System Compliance**:
|
||||||
|
**CRITICAL**: During frontend development, the Dev Agent (James) MUST strictly adhere to the FloDoc design system specification located at `.claude/skills/frontend-design/SKILL.md` and the visual assets in `.claude/skills/frontend-design/design-system/`. This includes:
|
||||||
|
|
||||||
|
- **Color System**: Extract primary, secondary, neutral, and accent colors from `design-system/Colors and shadows/Brand colors/` and `Complementary colors/` SVG/JPG specifications
|
||||||
|
- **Typography**: Follow `design-system/Typography/typoraphy.txt` and `design-system/Fonts/fonts.txt` for font families, sizes, weights, and line heights
|
||||||
|
- **Component Library**: Use atomic design components from `design-system/Atoms/` (Buttons, Inputs, Checkboxes, Menus, Progress Tags, etc.)
|
||||||
|
- **Iconography**: Source all icons from `design-system/Icons/` organized by category (security, users, files, notifications, etc.)
|
||||||
|
- **Brand Assets**: Reference `design-system/Logo/` for all logo variations
|
||||||
|
- **Shadows & Elevation**: Apply shadow styles from `design-system/Colors and shadows/Shadows/`
|
||||||
|
|
||||||
|
**Agent Coordination**:
|
||||||
|
- **Dev Agent (James)**: Must reference the design system folder before writing any frontend code. All Vue components, TailwindCSS classes, and styling decisions must align with the design system specifications.
|
||||||
|
- **Scrum Master (Bob)**: Must be aware of this design system requirement during story creation and acceptance criteria definition. Frontend stories should include verification that all UI elements conform to the design system specifications.
|
||||||
|
|
||||||
|
**Consequences of Non-Compliance**: UI elements not derived from the design system will be rejected during code review. The design system is the single source of truth for all visual decisions.
|
||||||
|
|
||||||
|
## 3.2 Modified/New Screens and Views
|
||||||
|
|
||||||
|
### TP Portal (Admin Interface)
|
||||||
|
|
||||||
|
**New Screens**:
|
||||||
|
1. **Institution Onboarding** - Single-page form for initial TP setup
|
||||||
|
2. **Cohort Dashboard** - Main landing with cohort list, status cards, and quick actions
|
||||||
|
3. **Cohort Creation Wizard** - 5-step multi-form:
|
||||||
|
- Step 1: Basic Info (name, program type)
|
||||||
|
- Step 2: Student Management (email entry/bulk upload)
|
||||||
|
- Step 3: Sponsor Configuration (single email, notification settings)
|
||||||
|
- Step 4: Document Upload (SETA agreement + supporting docs)
|
||||||
|
- Step 5: Student Upload Requirements (ID, Matric, Tertiary Qualifications)
|
||||||
|
4. **Document Mapping Interface** - Visual drag-and-drop for signatory assignment
|
||||||
|
5. **TP Signing Interface** - Single signing flow with "apply to all students" option
|
||||||
|
6. **Student Enrollment Status** - Bulk invite management and tracking
|
||||||
|
7. **Sponsor Access Monitor** - Real-time dashboard showing which sponsors have accessed their portal, when they last logged in, which students they've reviewed, and current pending actions. Prevents duplicate email sends and allows TP to intervene if sponsor hasn't accessed after notification.
|
||||||
|
8. **TP Review Dashboard** - 3-panel review interface:
|
||||||
|
- **Left Panel**: Student list with completion status (Waiting for Student, Waiting for Sponsor, Complete)
|
||||||
|
- **Middle Panel**: Full document viewer showing the selected student's completed documents
|
||||||
|
- **Right Panel**: Verification controls - approve/reject individual documents, add verification notes, mark student as verified
|
||||||
|
9. **Cohort Analytics** - Completion rates, timeline, bottlenecks
|
||||||
|
10. **Excel Export Interface** - Data selection and export configuration
|
||||||
|
|
||||||
|
**Modified Existing Screens**:
|
||||||
|
- **Template Builder** - Enhanced with cohort-specific metadata fields
|
||||||
|
- **User Settings** - Institution role management added
|
||||||
|
|
||||||
|
### Student Portal
|
||||||
|
|
||||||
|
**New Screens**:
|
||||||
|
1. **Student Invitation Landing** - Accept cohort invitation, view requirements
|
||||||
|
2. **Document Upload Interface** - Multi-file upload with validation
|
||||||
|
3. **Student Signing Flow** - DocuSeal signing form with document preview
|
||||||
|
4. **Submission Status** - Real-time progress tracking
|
||||||
|
5. **Completion Confirmation** - Summary of submitted documents
|
||||||
|
|
||||||
|
**Modified Existing Screens**:
|
||||||
|
- **Submission Form** - Rebranded for cohort context, simplified navigation
|
||||||
|
|
||||||
|
### Sponsor Portal
|
||||||
|
|
||||||
|
**New Screens**:
|
||||||
|
1. **Cohort Dashboard** - Overview of all students in cohort with bulk signing capability
|
||||||
|
2. **Student List View** - Searchable, filterable list of students with status indicators
|
||||||
|
3. **Signature Capture Interface** - Two methods for signature: draw on canvas or type name
|
||||||
|
4. **Bulk Signing Preview** - Confirmation modal showing all affected students before signing
|
||||||
|
5. **Success Confirmation** - Post-signing summary with next steps
|
||||||
|
|
||||||
|
**Modified Existing Screens**:
|
||||||
|
- **Signing Form** - Enhanced for bulk cohort signing workflow
|
||||||
|
|
||||||
|
## 3.3 UI Consistency Requirements
|
||||||
|
|
||||||
|
**Portal-Specific Requirements**:
|
||||||
|
|
||||||
|
**TP Portal**:
|
||||||
|
- **Admin-First Design**: Complex operations made simple through progressive disclosure
|
||||||
|
- **Bulk Operations**: Prominent "fill once, apply to all" patterns
|
||||||
|
- **Status Visualization**: Color-coded cohort states (Pending, In Progress, Ready for Sponsor, Complete)
|
||||||
|
- **Action History**: Audit trail visible within interface
|
||||||
|
|
||||||
|
**What is Progressive Disclosure?**
|
||||||
|
This is a UX pattern that hides complexity until the user needs it. For the TP Portal, this means:
|
||||||
|
- **Default View**: Show only essential actions (Create Cohort, View Active Cohorts, Export Data)
|
||||||
|
- **On-Demand Complexity**: Advanced features (detailed analytics, bulk email settings, custom document mappings) are revealed only when users click "Advanced Options" or navigate to specific sections
|
||||||
|
- **Example**: The Cohort Creation Wizard (5 steps) uses progressive disclosure - each step shows only the fields needed for that step, preventing overwhelming the user with all 20+ fields at once
|
||||||
|
- **Benefit**: Reduces cognitive load for new users while keeping power features accessible for experienced admins
|
||||||
|
|
||||||
|
**Student Portal**:
|
||||||
|
- **Mobile-First**: Optimized for smartphone access
|
||||||
|
- **Minimal Steps**: Maximum 3 clicks to complete any document
|
||||||
|
- **Clear Requirements**: Visual checklist of required vs. optional documents
|
||||||
|
- **Progress Indicators**: Step-by-step completion tracking
|
||||||
|
|
||||||
|
**Sponsor Portal**:
|
||||||
|
- **Review-Optimized**: Keyboard shortcuts for document navigation
|
||||||
|
- **Bulk Actions**: "Sign All" and "Bulk Review" modes
|
||||||
|
- **Document Comparison**: Side-by-side view capability
|
||||||
|
- **No Account Required**: Email-link only access pattern
|
||||||
|
- **Progress Tracking**: Persistent progress bar showing completion status (e.g., "3/15 students completed - 20%") with visual indicator
|
||||||
|
- **Tab-Based Navigation**: Pending/Completed tabs for clear workflow separation
|
||||||
|
|
||||||
|
**Cross-Portal Consistency**:
|
||||||
|
- **Navigation**: All portals use consistent header/navigation patterns
|
||||||
|
- **Notifications**: Toast notifications for state changes
|
||||||
|
- **Error Handling**: Consistent error message formatting and recovery options
|
||||||
|
- **Loading States**: Skeleton screens and spinners for async operations
|
||||||
|
- **Empty States**: Helpful guidance when no cohorts/students/documents exist
|
||||||
|
|
||||||
|
**Mobile Responsiveness**:
|
||||||
|
- **Breakpoints**: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
|
||||||
|
- **Touch Targets**: Minimum 44x44px for all interactive elements
|
||||||
|
- **Tablet Optimization**: 3-panel sponsor portal collapses to 2-panel on tablets
|
||||||
|
- **Vertical Layout**: All portals stack vertically on mobile devices
|
||||||
|
|
||||||
|
**Accessibility Standards**:
|
||||||
|
- **Keyboard Navigation**: Full keyboard support for all portals
|
||||||
|
- **Screen Readers**: ARIA labels and semantic HTML throughout
|
||||||
|
- **Focus Management**: Clear focus indicators and logical tab order
|
||||||
|
- **Color Contrast**: Minimum 4.5:1 ratio for all text
|
||||||
|
- **Reduced Motion**: Respect user's motion preferences
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
@ -0,0 +1,326 @@
|
|||||||
|
# 4. Technical Constraints and Integration Requirements
|
||||||
|
|
||||||
|
## 4.1 Existing Technology Stack
|
||||||
|
|
||||||
|
**Based on Architecture Analysis** (docs/current-app-sitemap.md):
|
||||||
|
|
||||||
|
**Languages:**
|
||||||
|
- Ruby 3.4.2
|
||||||
|
- JavaScript (Vue.js 3)
|
||||||
|
- HTML/CSS (TailwindCSS 3.4.17)
|
||||||
|
|
||||||
|
**Frameworks:**
|
||||||
|
- Ruby on Rails 7.x (with Shakapacker 8.0)
|
||||||
|
- Vue.js 3 with Composition API
|
||||||
|
- Devise for authentication
|
||||||
|
- Cancancan for authorization
|
||||||
|
- Sidekiq for background processing
|
||||||
|
|
||||||
|
**Database:**
|
||||||
|
- PostgreSQL/MySQL/SQLite (configured via DATABASE_URL)
|
||||||
|
- Redis for Sidekiq job queue
|
||||||
|
|
||||||
|
**Infrastructure:**
|
||||||
|
- Puma web server
|
||||||
|
- Active Storage (S3, Google Cloud, Azure, or local disk)
|
||||||
|
- SMTP server for email delivery
|
||||||
|
|
||||||
|
**External Dependencies:**
|
||||||
|
- HexaPDF (PDF generation and signing)
|
||||||
|
- PDFium (PDF rendering)
|
||||||
|
- rubyXL (Excel export - **to be added**)
|
||||||
|
- Ngrok (for local testing with public URLs)
|
||||||
|
|
||||||
|
**Key Libraries & Gems:**
|
||||||
|
- `devise` - Authentication
|
||||||
|
- `devise-two-factor` - 2FA support
|
||||||
|
- `cancancan` - Authorization
|
||||||
|
- `sidekiq` - Background jobs
|
||||||
|
- `hexapdf` - PDF processing
|
||||||
|
- `prawn` - PDF generation (alternative)
|
||||||
|
- `rubyXL` - Excel file generation (**required for FR23**)
|
||||||
|
|
||||||
|
## 4.2 Integration Approach
|
||||||
|
|
||||||
|
**Database Integration Strategy:**
|
||||||
|
- **New Tables Only**: Create `cohorts`, `cohort_enrollments`, `institutions`, `sponsors` tables
|
||||||
|
- **Foreign Keys**: Link to existing `templates`, `submissions`, `users` tables
|
||||||
|
- **No Schema Modifications**: Existing DocuSeal tables remain unchanged
|
||||||
|
- **Migration Safety**: All migrations must be reversible
|
||||||
|
- **Data Isolation**: Use `institution_id` scoping for all FloDoc queries
|
||||||
|
|
||||||
|
**API Integration Strategy:**
|
||||||
|
- **Namespace Extension**: Add `/api/v1/flodoc/` namespace for new endpoints
|
||||||
|
- **Pattern Consistency**: Follow existing DocuSeal REST conventions
|
||||||
|
- **Authentication**: Reuse existing Devise + JWT infrastructure
|
||||||
|
- **Rate Limiting**: Apply existing rate limits to new endpoints
|
||||||
|
- **Webhook Compatibility**: New cohort events trigger existing webhook infrastructure
|
||||||
|
|
||||||
|
**Frontend Integration Strategy:**
|
||||||
|
- **Vue.js Architecture**: Extend existing Vue 3 app with new portal components
|
||||||
|
- **Design System**: Replace DaisyUI with custom TailwindCSS (per CR3)
|
||||||
|
- **Component Structure**: Create new portal-specific components in `app/javascript/cohorts/`
|
||||||
|
- **Routing**: Use existing Vue Router with new portal routes
|
||||||
|
- **State Management**: Vuex or Pinia for cohort state (to be determined)
|
||||||
|
- **No Breaking Changes**: Existing DocuSeal UI remains functional
|
||||||
|
|
||||||
|
**Testing Integration Strategy:**
|
||||||
|
- **RSpec**: Extend existing test suite with new model/request specs
|
||||||
|
- **System Tests**: Add Capybara tests for 3-portal workflows
|
||||||
|
- **Vue Test Utils**: Component tests for new portal interfaces
|
||||||
|
- **FactoryBot**: Create factories for new models
|
||||||
|
- **Existing Tests**: All DocuSeal tests must continue passing
|
||||||
|
|
||||||
|
## 4.3 Code Organization and Standards
|
||||||
|
|
||||||
|
**File Structure Approach:**
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── models/
|
||||||
|
│ ├── cohort.rb # New: Cohort management
|
||||||
|
│ ├── cohort_enrollment.rb # New: Student enrollment tracking
|
||||||
|
│ ├── institution.rb # New: Single institution model
|
||||||
|
│ ├── sponsor.rb # New: Ad-hoc sponsor model
|
||||||
|
│ └── concerns/
|
||||||
|
│ └── user_flo_doc_additions.rb # New: User model extension
|
||||||
|
│
|
||||||
|
├── controllers/
|
||||||
|
│ ├── api/
|
||||||
|
│ │ └── v1/
|
||||||
|
│ │ ├── flodoc/
|
||||||
|
│ │ │ ├── cohorts_controller.rb
|
||||||
|
│ │ │ ├── enrollments_controller.rb
|
||||||
|
│ │ │ └── excel_export_controller.rb
|
||||||
|
│ │ └── admin/
|
||||||
|
│ │ ├── invitations_controller.rb
|
||||||
|
│ │ └── security_events_controller.rb
|
||||||
|
│ └── cohorts/
|
||||||
|
│ └── admin_controller.rb # Web interface
|
||||||
|
│
|
||||||
|
├── services/
|
||||||
|
│ ├── invitation_service.rb # Admin invitation logic
|
||||||
|
│ ├── cohort_service.rb # Cohort lifecycle management
|
||||||
|
│ ├── sponsor_service.rb # Sponsor access management
|
||||||
|
│ └── excel_export_service.rb # Excel generation (FR23)
|
||||||
|
│
|
||||||
|
├── jobs/
|
||||||
|
│ ├── cohort_admin_invitation_job.rb
|
||||||
|
│ ├── sponsor_access_job.rb
|
||||||
|
│ └── excel_export_job.rb
|
||||||
|
│
|
||||||
|
├── mailers/
|
||||||
|
│ └── cohort_mailer.rb # Cohort-specific emails
|
||||||
|
│
|
||||||
|
└── javascript/
|
||||||
|
└── cohorts/
|
||||||
|
├── portals/
|
||||||
|
│ ├── tp_portal/ # Admin interface
|
||||||
|
│ ├── student_portal/ # Student interface
|
||||||
|
│ └── sponsor_portal/ # Sponsor interface
|
||||||
|
└── components/ # Shared Vue components
|
||||||
|
```
|
||||||
|
|
||||||
|
**Naming Conventions:**
|
||||||
|
- **Models**: `Cohort`, `CohortEnrollment`, `Institution`, `Sponsor` (PascalCase, singular)
|
||||||
|
- **Controllers**: `CohortsController`, `Cohorts::AdminController` (namespaced)
|
||||||
|
- **Services**: `CohortService`, `InvitationService` (PascalCase, descriptive)
|
||||||
|
- **Jobs**: `CohortInvitationJob` (PascalCase, ends with Job)
|
||||||
|
- **Vue Components**: `CohortDashboard.vue`, `SponsorPanel.vue` (PascalCase)
|
||||||
|
- **Variables**: `cohort_enrollments` (snake_case, plural for collections)
|
||||||
|
- **Routes**: `/flodoc/cohorts`, `/admin/invitations` (kebab-case in URLs)
|
||||||
|
|
||||||
|
**Coding Standards:**
|
||||||
|
- **Ruby**: Follow existing RuboCop configuration
|
||||||
|
- **JavaScript**: Follow existing ESLint configuration
|
||||||
|
- **Vue.js**: Use Composition API, `<script setup>` syntax
|
||||||
|
- **TailwindCSS**: Use utility classes, avoid custom CSS
|
||||||
|
- **Testing**: TDD approach, minimum 80% coverage for new code
|
||||||
|
- **Documentation**: YARD comments for Ruby, JSDoc for JavaScript
|
||||||
|
|
||||||
|
**Documentation Standards:**
|
||||||
|
- **Model Comments**: Document associations, validations, and business logic
|
||||||
|
- **API Documentation**: Update OpenAPI/Swagger spec for new endpoints
|
||||||
|
- **Vue Components**: Document props, events, and usage examples
|
||||||
|
- **Migration Comments**: Explain why new tables are needed
|
||||||
|
- **Workflow Diagrams**: Mermaid diagrams for complex 3-portal workflows
|
||||||
|
|
||||||
|
## 4.4 Deployment and Operations
|
||||||
|
|
||||||
|
**Build Process Integration:**
|
||||||
|
- **Asset Compilation**: Shakapacker handles Vue/JS compilation
|
||||||
|
- **TailwindCSS**: Custom build with design system colors
|
||||||
|
- **Ruby Gems**: Bundle install includes new dependencies (rubyXL)
|
||||||
|
- **Database Migrations**: Run automatically in CI/CD pipeline
|
||||||
|
- **Sidekiq Workers**: Deploy with new job classes
|
||||||
|
|
||||||
|
**Deployment Strategy:**
|
||||||
|
- **Zero-Downtime**: Migrations run before new code deploys
|
||||||
|
- **Rollback Plan**: Database migrations must be reversible
|
||||||
|
- **Feature Flags**: Consider `Docuseal.floDocEnabled?` for gradual rollout
|
||||||
|
- **Blue-Green**: Deploy to staging first, validate 3-portal workflows
|
||||||
|
- **Monitoring**: Track cohort creation, completion rates, email delivery
|
||||||
|
|
||||||
|
**Monitoring and Logging:**
|
||||||
|
- **Existing**: Reuse DocuSeal's logging infrastructure
|
||||||
|
- **New Events**: Log cohort lifecycle events (created, student_enrolled, sponsor_accessed, completed)
|
||||||
|
- **Error Tracking**: Sentry/Rollbar integration for portal errors
|
||||||
|
- **Performance**: Monitor query performance on cohort dashboards
|
||||||
|
- **Email Tracking**: Track sponsor email delivery (single email rule compliance)
|
||||||
|
|
||||||
|
**Configuration Management:**
|
||||||
|
- **Environment Variables**: No new required variables
|
||||||
|
- **Feature Toggles**: Use existing Rails configuration pattern
|
||||||
|
- **Secrets**: Reuse existing Rails secrets for email/storage
|
||||||
|
- **Database**: No new database connections needed
|
||||||
|
|
||||||
|
## 4.5 Risk Assessment and Mitigation
|
||||||
|
|
||||||
|
**Technical Risks:**
|
||||||
|
|
||||||
|
1. **Risk**: DocuSeal's multi-submission mechanism duplicates empty documents, not pre-filled ones
|
||||||
|
- **Impact**: High - FR5 requires TP to sign once and auto-fill remaining students
|
||||||
|
- **Mitigation**:
|
||||||
|
- Prototype TP signing phase early
|
||||||
|
- Custom logic: After TP signs first submission, duplicate the completed submission (not empty template)
|
||||||
|
- Use DocuSeal's submission duplication API on the signed submission
|
||||||
|
- Alternative: Programmatic field population via API if duplication doesn't preserve signatures
|
||||||
|
- Fallback: Manual submission creation with field copying logic
|
||||||
|
|
||||||
|
2. **Risk**: Single email rule for sponsors conflicts with DocuSeal's per-submission email logic
|
||||||
|
- **Impact**: High - NFR11 compliance required
|
||||||
|
- **Mitigation**:
|
||||||
|
- Implement email deduplication service
|
||||||
|
- Use cohort-level email tracking
|
||||||
|
- Override DocuSeal's default email behavior
|
||||||
|
|
||||||
|
3. **Risk**: Vue 3 portal components may conflict with existing DocuSeal Vue 2 patterns
|
||||||
|
- **Impact**: Medium - Frontend integration complexity
|
||||||
|
- **Mitigation**:
|
||||||
|
- Audit existing Vue component patterns
|
||||||
|
- Use consistent state management approach
|
||||||
|
- Gradual migration if conflicts exist
|
||||||
|
|
||||||
|
4. **Risk**: Excel export (FR23) may require significant memory for large cohorts
|
||||||
|
- **Impact**: Medium - Performance for 50+ students
|
||||||
|
- **Mitigation**:
|
||||||
|
- Use streaming Excel generation (rubyXL streaming mode)
|
||||||
|
- Background job processing
|
||||||
|
- Pagination or chunking for very large cohorts
|
||||||
|
|
||||||
|
**Integration Risks:**
|
||||||
|
|
||||||
|
1. **Risk**: New FloDoc models may create circular dependencies with existing models
|
||||||
|
- **Impact**: Medium - Model loading issues
|
||||||
|
- **Mitigation**:
|
||||||
|
- Use `belongs_to` with optional: true where needed
|
||||||
|
- Lazy load associations
|
||||||
|
- Test model initialization in isolation
|
||||||
|
|
||||||
|
2. **Risk**: Sponsor portal access without authentication may create security vulnerabilities
|
||||||
|
- **Impact**: High - Data exposure risk
|
||||||
|
- **Mitigation**:
|
||||||
|
- Use signed tokens with expiration
|
||||||
|
- One-time access tokens
|
||||||
|
- IP-based rate limiting
|
||||||
|
- Audit all sponsor access attempts
|
||||||
|
|
||||||
|
3. **Risk**: Bulk operations may timeout for large cohorts (100+ students)
|
||||||
|
- **Impact**: Medium - User experience degradation
|
||||||
|
- **Mitigation**:
|
||||||
|
- Background job processing
|
||||||
|
- Progress indicators
|
||||||
|
- Chunked processing
|
||||||
|
- Async email delivery
|
||||||
|
|
||||||
|
**Deployment Risks:**
|
||||||
|
|
||||||
|
1. **Risk**: Database migrations may lock tables during cohort creation
|
||||||
|
- **Impact**: Low - Existing DocuSeal functionality unaffected
|
||||||
|
- **Mitigation**:
|
||||||
|
- Use non-locking migrations
|
||||||
|
- Run migrations during maintenance window
|
||||||
|
- Test on staging with production-like data volume
|
||||||
|
|
||||||
|
2. **Risk**: New Vue portals may increase bundle size significantly
|
||||||
|
- **Impact**: Low - Modern browsers handle it
|
||||||
|
- **Mitigation**:
|
||||||
|
- Code splitting by portal
|
||||||
|
- Lazy loading for complex views
|
||||||
|
- Tree-shaking unused dependencies
|
||||||
|
|
||||||
|
**Mitigation Strategies:**
|
||||||
|
|
||||||
|
**Development Phase:**
|
||||||
|
1. **Incremental Implementation**: Build one portal at a time
|
||||||
|
2. **Integration Testing**: Test each workflow stage before moving to next
|
||||||
|
3. **User Validation**: Get feedback on sponsor portal early
|
||||||
|
4. **Performance Baseline**: Measure current DocuSeal performance before changes
|
||||||
|
|
||||||
|
**Testing Phase:**
|
||||||
|
1. **End-to-End Tests**: Full 3-portal workflow testing
|
||||||
|
2. **Load Testing**: Simulate 50+ student cohorts
|
||||||
|
3. **Security Audit**: Review sponsor portal access patterns
|
||||||
|
4. **Mobile Testing**: Verify all portals work on mobile devices
|
||||||
|
|
||||||
|
**Rollout Phase:**
|
||||||
|
1. **Feature Flag**: Deploy with FloDoc disabled by default
|
||||||
|
2. **Staged Rollout**: Enable for specific institutions first
|
||||||
|
3. **Monitoring**: Track errors, performance, user adoption
|
||||||
|
4. **Rollback Plan**: Database migrations reversible, code deployable without FloDoc
|
||||||
|
|
||||||
|
**Known Issues from Existing Codebase** (from current-app-sitemap.md):
|
||||||
|
|
||||||
|
1. **Technical Debt**: No coding standards documentation
|
||||||
|
- **Impact**: Consistency issues across FloDoc development
|
||||||
|
- **Mitigation**: This PRD includes coding standards section
|
||||||
|
|
||||||
|
2. **Missing Documentation**: No technical debt analysis
|
||||||
|
- **Impact**: Unknown risks
|
||||||
|
- **Mitigation**: Document risks in this section
|
||||||
|
|
||||||
|
3. **Partial Implementation**: Cohort and Sponsor models referenced in Ability.rb but not created
|
||||||
|
- **Impact**: Will cause runtime errors if not implemented
|
||||||
|
- **Mitigation**: These models are explicitly created in this PRD
|
||||||
|
|
||||||
|
**Workarounds and Gotchas:**
|
||||||
|
|
||||||
|
1. **DocuSeal Multi-tenancy**: Current system supports multi-tenant mode
|
||||||
|
- **Gotcha**: FloDoc uses single-institution model
|
||||||
|
- **Workaround**: Ensure `Docuseal.multitenant?` doesn't interfere with FloDoc logic
|
||||||
|
|
||||||
|
2. **Active Storage Configuration**: Multiple storage backends supported
|
||||||
|
- **Gotcha**: Cohort documents must use same storage as existing templates
|
||||||
|
- **Workaround**: Reuse existing Active Storage configuration
|
||||||
|
|
||||||
|
3. **Sidekiq Queues**: Existing queue structure
|
||||||
|
- **Gotcha**: FloDoc jobs must not block core DocuSeal jobs
|
||||||
|
- **Workaround**: Use separate queues (`cohort_emails`, `excel_export`)
|
||||||
|
|
||||||
|
4. **Devise 2FA**: Users may have 2FA enabled
|
||||||
|
- **Gotcha**: Students/sponsors don't have accounts (ad-hoc access)
|
||||||
|
- **Workaround**: Not applicable - ad-hoc users bypass 2FA
|
||||||
|
|
||||||
|
5. **Vue + Rails Integration**: Shakapacker handles asset compilation
|
||||||
|
- **Gotcha**: New Vue portals must be registered in application.js
|
||||||
|
- **Workaround**: Follow existing Vue initialization pattern
|
||||||
|
|
||||||
|
**Risk Summary:**
|
||||||
|
|
||||||
|
| Risk | Severity | Likelihood | Mitigation Priority |
|
||||||
|
|------|----------|------------|---------------------|
|
||||||
|
| DocuSeal duplicates empty docs, not signed ones | High | High | **Critical** - Prototype early |
|
||||||
|
| Sponsor email deduplication | High | High | **Critical** - Core requirement |
|
||||||
|
| Vue 3 integration conflicts | Medium | Low | Medium - Audit first |
|
||||||
|
| Excel export performance | Medium | Medium | Medium - Background jobs |
|
||||||
|
| Sponsor portal security | High | Low | **Critical** - Security audit |
|
||||||
|
| Bulk operation timeouts | Medium | Medium | Medium - Chunking |
|
||||||
|
|
||||||
|
**Next Steps for Risk Mitigation:**
|
||||||
|
1. **Week 1**: Prototype TP signing phase - test submission duplication from signed document
|
||||||
|
2. **Week 2**: Build sponsor email deduplication service
|
||||||
|
3. **Week 3**: Security review of ad-hoc access patterns
|
||||||
|
4. **Week 4**: Performance testing with large cohorts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
@ -0,0 +1,389 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,29 @@
|
|||||||
|
# FloDoc Brownfield Enhancement PRD
|
||||||
|
|
||||||
|
**3-Portal Cohort Management System for Training Institutions**
|
||||||
|
|
||||||
|
*Version: v2.0* | *Date: 2026-01-10*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sections
|
||||||
|
|
||||||
|
- [Table of Contents](./table-of-contents.md)
|
||||||
|
- [1. Intro Project Analysis and Context](./1-intro-project-analysis-and-context.md)
|
||||||
|
- [2. Requirements](./2-requirements.md)
|
||||||
|
- [3. User Interface Enhancement Goals](./3-user-interface-enhancement-goals.md)
|
||||||
|
- [4. Technical Constraints and Integration Requirements](./4-technical-constraints-and-integration-requirements.md)
|
||||||
|
- [5. Epic and Story Structure](./5-epic-and-story-structure.md)
|
||||||
|
- [6. Epic Details](./6-epic-details.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
**Total Stories:** 32
|
||||||
|
**Phases:** 8
|
||||||
|
**Status:** Section 6 of 6 - Complete
|
||||||
|
|
||||||
|
**Deployment:** Local Docker MVP (Option A)
|
||||||
|
**Security:** POPIA + OWASP compliant
|
||||||
|
**API:** RESTful with webhooks
|
||||||
Loading…
Reference in new issue