🎨 wireframes

Story 6.2: Agenda Proposal Screen

Last updated: October 6, 2025 Reading time: 36 minutes File size: 62.02 KB

Header Information

Story: Epic 6, Story 6.2 - Partner Meeting Coordination Screen: Agenda Proposal Screen User Role: Partner Related FR: FR8 (Partner users vote on topic priorities and submit strategic topic suggestions), FR21 (Long-term planning capabilities including seasonal partner meeting coordination)

Visual Wireframe

┌───────────────────────────────────────────────────────────────────────────┐
│ ✕ Close                  Propose Agenda Item                              │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                            │
│  Meeting: Q2 2025 Partner Planning Session                                │
│  Date: April 15, 2025 • 14:00-17:00                                       │
│  Submission Deadline: April 8, 2025 (7 days remaining)                    │
│                                                                            │
│  ┌─── PROPOSAL DETAILS ─────────────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  Agenda Item Title *                                                  │ │
│  │  ┌──────────────────────────────────────────────────────────────┐   │ │
│  │  │ e.g., AI Integration Strategy for 2025 Events                 │   │ │
│  │  └──────────────────────────────────────────────────────────────┘   │ │
│  │  (Max 100 characters)                                                 │ │
│  │                                                                        │ │
│  │  Description *                                                         │ │
│  │  ┌──────────────────────────────────────────────────────────────┐   │ │
│  │  │ Discuss opportunities to integrate AI-powered features into   │   │ │
│  │  │ our events, including automated content recommendations,      │   │ │
│  │  │ intelligent speaker matching, and attendee engagement         │   │ │
│  │  │ analytics. We'll review pilot results from Q1 and propose     │   │ │
│  │  │ a phased rollout strategy for Q3-Q4.                          │   │ │
│  │  │                                                                │   │ │
│  │  │                                                                │   │ │
│  │  └──────────────────────────────────────────────────────────────┘   │ │
│  │  (Max 1000 characters • 182/1000 used)                                │ │
│  │                                                                        │ │
│  │  Expected Outcomes / Discussion Goals                                 │ │
│  │  ┌──────────────────────────────────────────────────────────────┐   │ │
│  │  │ • Alignment on AI integration priorities                      │   │ │
│  │  │ • Budget allocation approval for pilot expansion              │   │ │
│  │  │ • Timeline commitment for Q3 rollout                          │   │ │
│  │  │                                                                │   │ │
│  │  └──────────────────────────────────────────────────────────────┘   │ │
│  │  (Optional • bullet points recommended)                               │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌─── TIME & PRIORITY ──────────────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  Estimated Duration *                                                 │ │
│  │  ○ 15 minutes    ○ 30 minutes    ● 45 minutes    ○ 60 minutes        │ │
│  │  ○ Custom: [____] minutes                                             │ │
│  │                                                                        │ │
│  │  Priority Level *                                                     │ │
│  │  ○ High         Critical topic requiring immediate discussion         │ │
│  │  ● Medium       Important but can be scheduled flexibly               │ │
│  │  ○ Low          Nice to discuss if time permits                       │ │
│  │                                                                        │ │
│  │  Preferred Time Slot (Optional)                                       │ │
│  │  ○ Early in meeting (high energy for complex topics)                  │ │
│  │  ● Middle of meeting (balanced attention)                             │ │
│  │  ○ Late in meeting (lighter topics or follow-up discussions)          │ │
│  │  ○ No preference                                                      │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌─── SUPPORTING MATERIALS ─────────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  Upload materials to help organizers and other partners prepare       │ │
│  │                                                                        │ │
│  │  ┌──────────────────────────────────────────────────────────────┐   │ │
│  │  │ 📎 AI_Pilot_Results_Q1.pdf                           [Remove] │   │ │
│  │  │    2.3 MB • Uploaded 2 min ago                                │   │ │
│  │  │                                                                │   │ │
│  │  │ 📎 Budget_Proposal_AI_Integration.xlsx               [Remove] │   │ │
│  │  │    486 KB • Uploaded just now                                 │   │ │
│  │  └──────────────────────────────────────────────────────────────┘   │ │
│  │                                                                        │ │
│  │  ┌─────────────────────────────────────────────────────────────┐    │ │
│  │  │         📁 [Upload Files] or drag and drop here              │    │ │
│  │  │                                                               │    │ │
│  │  │      Accepted: PDF, PPTX, XLSX, DOCX • Max 20 MB per file   │    │ │
│  │  └─────────────────────────────────────────────────────────────┘    │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌─── STRATEGIC CONTEXT ────────────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  Link to Company Strategic Goals (Optional)                           │ │
│  │  ☑ Innovation & Digital Transformation                                │ │
│  │  ☑ Employee Development & Skills                                      │ │
│  │  ☐ Cost Optimization & Efficiency                                     │ │
│  │  ☐ Customer Experience Enhancement                                    │ │
│  │  ☐ Sustainability & Social Responsibility                             │ │
│  │  ☐ Other: [_________________________________]                         │ │
│  │                                                                        │ │
│  │  Business Impact (Optional)                                           │ │
│  │  ┌──────────────────────────────────────────────────────────────┐   │ │
│  │  │ This initiative directly supports our 2025 digital            │   │ │
│  │  │ transformation roadmap and could improve employee engagement  │   │ │
│  │  │ by 25-30% based on industry benchmarks.                       │   │ │
│  │  └──────────────────────────────────────────────────────────────┘   │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌─── PARTICIPANT PREPARATION ──────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  Pre-Reading Required?                                                │ │
│  │  ● Yes, materials should be reviewed in advance                       │ │
│  │  ○ No, materials are for reference only                               │ │
│  │                                                                        │ │
│  │  Requested Participants (Optional)                                    │ │
│  │  ☑ All partners (default)                                             │ │
│  │  ☐ Specific partners: [Search partners...                    ▼]      │ │
│  │                                                                        │ │
│  │  ☐ Request specific expertise/roles:                                  │ │
│  │    ☐ Technical/IT leads    ☐ C-level executives                       │ │
│  │    ☐ HR/Training leads     ☐ Budget/Finance leads                     │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌─── SIMILAR PROPOSALS ────────────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  💡 Other partners have proposed similar agenda items:                │ │
│  │                                                                        │ │
│  │  ┌──────────────────────────────────────────────────────────────┐   │ │
│  │  │ 🔗 "Machine Learning in Event Analytics"                      │   │ │
│  │  │    Proposed by: Swisscom • Priority: High • 30 min           │   │ │
│  │  │    Overlap: AI/ML focus, analytics discussion                │   │ │
│  │  │    [View Proposal] [Suggest Merge]                           │   │ │
│  │  └──────────────────────────────────────────────────────────────┘   │ │
│  │                                                                        │ │
│  │  💬 Consider supporting their proposal or suggesting a combined       │ │
│  │     session to maximize meeting efficiency.                           │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ┌─── PROPOSAL SUMMARY ─────────────────────────────────────────────────┐ │
│  │                                                                        │ │
│  │  Review your proposal before submission:                              │ │
│  │                                                                        │ │
│  │  Title:     AI Integration Strategy for 2025 Events                   │ │
│  │  Duration:  45 minutes                                                │ │
│  │  Priority:  Medium                                                    │ │
│  │  Materials: 2 files attached (2.8 MB total)                           │ │
│  │  Goals:     Innovation & Digital Transformation, Employee Dev.        │ │
│  │                                                                        │ │
│  │  ⚠️ Your proposal will be reviewed by organizers within 48 hours      │ │
│  │  📧 You'll receive email confirmation when status changes              │ │
│  │                                                                        │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                            │
│  ☑ I confirm this proposal aligns with our partnership goals and          │
│     represents my organization's priorities for this meeting              │
│                                                                            │
│                  [Cancel]        [Save as Draft]    [Submit Proposal]     │
│                                                                            │
└───────────────────────────────────────────────────────────────────────────┘

