Zoom Integration - Project Plan v2.0

Project: CODITECT Zoom Integration Version: 2.0.0 Status: Planning Last Updated: December 17, 2025

---

Executive Summary

This project delivers a zero-cost Zoom integration as an optional CODITECT component, enabling customers to schedule meetings, retrieve transcripts, and process meeting artifacts through the CODITECT AI pipeline.

Key Objectives

1. Zero External Cost - Use only free-tier Zoom APIs
2. Optional Component - Activatable only when needed
3. Provider Agnostic - Abstract interface for multi-provider support
4. CODITECT Native - Follow framework patterns and conventions

Success Criteria

• All free-tier APIs integrated and tested
• 80%+ unit test coverage
• Documentation complete (SDD, TDD, ADRs)
• Component activation workflow functional
• AI pipeline integration working

---

Phase 0: Zoom Marketplace App Setup (Prerequisites)

0.1 Zoom Developer Account Configuration

Duration: 1 day

• Create Zoom Developer Account

  • Go to: https://marketplace.zoom.us/
  • Sign in with Zoom account
  • Accept developer terms of service

• Create Zoom Marketplace App

  • Go to: Build App → Create
  • App Type: Server-to-Server OAuth (for backend) or OAuth (for user auth)
  • App Name: "CODITECT Zoom Integration"
  • App Description: Meeting scheduling and transcript retrieval

0.2 API Endpoints Reference

API	Endpoint Base	Documentation
Zoom REST API v2	https://api.zoom.us/v2	https://developers.zoom.us/docs/api/
OAuth Token	https://zoom.us/oauth/token	https://developers.zoom.us/docs/integrations/oauth/
OAuth Authorize	https://zoom.us/oauth/authorize	-
Webhooks	Your endpoint	https://developers.zoom.us/docs/api/rest/webhook-reference/

0.3 OAuth 2.0 App Configuration

Duration: 2 hours

• Configure User OAuth App (for user-level access)

  • Go to: App Credentials
  • Copy Client ID and Client Secret
  • Add Redirect URL:
    • http://localhost:8080/oauth/zoom/callback (development)
    • https://your-domain.com/oauth/zoom/callback (production)
  • Add Allow List URLs (development domains)

• Configure Scopes

  • Go to: Scopes → Add Scopes
  • Required Scopes:

    # User Scopes
    user:read:admin
    user:read
    
    # Meeting Scopes
    meeting:read:admin
    meeting:write:admin
    meeting:read
    meeting:write
    
    # Recording Scopes
    recording:read:admin
    recording:read
    cloud_recording:read:admin
    
    # Webinar (optional)
    webinar:read:admin
    webinar:write:admin

0.4 Server-to-Server OAuth Setup (Recommended for Backend)

Duration: 1 hour

• Create Server-to-Server OAuth App

  • Go to: Build App → Server-to-Server OAuth
  • App Name: "CODITECT Zoom Backend"
  • Copy Account ID, Client ID, Client Secret

• Configure Scopes

  • Add same scopes as User OAuth
  • Note: S2S has account-level access, not user-level

• Activate App

  • Complete all required fields
  • Click "Activate" to enable API access

0.5 Webhook Configuration

Duration: 1 hour

• Configure Event Subscriptions

  • Go to: Feature → Event Subscriptions
  • Add Event Subscription:
    • Subscription Name: "CODITECT Events"
    • Event Notification Endpoint URL: https://your-domain.com/webhooks/zoom
  • Events to subscribe:

    # Meeting Events
    meeting.started
    meeting.ended
    meeting.participant_joined
    meeting.participant_left
    
    # Recording Events
    recording.completed
    recording.transcript_completed

• Webhook Verification

  • Copy Secret Token for signature verification
  • Implement URL Validation (Zoom sends challenge)

0.6 API Endpoints Quick Reference

