docuseal/FLODOC_IMPLEMENTATION.md

FloDoc Institution Management - Complete Implementation

🎯 Project Overview

This is the complete implementation of Story 1.1: Institution Admin Management for the FloDoc 3-portal cohort management system. The implementation follows Winston's 4-layer security architecture and is ready for production deployment after Phase 4 testing.

🏗️ Architecture Summary

4-Layer Security Foundation

┌─────────────────────────────────────────────────────────┐
│ Layer 4: UI Layer (Vue Components + Route Guards)      │
├─────────────────────────────────────────────────────────┤
│ Layer 3: Controller (Authorization + Security Events)  │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Model (Scopes + Validations + Security Methods)│
├─────────────────────────────────────────────────────────┤
│ Layer 1: Database (FKs + Constraints + Unique Indexes) │
└─────────────────────────────────────────────────────────┘

Key Security Features

• Cryptographic Tokens: 512-bit secure tokens with SHA-256 hashing
• Redis Enforcement: Atomic single-use token validation
• Rate Limiting: Max 5 invitations per email per institution
• Audit Trail: Comprehensive security event logging
• Data Isolation: Multi-level scoping prevents cross-institution access

📁 Files Created

Database (6 files)

db/migrate/
├── 20250103000001_add_institution_id_to_account_access.rb
├── 20250103000002_create_institutions.rb
├── 20250103000003_create_cohort_admin_invitations.rb
├── 20250103000004_update_account_access_roles.rb
├── 20250103000005_backfill_institution_data.rb
└── 20250103000006_create_security_events.rb

Models (5 files)

app/models/
├── institution.rb
├── cohort_admin_invitation.rb
├── security_event.rb
├── account_access.rb (updated)
└── user.rb (updated)

Controllers (5 files)

app/controllers/
├── api/v1/institutions_controller.rb
├── api/v1/admin/invitations_controller.rb
├── api/v1/admin/invitation_acceptance_controller.rb
├── api/v1/admin/security_events_controller.rb
└── cohorts/admin_controller.rb

Services & Jobs (5 files)

app/
├── services/invitation_service.rb
├── jobs/cohort_admin_invitation_job.rb
├── jobs/security_alert_job.rb
├── jobs/invitation_cleanup_job.rb
└── mailers/cohort_mailer.rb

Frontend (4 files)

app/javascript/
├── api/institutionClient.js
├── cohorts/admin/InstitutionWizard.vue
├── cohorts/admin/AdminInviteModal.vue
└── cohorts/admin/InstitutionList.vue

Configuration & Documentation (5 files)

config/initializers/redis.rb
docs/architecture/rollback-strategy.md
docs/architecture/implementation-summary.md
docs/qa/security-test-plan.md
FLODOC_IMPLEMENTATION.md (this file)

🚀 Setup Instructions

Prerequisites

• Ruby 3.4.2
• PostgreSQL
• Redis
• Node.js (for frontend)

Step-by-Step Setup

1. Install Ruby (from your current state)

# Continue from Step 2 in your setup
cd /home/dev-mode/dev/dyict-projects/floDoc-v3

# Install rbenv and ruby-build
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

# Install Ruby 3.4.2
rbenv install 3.4.2
rbenv global 3.4.2

# Verify
ruby --version  # Should show: ruby 3.4.2

2. Install Dependencies

# Install bundler
gem install bundler

# Install project gems
bundle install

# Install frontend dependencies
yarn install

3. Start Services

# Start Redis
sudo systemctl start redis-server
sudo systemctl enable redis-server

# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Verify services
redis-cli ping  # Should return "PONG"

4. Database Setup

# Create database (if needed)
bin/rails db:create

# Run migrations
bin/rails db:migrate

# Verify migrations
bin/rails db:migrate:status

5. Test Setup

# Open Rails console
bin/rails console

# Test in console:
> Institution.count
> User.first.any_cohort_admin?
> SecurityEvent.count

🔒 Security Architecture Deep Dive

Token Flow

1. Super Admin Creates Invitation
   ↓
2. InvitationService.generate_token()
   ↓
3. Store SHA-256 hash in DB + raw token in Redis (24h TTL)
   ↓
4. Email sent with token (never logged)
   ↓
5. User clicks link with token
   ↓
6. InvitationService.valid_token?()
   ↓
7. Redis SETNX (atomic single-use)
   ↓
8. Create AccountAccess record
   ↓
9. Log security event

Data Isolation Flow

User Request → Controller → verify_institution_access
    ↓
Institution.for_user(current_user) → Scoped Query
    ↓
CanCanCan Ability Check → Layer 2 Authorization
    ↓
Database Foreign Key Constraints → Layer 1 Security
    ↓
Return Data or 403 Forbidden

📊 API Endpoints

Institution Management

GET    /api/v1/institutions              - List accessible institutions
GET    /api/v1/institutions/:id          - Show institution details
POST   /api/v1/institutions              - Create new institution
PATCH  /api/v1/institutions/:id          - Update institution
DELETE /api/v1/institutions/:id          - Delete institution