Key Interactive Elements

Form Controls

  • Text Input Fields: Title (100 char max), Description (1000 char max), Expected Outcomes (rich text)
  • Character Counters: Real-time character count with visual warning at 90% capacity
  • Radio Button Groups: Duration selection (15/30/45/60 min + custom), Priority levels (High/Medium/Low), Time slot preferences
  • Checkboxes: Strategic goals (multi-select), participant requirements, pre-reading toggle
  • File Upload Zone: Drag-and-drop area with browse button, progress indicators, file preview with remove option

Smart Features

  • Auto-Save: Form data auto-saved to localStorage every 30 seconds to prevent data loss
  • Duplicate Detection: Real-time similarity check against existing proposals, shows similar items with merge suggestions
  • Character Validation: Live validation with helpful error messages (e.g., “Title too long, 25 characters over limit”)
  • File Validation: Client-side validation for file type and size before upload, visual feedback for accepted/rejected files

Action Buttons

  • [Cancel]: Discard proposal with confirmation dialog if unsaved changes exist
  • [Save as Draft]: Save proposal without submitting, allowing later editing
  • [Submit Proposal]: Final submission with validation check and confirmation modal
  • [Upload Files]: Opens file browser or accepts drag-and-drop uploads
  • [Remove]: Removes uploaded file with confirmation
  • [View Proposal]: Opens similar proposal in modal overlay
  • [Suggest Merge]: Initiates merge request with another proposal

Visual Indicators

  • Required Field Markers (*): Red asterisk indicates mandatory fields
  • Validation Icons: Green checkmark for valid, red X for invalid fields
  • Progress Indicator: Shows completion percentage (e.g., “60% complete”)
  • Deadline Countdown: Visual countdown showing days/hours remaining until submission deadline

Functional Requirements Met

  • FR8 (Topic Voting & Suggestions): Partners can submit strategic agenda item suggestions for partner meetings, influencing meeting content and priorities
  • FR21 (Long-term Planning): Seasonal partner meeting coordination with structured agenda proposal workflow enables strategic partnership management
  • FR2 (Event Workflow): Proposal submission integrates with meeting planning workflow, allowing organizers to review and approve agenda items
  • FR7 (Email Notifications): Automated email notifications for proposal status changes (submitted, under review, approved/declined)

User Interactions

Opening the Proposal Form

  1. User clicks [Propose Agenda Item] button from Partner Meetings Hub
  2. System checks proposal submission deadline (must be at least 48 hours before meeting)
  3. If deadline passed: Display error modal “Agenda proposal deadline has passed for this meeting”
  4. If deadline valid: Load Agenda Proposal Screen with meeting context pre-filled
  5. Form displays with empty fields and meeting details at top

Filling Out Proposal Details

  1. User enters Agenda Item Title (required)
    • Character counter updates in real-time
    • Warning displays at 90 characters (90% of limit)
    • Error displays if exceeding 100 characters
  2. User enters Description (required)
    • Rich text editor with basic formatting (bold, italic, bullets)
    • Character counter shows usage (e.g., “182/1000 used”)
    • Auto-expands textarea as content grows
  3. User enters Expected Outcomes (optional)
    • Bullet point format recommended (auto-formatting)
    • Helps organizers understand discussion goals

Setting Time and Priority

  1. User selects Estimated Duration
    • Radio button selection (15/30/45/60 min or custom)
    • If “Custom” selected: Input field appears for manual entry (max 120 min)
    • Duration validation: Warns if total proposed durations exceed meeting time
  2. User selects Priority Level
    • High: Critical topic requiring immediate discussion
    • Medium: Important but flexible scheduling
    • Low: Nice to discuss if time permits
    • Help tooltips explain each priority level
  3. User selects Preferred Time Slot (optional)
    • Early/Middle/Late/No preference
    • System considers preferences when scheduling but doesn’t guarantee placement

Uploading Supporting Materials

  1. User clicks [Upload Files] or drags files into upload zone
  2. File validation runs:
    • Type check: PDF, PPTX, XLSX, DOCX accepted
    • Size check: Max 20 MB per file, 100 MB total
    • If invalid: Error toast with specific reason (e.g., “File type .txt not accepted”)
  3. Valid files upload with progress bar
  4. Uploaded files appear in list with:
    • File icon based on type
    • File name (truncated if long)
    • File size
    • Upload timestamp
    • [Remove] button
  5. User can remove files by clicking [Remove] (confirmation required if file > 5 MB)