Operation	Endpoint
Get Access Token (User OAuth)	POST https://zoom.us/oauth/token
Get Access Token (S2S OAuth)	POST https://zoom.us/oauth/token
Revoke Token	POST https://zoom.us/oauth/revoke
Create Meeting	POST https://api.zoom.us/v2/users/{userId}/meetings
Get Meeting	GET https://api.zoom.us/v2/meetings/{meetingId}
Update Meeting	PATCH https://api.zoom.us/v2/meetings/{meetingId}
Delete Meeting	DELETE https://api.zoom.us/v2/meetings/{meetingId}
List Meetings	GET https://api.zoom.us/v2/users/{userId}/meetings
Get Past Meeting	GET https://api.zoom.us/v2/past_meetings/{meetingId}
Get Participants	GET https://api.zoom.us/v2/past_meetings/{meetingId}/participants
Get Recordings	GET https://api.zoom.us/v2/meetings/{meetingId}/recordings
List User Recordings	GET https://api.zoom.us/v2/users/{userId}/recordings
Download Recording	GET {download_url} (from recordings response)
Get User	GET https://api.zoom.us/v2/users/{userId}
Get Current User	GET https://api.zoom.us/v2/users/me

0.7 Environment Variables

Duration: 30 minutes

• Create .env file with credentials

  # User OAuth
  ZOOM_CLIENT_ID=your-client-id
  ZOOM_CLIENT_SECRET=your-client-secret
  ZOOM_REDIRECT_URI=http://localhost:8080/oauth/zoom/callback
  
  # Server-to-Server OAuth
  ZOOM_ACCOUNT_ID=your-account-id
  ZOOM_S2S_CLIENT_ID=your-s2s-client-id
  ZOOM_S2S_CLIENT_SECRET=your-s2s-client-secret
  
  # Webhooks
  ZOOM_WEBHOOK_SECRET_TOKEN=your-webhook-secret
  ZOOM_WEBHOOK_VERIFICATION_TOKEN=your-verification-token
  
  # Security
  TOKEN_ENCRYPTION_KEY=<32-byte-base64-key>

• Add .env to .gitignore

• Create .env.example with placeholder values

0.8 API Rate Limits Reference

Category	Limit	Notes
Light	10 req/sec	Most endpoints
Medium	20 req/sec	List operations
Heavy	5 req/sec	Recordings, reports
Daily	10,000 requests	Free/Pro plans

0.9 Required Zoom Plan Features

Feature	Free	Pro	Business	Enterprise
REST API Access	Limited	Yes	Yes	Yes
Webhooks	No	Yes	Yes	Yes
Cloud Recordings	No	Yes (1GB)	Yes	Yes
Transcription	No	Limited	Yes	Yes
Meeting Duration	40 min	30 hrs	30 hrs	30 hrs

---

Project Phases

Phase 1: Foundation (Week 1-2)

Goal: Core infrastructure and authentication

Phase 2: API Integration (Week 3-4)

Goal: Meeting and Recording API implementations

Phase 3: AI Pipeline (Week 5)

Goal: Connect to CODITECT AI processing

Phase 4: Testing & Documentation (Week 6)

Goal: Comprehensive testing and docs

---

Detailed Timeline

Week 1  │ Week 2  │ Week 3  │ Week 4  │ Week 5  │ Week 6
────────┼─────────┼─────────┼─────────┼─────────┼─────────
Phase 1: Foundation        │ Phase 2: API Integration
████████████████████████████│██████████████████████████
                           │
        OAuth │ Models     │ Meetings │ Recordings
        ██████│████████████│██████████│███████████
                                      │
                                      │ Phase 3: AI
                                      │ ██████████
                                              │
                                              │ Phase 4
                                              │ ████████

---

Phase 1: Foundation

1.1 Project Setup

Duration: 2 days

• Create project structure
  • src/ directory with __init__.py
  • tests/ directory with __init__.py
  • config/ directory with default.yaml
  • docs/ directory (already created)
• Set up pyproject.toml with dependencies
• Configure pytest and coverage
• Set up pre-commit hooks
• Create .gitignore for secrets

1.2 Provider Interface

Duration: 2 days

• Define MeetingProviderInterface abstract base class
  • authenticate() method
  • create_meeting() method
  • get_meeting() method
  • list_meetings() method
  • get_transcript() method
  • get_recording() method
  • get_participants() method
• Create data models
  • Meeting dataclass
  • Transcript dataclass
  • TranscriptEntry dataclass
  • Recording dataclass
  • Participant dataclass
