docuseal/docs/prd/4-technical-constraints-and-integration-requirements.md

# 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

---