Adding Strategic Context

  1. User selects Strategic Goals (checkboxes)
    • Multi-select allowed
    • “Other” option opens text field for custom goal
  2. User describes Business Impact (optional)
    • Free-form text area
    • Helps justify proposal importance
    • Used by organizers in approval process

Participant Preparation Settings

  1. User toggles Pre-Reading Required
    • Yes: Materials should be reviewed in advance
    • No: Materials are for reference only
    • Affects when materials are distributed (if Yes: 1 week before, if No: day before)
  2. User selects Requested Participants
    • Default: All partners invited to meeting
    • Optional: Search and select specific partners
    • Optional: Request specific expertise/roles (checkboxes)

Duplicate Detection & Merge Suggestions

  1. As user types Title and Description, system performs similarity check
  2. If similar proposals found (>70% text similarity or same keywords):
    • Similar Proposals section appears
    • Shows matching proposals with:
      • Proposal title
      • Proposer company
      • Priority and duration
      • Overlap summary
    • [View Proposal] button opens modal with full details
    • [Suggest Merge] button initiates merge request workflow
  3. User can:
    • View similar proposal and adjust their own to differentiate
    • Suggest merging proposals into combined session
    • Continue with separate proposal if topics genuinely different

Reviewing and Submitting

  1. User reviews Proposal Summary (auto-generated)
    • Shows all key details in condensed format
    • Highlights any validation warnings
  2. User checks Confirmation Checkbox (required)
    • “I confirm this proposal aligns with our partnership goals…”
    • Cannot submit without checking
  3. User clicks [Submit Proposal]
  4. Final validation runs:
    • All required fields completed
    • Files successfully uploaded (no pending uploads)
    • Character limits respected
    • Confirmation checkbox checked
  5. If validation fails:
    • Error summary modal displays
    • Scroll to first invalid field
    • Highlight invalid fields in red
  6. If validation passes:
    • Confirmation modal appears:
      Submit Agenda Proposal?

Your proposal "AI Integration Strategy for 2025 Events" will be
sent to meeting organizers for review. You'll receive email
confirmation within 48 hours.

[Go Back]  [Confirm Submission]
  7. On confirmation:
    • API call executes (POST /api/v1/partners/{partnerId}/meetings/{meetingId}/agenda/propose)
    • Success notification displays
    • Email confirmation sent to user
    • Screen closes, returns to Partner Meetings Hub
    • Proposal appears in “Your Proposals” section with “Under Review” status

Saving as Draft

  1. User clicks [Save as Draft] at any time
  2. Partial validation runs (required fields not enforced)
  3. Draft saved to database with “DRAFT” status
  4. Success toast: “Draft saved successfully”
  5. User can:
    • Continue editing
    • Close screen (draft accessible later)
    • Submit when ready

Canceling Proposal

  1. User clicks [Cancel] or close button (✕)
  2. If unsaved changes detected:
    • Confirmation dialog appears:
      Discard Changes?

You have unsaved changes. Do you want to save as draft before closing?

[Discard]  [Save Draft]  [Keep Editing]
  3. If no changes: Screen closes immediately
  4. If [Discard]: Screen closes, changes lost
  5. If [Save Draft]: Draft saved, then screen closes
  6. If [Keep Editing]: Dialog closes, user continues editing

Technical Notes

Frontend Implementation

  • Framework: React 18.2 with TypeScript, Material-UI components (Modal, TextField, Radio, Checkbox, FileUpload)
  • Form Management: React Hook Form with Zod schema validation for robust type-safe form handling
  • Rich Text Editor: Draft.js or Slate.js for description field with basic formatting
  • File Upload: Direct browser-to-S3 presigned URL upload (via Company Management API)
  • Auto-Save: localStorage backup every 30s, synced with server on Submit/Save Draft
  • Real-Time Validation: Debounced validation (500ms) to reduce API calls while providing immediate feedback

Duplicate Detection

  • Algorithm: Cosine similarity on TF-IDF vectors of title + description text
  • Threshold: 70% similarity triggers “similar proposal” alert
  • Keyword Matching: Exact matches on key terms (e.g., “AI”, “budget”, “strategy”) boost similarity score
  • API: POST /api/v1/meetings/{meetingId}/agenda/proposals/check-similarity with proposal text
  • Response: List of similar proposals with similarity scores and overlap summaries

File Upload Process

  1. User selects files
  2. Frontend validates file type and size
  3. Request presigned upload URL: POST /api/v1/files/presigned-upload-url
  4. Direct upload to S3 using presigned URL (client-side)
  5. Confirm upload completion: POST /api/v1/files/{fileId}/confirm
  6. Attach file IDs to proposal on submission
  7. S3 lifecycle policy: Delete files if proposal not submitted within 7 days (cleanup orphaned files)

Character Limit Enforcement

  • Client-Side: maxLength attribute on inputs, disabled submit if exceeded
  • Server-Side: Database column constraints, validation layer rejects oversized content
  • User Feedback: Character counter changes color (green → yellow at 80% → red at 100%)

State Management

  • Local State: React Hook Form for form fields, file upload progress
  • Server State: React Query for meeting details, existing proposals, similarity checks
  • Persistent State: localStorage for draft backup, restored on page reload
  • Cache Strategy:
    • Meeting details: 5 min cache
    • Existing proposals: 2 min cache, invalidated on new submission
    • Similarity check: No cache (always fresh)

Performance Optimization

  • Debounced Similarity Check: 1 second debounce on title/description changes
  • Lazy Load Similar Proposals: Only fetch on first similarity match
  • File Upload Chunking: Large files (>10 MB) uploaded in chunks for reliability
  • Optimistic UI Updates: Draft saves show success immediately, rollback on API failure

API Requirements