• Define exception hierarchy
  • MeetingIntegrationError base
  • AuthenticationError
  • RateLimitError
  • ProviderError

1.3 OAuth Implementation

Duration: 3 days

• Implement ZoomUserOAuth
  • Authorization URL generation
  • Code exchange for tokens
  • Token refresh logic
  • Token revocation
• Implement ZoomS2SOAuth
  • Account credentials grant
  • Automatic token refresh
  • Error handling
• Create token storage abstraction
  • Secure storage interface
  • File-based implementation
  • Encryption at rest (AES-256)
• Write unit tests for OAuth
  • Test token exchange
  • Test token refresh
  • Test error handling

1.4 Rate Limiting

Duration: 2 days

• Implement TokenBucket class
  • Async support
  • Configurable rate and burst
  • Token refill logic
• Implement ZoomRateLimiter
  • Per-endpoint rate limits
  • General rate limit tracking
  • Warning on approaching limits
• Create retry decorator with backoff
  • Exponential backoff
  • Jitter
  • Configurable max retries
• Write unit tests
  • Test rate limiting behavior
  • Test retry logic

---

Phase 2: API Integration

2.1 Base API Client

Duration: 2 days

• Implement ZoomAPIClient
  • Authenticated requests
  • Response handling
  • Error mapping
  • Rate limit header parsing
• Add request/response logging
• Write unit tests

2.2 Meeting API Integration

Duration: 3 days

• Implement ZoomMeetingAPI
  • create_meeting() with settings
  • get_meeting() by ID
  • update_meeting() for modifications
  • delete_meeting() for cancellation
  • list_meetings() with pagination
• Implement get_past_meeting()
  • Handle UUID encoding
  • Parse meeting details
• Implement get_meeting_participants()
  • Pagination handling
  • Participant data mapping
• Write unit tests
  • Mock API responses
  • Test error handling
  • Test pagination

2.3 Recording API Integration

Duration: 3 days

• Implement ZoomRecordingAPI
  • get_meeting_recordings()
  • list_user_recordings() with filters
  • delete_meeting_recordings()
• Implement recording download
  • Authenticated download URL
  • Progress callback
  • Error handling
• Implement transcript download
  • VTT content retrieval
  • Parse transcript content
• Write unit tests

2.4 Zoom Provider

Duration: 2 days

• Implement ZoomProvider
  • Implement all interface methods
  • Coordinate auth, API, rate limiting
  • Handle authentication modes
• Create configuration loader
  • YAML configuration parsing
  • Environment variable support
  • Validation
• Write integration tests
  • Test full workflow
  • Test error scenarios

2.5 Webhook Handler (Optional)

Duration: 2 days

• Implement ZoomWebhookHandler
  • Signature verification
  • URL validation challenge
  • Event routing
• Create event handlers
  • Meeting ended handler
  • Recording completed handler
• Write unit tests

---

Phase 3: AI Pipeline Integration

3.1 Transcript Processing

Duration: 2 days

• Implement ZoomVTTParser
  • Parse VTT format
  • Extract speaker names
  • Extract timestamps
  • Build formatted content
• Implement ZoomTranscriptProcessor
  • Format transcript for AI
  • Speaker diarization formatting
  • Analysis prompt templates
• Write unit tests

3.2 AI Pipeline Connector

Duration: 2 days

• Connect to CODITECT AI service
  • Use existing AI pipeline
  • Handle response parsing
• Implement analysis types
  • Meeting summary
  • Action items extraction
  • Key decisions
  • Follow-up items
• Write integration tests

3.3 Context Database Integration

Duration: 2 days

• Implement MeetingContextStore
  • Store meeting metadata
  • Store transcript text
  • Store AI-generated insights
• Create search capabilities
  • Full-text search on transcripts
  • Filter by date range
  • Filter by participants
• Write integration tests

3.4 Component Activation

Duration: 1 day

• Create component activation entry
  • Add to component-activation-status.json
  • Define dependencies
  • Set default to disabled
• Create activation script
  • Validate dependencies
  • Run configuration
  • Test connectivity

---

Phase 4: Testing & Documentation

4.1 Comprehensive Testing

Duration: 3 days