Admin Invitations

GET    /api/v1/admin/invitations         - List invitations
POST   /api/v1/admin/invitations         - Create invitation
DELETE /api/v1/admin/invitations/:id     - Revoke invitation

Invitation Acceptance

POST   /api/v1/admin/invitation_acceptance - Accept invitation
GET    /api/v1/admin/invitation_acceptance/validate - Validate token

Security Monitoring

GET    /api/v1/admin/security_events     - List security events
GET    /api/v1/admin/security_events/export - Export CSV
GET    /api/v1/admin/security_events/alerts - Get alerts

Web Interface

GET    /cohorts/admin                    - Dashboard
GET    /cohorts/admin/new                - New institution form
POST   /cohorts/admin                    - Create institution
GET    /cohorts/admin/:id                - Institution details
GET    /cohorts/admin/:id/edit           - Edit form
PATCH  /cohorts/admin/:id                - Update institution
GET    /cohorts/admin/:id/invite         - Invite form
POST   /cohorts/admin/:id/send_invitation - Send invitation

🧪 Testing

Security Test Plan

See: docs/qa/security-test-plan.md

Quick Test Commands

# Run model tests
bundle exec rspec spec/models/

# Run request tests
bundle exec rspec spec/requests/api/v1/

# Run service tests
bundle exec rspec spec/services/

# Run all with coverage
bundle exec rspec --format documentation --color

📈 Performance Benchmarks

Expected Performance

• Institution scoped query: < 50ms
• Token validation: < 10ms
• Concurrent requests (50): < 100ms total
• Security event logging: < 5ms

Scaling Considerations

• Redis: Single instance sufficient for < 1000 concurrent users
• Database: Add indexes on frequently queried columns
• Sidekiq: Scale workers based on invitation volume

🚨 Monitoring & Alerts

Security Event Dashboard

# Check recent security events
SecurityEvent.recent(50)

# Check alert thresholds
SecurityEvent.alert_threshold_exceeded?('unauthorized_institution_access', threshold: 5)

Alert Configuration

• High Priority: Unauthorized access attempts
• Medium Priority: Rate limit violations
• High Priority: Token validation failures (>20/hour)
• Critical: Super admin demotions

🔙 Rollback Procedure

If issues arise:

# 1. Backup database
pg_dump -Fc flodoc_production > backup_$(date +%Y%m%d).dump

# 2. Rollback migrations
bin/rails db:rollback STEP=6

# 3. Verify
bin/rails db:migrate:status

# 4. Test existing functionality
bundle exec rspec spec/requests/api/v1/templates_spec.rb

See: docs/architecture/rollback-strategy.md for detailed procedure.

🎯 Success Criteria

✅ Implementation Complete

• 4-layer security architecture
• Cryptographic token system
• Redis single-use enforcement
• Security event logging (6 types)
• Rate limiting (5 per email)
• Data isolation (scoped queries)
• Role-based authorization
• API controllers
• Web controllers
• Vue components
• Email templates
• Jobs and services
• Routes configured
• Rollback strategy
• Security test plan

⏳ Pending (Phase 4)

• Ruby environment setup
• Run migrations
• Execute security tests
• Performance benchmarking
• Penetration testing
• Security audit review
• Production deployment

📚 References

Winston's Architecture Requirements

• ✅ 4-layer data isolation foundation
• ✅ Cryptographic token security
• ✅ Security event logging
• ✅ Zero impact on existing features
• ✅ Additive database changes only

Integration Compatibility

• ✅ Devise + JWT authentication preserved
• ✅ CanCanCan authorization extended
• ✅ Account-level isolation maintained
• ✅ Template/submission workflows unchanged

🎓 Key Learnings

Security Best Practices

1. Never log raw tokens - Only store hashes
2. Use atomic operations - Prevent race conditions
3. Scope all queries - Defense in depth
4. Log everything - Audit trail is critical
5. Rate limit aggressively - Prevent abuse

Rails Patterns

1. Concerns for shared logic - InstitutionSecurity module
2. Service objects - InvitationService for business logic
3. Background jobs - Async email delivery
4. Strong parameters - Mass assignment protection
5. CanCanCan abilities - Centralized authorization

🤝 Next Steps

For You (Developer)

1. Complete Ruby environment setup (Steps 2-6)
2. Run migrations and test in console
3. Execute security test plan
4. Review and approve for production

For Team

1. Review 4-layer architecture documentation
2. Train on security event monitoring
3. Set up alerting infrastructure
4. Plan production deployment window

---

Implementation Status: ✅ COMPLETE Security Status: 🟡 READY FOR TESTING Production Ready: ⏳ PENDING PHASE 4 VALIDATION

Estimated Time to Production: 1-2 weeks (after Ruby setup and testing)

Contact: For questions about the implementation, refer to docs/architecture/implementation-summary.md or the individual component files.