Initial Page Load APIs

  1. GET /api/v1/partners/{partnerId}/meetings/{meetingId}?include=agenda,participants (Story 1.18)

    • Consolidation: Uses ?include= pattern to fetch meeting details with agenda and participants in single request
    • Authorization: Requires PARTNER role
    • Query Params:
      • include=agenda,participants (expanded data)
    • Returns: Meeting context for proposal form
      json
      {
  "meetingId": "meeting-123",
  "title": "Q2 2025 Partner Planning Session",
  "date": "2025-04-15T14:00:00Z",
  "endTime": "2025-04-15T17:00:00Z",
  "location": "UBS Conference Center, Zurich",
  "agendaProposalDeadline": "2025-04-08T23:59:59Z",
  "totalDuration": 180,
  "allocatedDuration": 135,
  "availableDuration": 45,
  "organizerName": "Event Organizer Team",
  "organizerEmail": "organizers@batbern.ch",
  "agenda": {
    "items": [...],
    "totalProposals": 12
  },
  "participants": [...]
}
    • Used for: Populate meeting context header, validate submission deadline, show available time, display existing agenda items
    • Performance: <400ms (P95) for meeting with all included data
    • Consolidation Benefit: Single request replaces 3 separate calls (meeting details, agenda, participants)

  2. GET /api/v1/partners/{partnerId}?include=settings (Story 1.18)

    • Consolidation: Uses consolidated Partners API to fetch strategic goals from settings
    • Authorization: Requires PARTNER role
    • Query Params:
      • include=settings (includes strategic goals configuration)
    • Returns: Partner company information with strategic goals
      json
      {
  "companyId": "comp-456",
  "goals": [
    {
      "id": "goal-1",
      "name": "Innovation & Digital Transformation",
      "description": "Driving digital innovation across all business units",
      "active": true
    },
    {
      "id": "goal-2",
      "name": "Employee Development & Skills",
      "description": "Upskilling workforce for future readiness",
      "active": true
    },
    // ... other goals
  ],
  "customGoalsAllowed": true
}
    • Used for: Pre-populate strategic goals checkboxes with company-specific goals

  3. GET /api/v1/partners/{partnerId}/meetings/{meetingId}/proposals/drafts

    • Authorization: Requires PARTNER role
    • Query Params: None
    • Returns: User’s saved drafts for this meeting (if any)
      json
      {
  "drafts": [
    {
      "draftId": "draft-789",
      "title": "AI Integration Strategy",
      "lastSaved": "2025-04-01T10:30:00Z",
      "completeness": 0.6
    }
  ]
}
    • Used for: Prompt user to continue existing draft if found

User Action APIs

  1. POST /api/v1/partners/{partnerId}/meetings/{meetingId}/agenda/propose

    • Triggered by: [Submit Proposal] button click after validation
    • Authorization: Requires PARTNER role, partner must be invited to meeting
    • Payload:
      json
      {
  "title": "AI Integration Strategy for 2025 Events",
  "description": "Discuss opportunities to integrate AI-powered features...",
  "expectedOutcomes": "• Alignment on AI integration priorities\n• Budget allocation approval...",
  "estimatedDurationMinutes": 45,
  "priority": "medium",
  "preferredTimeSlot": "middle",
  "supportingMaterialFileIds": ["file-123", "file-456"],
  "strategicGoalIds": ["goal-1", "goal-2"],
  "businessImpact": "This initiative directly supports our 2025 digital transformation...",
  "preReadingRequired": true,
  "requestedParticipants": "all",
  "requestedExpertise": ["technical_leads", "hr_leads"],
  "confirmationAcknowledged": true
}
    • Validation:
      • Title: Required, 1-100 characters
      • Description: Required, 1-1000 characters
      • Duration: Required, 15-120 minutes
      • Priority: Required, enum [high, medium, low]
      • File IDs must exist and belong to requesting partner
      • Proposal deadline must not have passed
      • Confirmation must be true
    • Response (201 Created):
      json
      {
  "proposalId": "proposal-987",
  "status": "UNDER_REVIEW",
  "submittedAt": "2025-04-01T14:35:00Z",
  "estimatedReviewDate": "2025-04-03T14:35:00Z",
  "reviewers": ["organizer@batbern.ch"],
  "emailConfirmationSent": true
}
    • Error Response (400 Bad Request):
      json
      {
  "error": "VALIDATION_FAILED",
  "message": "Proposal validation failed",
  "details": [
    {
      "field": "title",
      "message": "Title exceeds maximum length of 100 characters"
    },
    {
      "field": "estimatedDurationMinutes",
      "message": "Total proposed duration (245 min) exceeds available meeting time (45 min)"
    }
  ]
}
    • Error Response (409 Conflict):
      json
      {
  "error": "DEADLINE_PASSED",
  "message": "Agenda proposal deadline has passed",
  "deadline": "2025-04-08T23:59:59Z",
  "currentTime": "2025-04-09T10:00:00Z"
}
    • Used for: Submit final agenda proposal, trigger organizer review workflow

  2. POST /api/v1/partners/{partnerId}/meetings/{meetingId}/agenda/proposals/check-similarity

    • Triggered by: Real-time as user types title/description (debounced 1s)
    • Authorization: Requires PARTNER role
    • Payload:
      json
      {
  "title": "AI Integration Strategy for 2025 Events",
  "description": "Discuss opportunities to integrate AI-powered features..."
}
    • Response:
      json
      {
  "similarProposals": [
    {
      "proposalId": "proposal-456",
      "title": "Machine Learning in Event Analytics",
      "proposedBy": {
        "companyName": "Swisscom",
        "companyId": "comp-789"
      },
      "priority": "high",
      "estimatedDurationMinutes": 30,
      "similarityScore": 0.78,
      "overlapSummary": "AI/ML focus, analytics discussion",
      "keywords": ["AI", "machine learning", "analytics"]
    }
  ],
  "hasDuplicates": true,
  "mergeRecommended": true
}
    • Used for: Detect similar proposals, suggest merges, prevent duplicate agenda items

  3. POST /api/v1/partners/{partnerId}/meetings/{meetingId}/agenda/proposals/draft

    • Triggered by: [Save as Draft] button or auto-save (every 30s)
    • Authorization: Requires PARTNER role
    • Payload: Same structure as proposal submission, but required fields not enforced
      json
      {
  "draftId": "draft-789",
  "title": "AI Integration Strategy",
  "description": "Discuss opportunities...",
  "estimatedDurationMinutes": 45,
  "priority": "medium",
  "supportingMaterialFileIds": ["file-123"],
  "lastSaved": "2025-04-01T14:30:00Z"
}
    • Response:
      json
      {
  "draftId": "draft-789",
  "saved": true,
  "savedAt": "2025-04-01T14:30:00Z",
  "completeness": 0.6,
  "missingRequiredFields": ["expectedOutcomes", "strategicGoalIds"]
}
    • Used for: Save incomplete proposals for later editing, prevent data loss

  4. PUT /api/v1/partners/{partnerId}/meetings/{meetingId}/agenda/proposals/{proposalId}/support

    • Triggered by: [Support This Proposal] button on similar proposal
    • Authorization: Requires PARTNER role, different from proposal author
    • Payload:
      json
      {
  "supportComment": "We also see value in this discussion and would contribute budget data"
}
    • Response:
      json
      {
  "proposalId": "proposal-456",
  "supportCount": 3,
  "supportingPartners": ["UBS", "Credit Suisse", "Swiss Re"],
  "yourSupport": true,
  "increasedPriority": true
}
    • Used for: Express support for other partners’ proposals, increase priority through consensus

  5. POST /api/v1/partners/{partnerId}/meetings/{meetingId}/agenda/proposals/merge-request

    • Triggered by: [Suggest Merge] button on similar proposal
    • Authorization: Requires PARTNER role
    • Payload:
      json
      {
  "proposalId1": "proposal-987",
  "proposalId2": "proposal-456",
  "mergedTitle": "AI & Machine Learning Strategy for 2025",
  "mergedDescription": "Combined session covering AI integration and ML analytics...",
  "combinedDurationMinutes": 60,
  "justification": "Both proposals share AI/ML focus, combining allows deeper discussion"
}
    • Response:
      json
      {
  "mergeRequestId": "merge-123",
  "status": "PENDING_APPROVAL",
  "requiresApproval": ["partner-987", "partner-456", "organizer"],
  "notificationsSent": true
}
    • Used for: Request merging similar proposals into combined agenda item

  6. POST /api/v1/files/upload (Story 1.27)

    • Consolidation: Simplified file upload with presigned URL pattern
    • Triggered by: File selection in upload zone
    • Authorization: Requires authenticated user
    • Payload:
      json
      {
  "fileName": "AI_Pilot_Results_Q1.pdf",
  "fileSize": 2400000,
  "contentType": "application/pdf",
  "context": "AGENDA_PROPOSAL",
  "contextId": "meeting-123"
}
    • Response:
      json
      {
  "fileId": "file-123",
  "uploadUrl": "https://s3.eu-central-1.amazonaws.com/batbern-content/...",
  "uploadFields": {
    "key": "proposals/meeting-123/file-123.pdf",
    "policy": "...",
    "x-amz-signature": "..."
  },
  "expiresAt": "2025-04-01T15:30:00Z",
  "cdnUrl": "https://d3tsrt2aaweqwh.cloudfront.net/proposals/meeting-123/file-123.pdf"
  }
    • Used for: Generate presigned S3 upload URL for direct client-to-S3 upload
    • Performance: <200ms (P95)
    • Consolidation Benefit: Single endpoint handles presigned URL generation and file metadata

  7. DELETE /api/v1/files/{fileId} (Story 1.27)

    • Consolidation: Standard file deletion endpoint
    • Triggered by: [Remove] button on uploaded file
    • Authorization: Requires authenticated user, file owner
    • Payload: None
    • Response:
      json
      {
  "fileId": "file-123",
  "deleted": true,
  "deletedAt": "2025-04-01T14:32:00Z"
}
    • Used for: Remove uploaded file before proposal submission
    • Consolidation Benefit: Simplified file management (upload confirmation integrated into initial upload endpoint)