• Unit tests (80%+ coverage)
  • OAuth tests
  • Rate limiter tests
  • Meeting API tests
  • Recording API tests
  • VTT parser tests
  • Provider tests
• Integration tests
  • End-to-end meeting creation
  • Transcript retrieval flow
  • Error handling scenarios
• Performance tests
  • Rate limiting effectiveness
  • Response times

4.2 Documentation

Duration: 2 days

• Complete SDD (done)
• Complete TDD (done)
• Complete ADRs (done)
• Create user guide
  • Setup instructions
  • Configuration reference
  • Troubleshooting guide
• Create API reference
  • Python API documentation
  • Code examples
• Update README.md
  • Quick start
  • Feature list
  • Requirements

4.3 Final Review

Duration: 1 day

• Code review
• Documentation review
• Security review
• Performance review
• Final testing

---

Phase 5: Scheduling Components (integration-core)

5.1 Unified Scheduling Orchestrator

Duration: 2 days

• Integrate with coditect-integrations package
  • Install integration-core as dependency: pip install coditect-integrations[zoom]
  • Import orchestrator: from coditect_integrations import MeetingSchedulerOrchestrator
  • Import models: from coditect_integrations.models import ScheduledMeeting, Attendee, RecurrenceRule
  • Configure MeetingSchedulerOrchestrator with ZoomProvider
• Implement ZoomProvider(MeetingProviderInterface)
  • Implement provider_name property → "zoom"
  • Implement authenticate() → OAuth/S2S token loading
  • Implement create_meeting() → Zoom REST API POST /users/{userId}/meetings
  • Implement get_meeting() → Zoom REST API GET /meetings/{meetingId}
  • Implement get_transcript() → VTT download and parsing via ZoomVTTParser
  • Implement get_recording() → Cloud Recording API download
  • Implement get_participants() → Past meeting participants API
• Register provider with orchestrator
  • orchestrator.register_provider("zoom", ZoomProvider())
  • Return unified ScheduledMeeting dataclass

5.2 Calendar Synchronization

Duration: 3 days

• Implement external calendar integration (Zoom has no native calendar)
  • Import: from coditect_integrations.calendar import CalendarSyncManager, CalendarClient
  • Create Zoom meeting + calendar event atomically (transaction pattern)
  • Store CalendarEvent.id in ScheduledMeeting.external_calendar_id
  • Sync meeting changes to calendar via CalendarSyncManager.create_calendar_event()
• Implement GoogleCalendarClient(CalendarClient) and/or OutlookCalendarClient
  • Implement create_event() with Zoom join URL in event body
  • Implement update_event() when Zoom meeting changes
  • Implement delete_event() when Zoom meeting cancelled
• Configure CalendarSyncManager
  • CalendarSyncManager(google_calendar=GoogleCalendarClient(), outlook_calendar=OutlookClient())
  • One-way sync: Zoom → External Calendar (Zoom is source of truth)
  • Store sync state per meeting in CODITECT database

5.3 Recurring Meetings

Duration: 2 days

• Integrate RecurrenceEngine from integration-core
  • Import: from coditect_integrations.scheduling import RecurrenceEngine
  • Import models: from coditect_integrations.models import RecurrenceRule, Frequency, Weekday
• Implement Zoom-specific recurrence conversion
  • Use RecurrenceEngine.to_provider_format(rule, "zoom") for Zoom JSON
  • Map Frequency.DAILY → Zoom type: 1
  • Map Frequency.WEEKLY → Zoom type: 2 with weekly_days bitmask
  • Map Frequency.MONTHLY → Zoom type: 3 with monthly_day
  • Handle RecurrenceRule.interval → Zoom repeat_interval
  • Handle RecurrenceRule.count → Zoom end_times
  • Handle RecurrenceRule.until → Zoom end_date_time
• Test recurrence patterns via RecurrenceEngine.generate_instances()
  • Frequency.DAILY with interval=2 (every other day)
  • Frequency.WEEKLY with by_day=[Weekday.MO, Weekday.WE]
  • Frequency.MONTHLY with by_month_day=[1] (first of month)

5.4 Attendee Management

Duration: 2 days