Primary Navigation Actions

  1. ✕ Close button / [Cancel] → Close modal, return to Partner Meetings Hub

    • Target: story-6.2-partner-meetings.md (Partner Meetings screen)
    • Context: None if discarding, draft ID if saved
    • Unsaved Changes: Prompt with “Discard Changes?” dialog if form dirty
    • Behavior: Modal closes, underlying Partner Meetings Hub remains in view

  2. [Submit Proposal] → Submit proposal, show confirmation, close modal

    • Action: Execute proposal submission API
    • Success Flow:
      • Confirmation modal appears: “Proposal submitted successfully”
      • Email confirmation sent notification
      • Modal closes after 2 seconds
      • Partner Meetings Hub refreshes to show new proposal in “Your Proposals” section
    • Failure Flow:
      • Error modal with specific validation errors
      • Remain on Agenda Proposal Screen
      • Highlight invalid fields

  3. [Save as Draft] → Save draft, remain on screen

    • Action: Execute draft save API
    • Success: Toast notification “Draft saved”, update last saved timestamp
    • Failure: Error toast with retry option
    • Behavior: Form remains open for continued editing

Secondary Navigation (Data Interactions)

  1. [View Proposal] button in Similar Proposals → Open proposal detail modal

    • Target: Modal overlay showing full similar proposal details
    • Content:
      • Complete proposal information (title, description, outcomes, duration, priority)
      • Proposer company information
      • Similarity analysis (overlap keywords, shared topics)
      • Support count and supporting partners
    • Actions: [Close], [Support This Proposal], [Suggest Merge]
    • Behavior: Modal over modal (Proposal Detail over Agenda Proposal Screen)

  2. [Suggest Merge] button → Open merge request modal

    • Target: Modal overlay for merge request form
    • Content:
      • Preview of both proposals side-by-side
      • Merged title/description editor
      • Combined duration calculation
      • Justification text field
    • Actions: [Cancel], [Send Merge Request]
    • Behavior: On send, merge request API called, notifications sent to affected parties

  3. File name click in uploaded materials → Preview or download file

    • Behavior:
      • PDFs: Open in browser preview modal
      • Office docs (PPTX, XLSX, DOCX): Trigger download
      • Images: Open in lightbox viewer
    • No Navigation: Remains on Agenda Proposal Screen

  4. Strategic Goal “Other” text field → Enable custom goal input

    • Trigger: Checking “Other” checkbox enables text input
    • Behavior: User can type custom strategic goal (max 100 chars)
    • Validation: Required if “Other” checked, auto-added to company goals library
    • No Navigation: Remains on Agenda Proposal Screen