• Integrate AttendeeManager from integration-core
  • Import: from coditect_integrations.attendee import AttendeeManager
  • Import models: from coditect_integrations.models import Attendee, ResponseStatus, AttendeeResponse
• Implement ZoomNotificationService(NotificationService)
  • Zoom API doesn't send invitations → use external email service
  • Implement send_invitation() → Email with Zoom join URL + calendar event
  • Implement send_update() → Email notification of meeting changes
  • Implement send_cancellation() → Email with cancellation notice
• Implement RSVP tracking in CODITECT database (Zoom has no native RSVP)
  • Store AttendeeResponse per meeting in database
  • Track ResponseStatus.ACCEPTED/DECLINED/TENTATIVE/PENDING
  • Query via get_attendee_responses(meeting_id)
• Handle Zoom Registrants (if registration enabled on meeting)
  • Use Zoom API: POST /meetings/{meetingId}/registrants
  • Sync registrant status → AttendeeResponse

5.5 Availability Checking

Duration: 2 days

• Integrate AvailabilityService from integration-core
  • Import: from coditect_integrations.availability import AvailabilityService
  • Import models: from coditect_integrations.models import TimeRange, BusyPeriod, AvailableSlot, WorkingHours
• Implement calendar clients for free/busy queries
  • GoogleCalendarFreeBusyClient → Calendar API freebusy.query()
  • OutlookFreeBusyClient → Graph API /users/{id}/calendar/getSchedule (optional)
• Configure AvailabilityService for cross-provider availability
  • AvailabilityService(google_calendar=GoogleClient(), outlook_calendar=OutlookClient())
  • Auto-route attendees by email domain (gmail/google vs outlook/hotmail/live)
  • Use get_free_busy() → Dict[email, List[BusyPeriod]]
  • Use _merge_busy_periods() to consolidate across all attendees
• Find available slots
  • find_available_slots(attendees, TimeRange, duration_minutes, WorkingHours)
  • suggest_meeting_times() with preference scoring

5.6 Reminder System

Duration: 1 day

• Integrate ReminderService from integration-core
  • Import: from coditect_integrations.reminders import ReminderService
  • Import models: from coditect_integrations.models import Reminder, ScheduledReminder, ReminderMethod
• Implement notification channels for Zoom
  • EmailNotificationChannel → Include Zoom join_url in body
  • PushNotificationChannel → Deep link to Zoom app (optional)
  • WebhookNotificationChannel → POST to customer webhook (optional)
• Implement ReminderStorage for persistence
  • Store ScheduledReminder with meeting.join_url reference
  • Query get_due_reminders(before=datetime.utcnow())
• Configure ReminderService
  • ReminderService(email_service=EmailChannel(), storage=ReminderStorage())
  • Schedule: schedule_reminder(meeting_id, Reminder(minutes_before=10, method=EMAIL))
  • Process: process_due_reminders() via background worker
  • Cancel: cancel_all_reminders(meeting_id) when meeting deleted

---

Resource Requirements

Team

• 1 Backend Engineer (primary)
• 0.5 DevOps Engineer (CI/CD setup)
• 0.25 Tech Writer (documentation review)

Infrastructure

• Zoom Marketplace App (free)
• CI/CD pipeline (existing)
• Test environment (existing)

Dependencies

[project.dependencies]
coditect-integrations = ">=1.0.0"

[project.optional-dependencies]
zoom = [
    "coditect-integrations[zoom]>=1.0.0",
    "aiohttp>=3.9.0",
    "pydantic>=2.0.0",
    "cryptography>=41.0.0",
    "python-dateutil>=2.8.0",
]

---

Integration-Core Components Reference

Core Imports

# Orchestrator
from coditect_integrations import MeetingSchedulerOrchestrator
from coditect_integrations.core import MeetingProviderInterface

# Models
from coditect_integrations.models import (
    Meeting, ScheduledMeeting, MeetingUpdate,
    Attendee, AttendeeResponse, ResponseStatus,
    RecurrenceRule, Frequency, Weekday,
    Reminder, ScheduledReminder, ReminderMethod,
    TimeRange, BusyPeriod, AvailableSlot, WorkingHours,
    Transcript, TranscriptEntry, Recording, Participant,
    CalendarEvent, SyncState, SyncDirection,
)

# Services
from coditect_integrations.scheduling import RecurrenceEngine
from coditect_integrations.calendar import CalendarSyncManager
from coditect_integrations.attendee import AttendeeManager
from coditect_integrations.availability import AvailabilityService
from coditect_integrations.reminders import ReminderService

Provider Implementation Pattern

class ZoomProvider(MeetingProviderInterface):
    @property
    def provider_name(self) -> str:
        return "zoom"

    async def create_meeting(self, title, start_time, duration_minutes, attendees=None, **kwargs) -> Meeting:
        # Zoom REST API: POST /users/{userId}/meetings
        pass

    async def get_transcript(self, meeting_id) -> Optional[Transcript]:
        # Download VTT from Cloud Recording API, parse with ZoomVTTParser
        pass

Zoom Recurrence Format Mapping

# integration-core RecurrenceRule → Zoom API format
recurrence_engine = RecurrenceEngine()

rule = RecurrenceRule(
    frequency=Frequency.WEEKLY,
    interval=1,
    by_day=[Weekday.MO, Weekday.WE, Weekday.FR],
    count=10,
)

zoom_format = recurrence_engine.to_provider_format(rule, "zoom")
# Result: {"type": 2, "repeat_interval": 1, "weekly_days": "2,4,6", "end_times": 10}

Orchestrator Usage

orchestrator = MeetingSchedulerOrchestrator(
    recurrence_engine=RecurrenceEngine(),
    calendar_sync=CalendarSyncManager(google_calendar=GoogleCalendarClient()),  # External calendar
    attendee_manager=AttendeeManager(notification_service=EmailService()),
    availability_service=AvailabilityService(google_calendar=FreeBusyClient()),
    reminder_service=ReminderService(email_service=EmailChannel(), storage=ReminderDB()),
)

# Schedule Zoom meeting with external calendar sync
meeting = await orchestrator.schedule_meeting(
    provider="zoom",
    title="Team Standup",
    start_time=datetime(2025, 12, 20, 9, 0),
    duration_minutes=30,
    attendees=[Attendee(email="team@example.com", name="Team")],
    recurrence=RecurrenceRule(frequency=Frequency.DAILY, interval=1, count=20),
    reminders=[Reminder(minutes_before=5, method=ReminderMethod.EMAIL)],
    sync_to_calendar="google",  # Sync to Google Calendar
)

---

Risk Assessment

Risk	Probability	Impact	Mitigation
API rate limits hit	Medium	Low	Token bucket rate limiting
OAuth token expiry	Low	Medium	Automatic refresh logic
Recording not available	Medium	Low	Graceful handling, retry
Zoom API changes	Low	High	Version pinning, monitoring
Business+ required	N/A	N/A	Document requirement clearly

---

Success Metrics

Metric	Target
Unit test coverage	80%+
Integration test pass rate	100%
API response time (p95)	<500ms
Documentation completeness	100%
Zero external costs	Verified

---

Acceptance Criteria

MVP (Minimum Viable Product)

1. Can authenticate with Zoom OAuth
2. Can create meeting via REST API
3. Can retrieve meeting recordings
4. Can retrieve meeting transcript (VTT)
5. Component activation works
6. Documentation complete

Full Release

1. All MVP criteria met
2. Webhook handlers working
3. AI pipeline integration
4. Context database storage
5. Performance targets met
6. Security review passed

Scheduling Components (Phase 5)

1. Unified scheduling orchestrator integrated
2. Two-way calendar sync working
3. Recurring meetings supported
4. Attendee invitations/RSVPs working
5. Availability checking functional
6. Reminder system operational

---

Comparison with Google Meet Integration

Feature	Google Meet	Zoom
Meeting Creation	Calendar API	REST API
Meeting Management	Calendar API	REST API
Transcripts	Meet REST API	Cloud Recording API
Recordings	Drive API	Cloud Recording API
Webhooks	Workspace Events	Zoom Webhooks
Free Tier	Yes*	Yes*
Real-time	No (paid)	No (RTMS = paid)

*Both require business-tier accounts for transcript/recording access

---

Document Control:

• Created: December 17, 2025
• Owner: CODITECT Engineering Team
• Review Cycle: Weekly during development