Event-Driven Navigation

  1. Auto-save triggers → Background save, no navigation

    • Trigger: 30 second timer or before window close
    • Action: Silent draft save API call
    • Notification: Small toast “Draft saved” in bottom-right corner (non-intrusive)
    • Failure: Retry up to 3 times, then warn user “Unable to auto-save. Please save manually.”
    • No Navigation: Remains on current screen

  2. Similar proposal detected → Show Similar Proposals section

    • Trigger: Similarity check API returns matches (>70% similarity)
    • Behavior: Similar Proposals section animates into view
    • Notification: Info toast “We found similar proposals. Consider merging or supporting existing items.”
    • No Navigation: Remains on Agenda Proposal Screen

  3. Proposal deadline approaching (24 hours) → Urgency indicator

    • Trigger: Time-based check (frontend timer)
    • Behavior:
      • Deadline text changes color to red
      • Warning banner appears: “⚠️ Proposal deadline in 24 hours”
      • [Submit Now] button highlighted
    • No Navigation: Remains on current screen

  4. File upload complete → Update file list

    • Trigger: S3 upload success callback
    • Behavior:
      • Progress bar changes to checkmark
      • File appears in uploaded materials list
      • Success toast “File uploaded successfully”
    • No Navigation: Remains on Agenda Proposal Screen

  5. File upload failed → Show error and retry option

    • Trigger: S3 upload error callback
    • Behavior:
      • Progress bar changes to error icon
      • Error toast with specific reason “Upload failed: File too large / Network error / Invalid type”
      • [Retry Upload] button appears
    • No Navigation: Remains on Agenda Proposal Screen

Error States & Redirects

  1. Unauthorized access (403) → Redirect to Partner Dashboard

    • Condition: User is not a partner or not invited to this meeting
    • Notification: “You don’t have permission to propose agenda items for this meeting.”
    • Redirect: After 3 seconds, navigate to Partner Dashboard
    • Target: Partner Dashboard (if wireframe exists, otherwise main app home)

  2. Meeting not found (404) → Redirect to Partner Meetings Hub

    • Condition: Meeting ID invalid or meeting deleted
    • Notification: “Meeting not found. It may have been cancelled or deleted.”
    • Redirect: Immediate navigation to Partner Meetings Hub
    • Target: story-6.2-partner-meetings.md

  3. Proposal deadline passed (409) → Close modal with error

    • Condition: Server validation detects deadline passed since modal opened
    • Modal:
      Deadline Passed

The agenda proposal deadline for this meeting has passed.
You can no longer submit new proposals.

Deadline: April 8, 2025 at 11:59 PM

[View Meeting Details]  [Close]
    • [View Meeting Details]: Navigate to read-only meeting details
    • [Close]: Close modal, return to Partner Meetings Hub

  4. Session timeout (401) → Save draft, redirect to login

    • Condition: JWT token expired during form editing
    • Behavior:
      1. Attempt to save draft to localStorage (client-side backup)
      2. Display modal: “Your session has expired. Your draft has been saved locally and will be restored after login.”
      3. Redirect to login page
      4. After login: Restore from localStorage and prompt “Would you like to continue your unsaved proposal?”

  5. Network error → Save locally, show offline indicator

    • Condition: API calls fail due to network issues
    • Behavior:
      1. Save form data to localStorage
      2. Show offline banner: “You appear to be offline. Your changes are saved locally.”
      3. Display [Retry Connection] button
      4. When connection restored: Sync local changes to server
    • No Navigation: Remains on Agenda Proposal Screen with offline mode active

  6. Validation error (400) → Highlight errors inline

    • Condition: Server-side validation fails on submission
    • Behavior:
      1. Parse error response for field-specific errors
      2. Scroll to first invalid field
      3. Display inline error messages below each field
      4. Show error summary at top: “Please fix 3 errors before submitting”
      5. [Submit Proposal] button remains enabled for retry
    • No Navigation: Remains on current screen for error correction

Responsive Design Considerations

Mobile Layout Changes (< 768px)

  • Form Sections: Stack vertically, full width
  • Radio Button Groups: Convert to dropdown selects to save vertical space
    • Duration: Dropdown with “15 min”, “30 min”, “45 min”, “60 min”, “Custom” options
    • Priority: Dropdown with “High”, “Medium”, “Low”
    • Time Slot: Dropdown or hidden on mobile (less critical on small screens)
  • File Upload Zone: Full-width, larger touch target (min 60px height)
  • Supporting Materials List: Cards instead of rows, with swipe-to-delete gesture
  • Similar Proposals: Collapsible accordion, show summary only until expanded
  • Action Buttons: Sticky footer with full-width buttons stacked vertically
    • [Cancel] top
    • [Save as Draft] middle
    • [Submit Proposal] bottom (primary action)
  • Character Counters: Move below text fields instead of inline
  • Strategic Goals Checkboxes: Group in collapsible section to reduce screen height

Tablet Layout Changes (768px - 1024px)

  • Two-Column Layout: Split form into left (main content) and right (context/summary) columns
  • Radio Buttons: Remain horizontal for Duration and Priority
  • File Upload: Half-width zone with file list adjacent
  • Similar Proposals: Side-by-side cards (2 per row)
  • Action Buttons: Bottom-right aligned, horizontal layout:
    • [Cancel] left, [Save as Draft] center, [Submit Proposal] right

Mobile-Specific Interactions

  • Pull-to-Refresh: Not applicable (modal form, no refresh needed)
  • Swipe Gestures:
    • Swipe left on uploaded file → Reveal [Remove] button
    • Swipe down from top of modal → Close modal (with unsaved changes warning)
  • Touch Targets: All interactive elements minimum 44x44px
  • Virtual Keyboard: Form auto-scrolls to keep focused input visible above keyboard
  • File Upload: Mobile allows “Take Photo” option in addition to file selection
  • Voice Input: Enable voice-to-text for description and business impact fields (browser native)

Accessibility Notes

  • Keyboard Navigation:
    • Full tab navigation through all form fields in logical order
    • Enter key submits form when on [Submit Proposal] button
    • Escape key closes modal (with unsaved changes warning)
    • Arrow keys navigate radio button groups
  • Focus Management:
    • On modal open: Focus moves to first input (Title field)
    • On modal close: Focus returns to trigger element (Propose Agenda Item button)
    • On error: Focus moves to first invalid field
  • ARIA Labels:
    • Required fields: aria-required="true" and visual asterisk
    • Character counters: aria-live="polite" announce remaining characters
    • File upload zone: aria-label="Upload supporting materials, accepts PDF, PowerPoint, Excel, Word, maximum 20 megabytes per file"
    • Similar proposals: aria-label="Similar proposal: Machine Learning in Event Analytics by Swisscom"
  • Error Messaging:
    • Invalid fields: aria-invalid="true" and aria-describedby linking to error message
    • Error summary: role="alert" for immediate announcement
    • Field-specific errors: Associated via aria-describedby to input
  • Color Contrast:
    • All text meets WCAG 2.1 AA standards (4.5:1 for normal text)
    • Error states use both color (red) and icon (⚠️) for colorblind users
    • Focus indicators: 3px solid outline with 3:1 contrast ratio
  • Screen Reader Support:
    • Form progress announced: “Form 60% complete, 4 of 10 required fields filled”
    • File upload status: “Uploading AI_Pilot_Results.pdf, 45% complete”
    • Similarity detection: “2 similar proposals found, review suggested”
    • Auto-save: “Draft saved automatically at 2:30 PM”
  • Semantic HTML:
    • Proper heading hierarchy (h1 for modal title, h2 for section headers)
    • <fieldset> and <legend> for radio button groups
    • <label> elements explicitly associated with inputs
    • <button> elements (not divs) for all actions

State Management

Local Component State

  • formData: Object containing all form field values (title, description, duration, priority, etc.)
  • uploadedFiles: Array of uploaded file objects with metadata (id, name, size, uploadProgress)
  • validationErrors: Object mapping field names to error messages
  • isDirty: Boolean indicating unsaved changes (triggers warning on close)
  • isSaving: Boolean for save/submit loading state
  • isAutoSaving: Boolean for auto-save loading indicator
  • similarProposals: Array of detected similar proposals
  • showSimilarProposals: Boolean to control Similar Proposals section visibility
  • draftId: String ID if continuing existing draft
  • lastSaved: Timestamp of last successful save (auto or manual)

Global State (Zustand Store)

  • currentPartner: Partner company information (id, name, tier, strategic goals)
  • currentUser: User information (id, name, email, role)
  • meetingContext: Current meeting details (from parent screen)
  • userDrafts: Array of user’s saved drafts across all meetings (for quick access)

Server State (React Query)

  • Query Keys:

    • ['meeting', meetingId, 'details']: Meeting details (5 min cache)
    • ['partner', partnerId, 'strategic-goals']: Company strategic goals (30 min cache)
    • ['meeting', meetingId, 'proposals', 'drafts']: User’s drafts (no cache, always fresh)
    • ['meeting', meetingId, 'similarity-check']: Similarity results (1 min cache)

  • Mutations:

    • submitProposal: Invalidates ['meeting', meetingId, 'proposals'] query on success
    • saveDraft: Invalidates ['meeting', meetingId, 'proposals', 'drafts'] query
    • uploadFile: No cache invalidation, updates local uploadedFiles state
    • deleteFile: Removes from local uploadedFiles state
    • checkSimilarity: No cache, updates local similarProposals state

Real-Time Updates

  • Auto-Save Polling: Every 30 seconds (configurable via AUTO_SAVE_INTERVAL_MS)
  • Similarity Check: Debounced 1 second after last keystroke in title/description fields
  • Deadline Countdown: Client-side timer updates every minute, visual urgency at <24 hours
  • File Upload Progress: Real-time progress updates via S3 upload events

Form Validation Rules

Field-Level Validations

  • Title:

    • Required: Cannot be empty
    • Min Length: 10 characters
    • Max Length: 100 characters
    • Pattern: Alphanumeric with spaces, hyphens, basic punctuation allowed
    • Trim: Leading/trailing whitespace removed

  • Description:

    • Required: Cannot be empty
    • Min Length: 50 characters (ensures sufficient detail)
    • Max Length: 1000 characters
    • Pattern: Rich text with basic formatting, no scripts/iframes

  • Expected Outcomes:

    • Optional: Can be empty
    • Max Length: 500 characters
    • Recommended: Bullet point format (helpful hint shown)

  • Estimated Duration:

    • Required: Must select a value
    • Range: 15-120 minutes
    • Custom: If selected, must be positive integer
    • Validation: Cannot exceed available meeting time

  • Priority Level:

    • Required: Must select High, Medium, or Low
    • No additional validation

  • Preferred Time Slot:

    • Optional: Can be left unselected
    • Default: “No preference”

  • Supporting Materials:

    • Optional: 0-10 files allowed
    • File Type: PDF, PPTX, XLSX, DOCX only
    • File Size: Max 20 MB per file, 100 MB total
    • Validation: Type and size checked client-side before upload

  • Strategic Goals:

    • Optional: 0-n selections allowed
    • “Other” custom goal: Max 100 characters if specified

  • Business Impact:

    • Optional: Can be empty
    • Max Length: 500 characters

  • Pre-Reading Required:

    • Required: Must select Yes or No (default: Yes)

  • Requested Participants:

    • Optional: Default “All partners”
    • Validation: If specific partners selected, at least 1 required

  • Requested Expertise:

    • Optional: 0-n selections allowed

  • Confirmation Checkbox:

    • Required: Must be checked to submit (cannot submit until checked)

Form-Level Validations

  • Total Duration Check: Sum of all proposed agenda items (including this one) cannot exceed meeting total time

    • Example: Meeting is 180 min, 135 min already allocated → max 45 min for new proposal
    • Error: “Total proposed duration (245 min) exceeds available meeting time (45 min remaining)”

  • Duplicate Title Check: Title cannot match existing proposal title exactly (case-insensitive)

    • Error: “An agenda item with this title already exists. Please use a unique title.”

  • File Upload Completion: All files must finish uploading before submission

    • Error: “File uploads in progress. Please wait for uploads to complete.”

  • Deadline Validation: Current time must be before agenda proposal deadline

    • Error: “Proposal deadline has passed (deadline was April 8, 2025 at 11:59 PM)”

  • Strategic Context: If strategic goals selected, business impact description recommended (warning, not error)

    • Warning: “Consider adding business impact description to strengthen your proposal”

Edge Cases & Error Handling

Empty States

  • No Strategic Goals: If company has no strategic goals defined, show message “Your company has not defined strategic goals. You can add custom goals using the ‘Other’ option.”
  • No Similar Proposals: Similar Proposals section hidden if no matches found (>70% similarity threshold)
  • No Uploaded Files: Upload zone displayed prominently with helpful text “Add supporting materials to help organizers understand your proposal”

Loading States

  • Initial Load: Modal displays with loading skeleton for meeting details and strategic goals
  • Saving Proposal: [Submit Proposal] button shows spinner and text changes to “Submitting…”
  • Auto-Saving: Small spinner in top-right corner with “Saving draft…” text (non-intrusive)
  • File Uploading: Progress bar per file with percentage and “Uploading…” text
  • Similarity Check: Debounced loading indicator next to title field (small spinner, disappears after check)

Error States

  • API Unavailable (503):

    • Modal: “Service temporarily unavailable. Your draft is saved locally and will sync when service is restored.”
    • Enable offline mode: All changes saved to localStorage
    • Periodic retry: Attempt to reconnect every 30 seconds
    • Visual indicator: Offline banner at top of form

  • File Upload Failed:

    • Show error icon on failed file with reason (Network error, File too large, Invalid type)
    • [Retry Upload] button appears next to failed file
    • Option to remove failed file and try again
    • Error persists: Suggest reducing file size or using different format

  • Validation Failed (400):

    • Scroll to first invalid field
    • Highlight all invalid fields with red border and error icon
    • Show inline error message below each invalid field
    • Display error summary banner at top: “Please fix 3 errors before submitting”
    • [Submit Proposal] remains enabled for retry after corrections

  • Duplicate Proposal (409):

    • Modal: “A similar proposal has been submitted while you were editing. Would you like to:”
      • [View Similar Proposal] → Open comparison view
      • [Modify Your Proposal] → Return to editing
      • [Suggest Merge] → Initiate merge request
      • [Submit Anyway] → Force submit as separate item

  • Deadline Extension:

    • If organizers extend deadline while user has modal open, show notification:
      • “Good news! The proposal deadline has been extended to April 10, 2025.”
      • Update deadline countdown automatically

Permission Issues

  • Partner Access Revoked Mid-Session:

    • Modal: “Your partnership access has been updated. You can no longer submit proposals for this meeting.”
    • Auto-save draft to localStorage before closing
    • Redirect to Partner Dashboard after 5 seconds

  • Meeting Cancelled:

    • Modal: “This meeting has been cancelled. Agenda proposals are no longer accepted.”
    • Option to save proposal as template for future meetings
    • Redirect to Partner Meetings Hub

Data Integrity

  • Concurrent Editing:

    • If user opens same draft in multiple tabs, show warning:
      • “This draft is open in another tab. Changes may conflict.”
      • “Which version do you want to keep: [This Tab] [Other Tab] [Merge Changes]”

  • File Corruption:

    • If uploaded file fails integrity check (checksum mismatch):
      • Error: “File upload verification failed. Please re-upload the file.”
      • File removed from list automatically
      • User prompted to upload again

  • LocalStorage Quota Exceeded:

    • If auto-save to localStorage fails due to quota:
      • Warning: “Unable to save draft locally. Consider submitting now or saving draft to server.”
      • Disable auto-save, rely on manual [Save as Draft] button
      • Show persistent warning banner until issue resolved

Meeting Time Constraints

  • Available Time Exceeded:

    • Real-time check: If total proposed durations exceed available time, show warning:
      • “Warning: Total proposed durations (245 min) exceed available time (45 min). Organizers may reduce durations or schedule additional meeting time.”
    • Allow submission but flag proposal for organizer review

  • Too Many Proposals:

    • If meeting has 20+ proposed agenda items:
      • Info banner: “This meeting has many proposed items. Consider supporting existing proposals instead of adding new ones.”
      • Highlight similar proposals more prominently

Browser Compatibility

  • File Upload Fallback:

    • If drag-and-drop not supported: Show standard file input button only
    • If FormData API unavailable: Disable file uploads, show message “File uploads not supported in this browser. Please use a modern browser.”

  • LocalStorage Unavailable:

    • If localStorage blocked or unavailable:
      • Disable auto-save feature
      • Show warning: “Auto-save disabled. Please save drafts manually.”
      • Rely entirely on server-side draft saves

Change Log

Date Version Description Author
2025-04-01 1.0 Initial wireframe creation Sally (UX)

Review Notes

Stakeholder Feedback

To be added after stakeholder review

Design Iterations

To be documented as design evolves

Open Questions

  1. Merge Workflow Complexity: Should merge requests require approval from both proposers AND organizers, or just organizers?

    • Impact: More approvals = better consensus, but slower process
    • Recommendation: Organizer approval only, with automatic notification to both proposers

  2. Draft Expiration: Should saved drafts expire after a certain period (e.g., 30 days)?

    • Current: Drafts persist indefinitely
    • Consideration: Old drafts for past meetings may clutter UI
    • Recommendation: Auto-archive drafts for meetings that occurred >30 days ago

  3. Anonymous Proposals: Should partners be able to submit anonymous agenda proposals?

    • Current: All proposals show proposer company name
    • Use Case: Sensitive topics that partners hesitate to propose publicly
    • Recommendation: Consider anonymous option in future iteration with organizer-only visibility of proposer

  4. Voting on Proposals: Should other partners be able to vote on proposed agenda items to influence priority?

    • Current: Partners can “support” proposals, increasing visibility
    • Enhancement: Formal voting with weighted votes by partnership tier
    • Recommendation: Evaluate in pilot meetings, add if strong partner demand

  5. Proposal Templates: Should system provide pre-defined proposal templates for common agenda types (budget review, strategic planning, innovation showcase)?

    • Current: Blank form only
    • Benefit: Faster proposal creation, consistent structure
    • Recommendation: Add template library in future iteration based on most common proposal patterns