Document Management + AI Search Use Cases

This document describes use cases for uploading and managing HR documents, traditional and AI-powered search, document tagging, and the AI assistant for policy questions.

Actors

UC-DOC-01: Upload Document

Primary Actor: Tenant Admin, Manager, Employee (if permitted)

Preconditions

• Actor is authenticated
• Actor has document upload permission
• Document meets size and type requirements

Main Flow

1. Actor navigates to Documents → Upload
2. Selects file from local system
3. System validates:
   • File size (max 10MB)
   • File type (PDF, DOCX, DOC, JPG, PNG)
4. Enters document metadata:
   • Title (auto-filled from filename, editable)
   • Description (optional)
5. Selects visibility level (default based on role):
   • Private: Only uploader can access (default for Employees)
   • Manager: Uploader + direct manager
   • Team: Uploader's team members
   • Department: All department members
   • All Managers: All users with Manager role
   • All Employees: Everyone in tenant
   • Company: Everyone + featured in company docs (default for HR)
   • Specific People: Custom list of users/roles/departments
6. Adds tags from available options:
   • Contract
   • Policy
   • Onboarding
   • Confidential
   • Template
   • Custom tags
7. Clicks Upload
8. System:
   • Stores file in cloud storage
   • Creates metadata record
   • Generates RAG embeddings for AI search
9. Confirms successful upload

Alternative Flows

A1: File Too Large

1. System displays "File exceeds 10MB limit"
2. User must compress or split file

A2: Invalid File Type

1. System displays "File type not allowed"
2. Lists allowed types: PDF, DOCX, DOC, JPG, PNG

A3: Upload Fails

1. Network or storage error occurs
2. System displays error message
3. User can retry upload

Postconditions

• Document stored in cloud storage (Google Cloud Storage)
• Metadata record created in PostgreSQL
• RAG embeddings generated and stored in MongoDB
• Document appears in search results
• Audit log records upload

Business Rules

• Max file size: 10MB
• Allowed types: PDF, DOCX, DOC, JPG, PNG
• No executables (.exe, .sh, .bat)
• Visibility defaults to Private

UC-DOC-02: Search Documents (Traditional)

Primary Actor: All users

Preconditions

• User is authenticated
• Documents exist in tenant

Main Flow

1. User navigates to Documents
2. Enters search term in search bar
3. System searches across:
   • Document title
   • Description
   • Tags
   • Content (extracted text)
4. Results filtered by user's access level
5. Displays matching documents with:
   • Title and description
   • Tags (color-coded)
   • Upload date and owner
   • Visibility indicator
6. User can filter results:
   • By tag
   • By visibility level
   • By date range
   • By uploader
7. Clicks document to view/download

Alternative Flows

A1: No Results

1. Search returns no matching documents
2. System suggests:
   • Broadening search terms
   • Trying AI-powered search
   • Checking access permissions

A2: Access Denied

1. Document exists but user lacks access
2. Document not shown in results
3. (User never knows it exists)

Postconditions

• User sees matching documents they can access
• No access to documents outside permission scope

Search Capabilities

UC-DOC-03: AI-Powered Document Search (RAG)

Primary Actor: All users

Preconditions

• User is authenticated
• AI service is available
• Documents have RAG embeddings

Main Flow

1. User navigates to Documents → AI Search (or uses AI assistant)
2. Enters natural language question:
   • "What is our work from home policy?"
   • "How many vacation days do new employees get?"
3. System processes query:
   • Generates embedding for question
   • Searches MongoDB vector store
   • Retrieves relevant document chunks
   • Filters by user's access permissions
4. Displays results:
   • AI-generated answer summarizing relevant content
   • Source documents with relevant excerpts
   • Confidence indicator
5. User can click sources to view full documents

Alternative Flows

A1: No Relevant Documents

1. AI cannot find matching content
2. Responds: "I couldn't find information about that in the company documents."
3. Suggests contacting HR directly

A2: Multiple Sources

1. Answer draws from multiple documents
2. All sources listed with excerpts
3. User can explore each source

A3: Low Confidence

1. AI finds partial matches but low confidence
2. Displays: "I found some related information, but I'm not certain it answers your question."
3. Shows best matches with caveats

Postconditions

• User receives AI-generated answer
• Sources are cited for verification
• Query logged for analytics (anonymized)

RAG Architecture

┌──────────────────────────────────────────────────────┐
│                    AI Search Flow                    │
├──────────────────────────────────────────────────────┤
│                                                      │
│   User Query: "What is our parental leave policy?"   │
│                        │                             │
│                        ▼                             │
│              ┌─────────────────┐                     │
│              │ Generate Query  │                     │
│              │   Embedding     │                     │
│              └────────┬────────┘                     │
│                       │                              │
│                       ▼                              │
│              ┌─────────────────┐                     │
│              │ Vector Search   │ (MongoDB)           │
│              │ + Access Filter │                     │
│              └────────┬────────┘                     │
│                       │                              │
│                       ▼                              │
│              ┌─────────────────┐                     │
│              │ Retrieve Top    │                     │
│              │ Document Chunks │                     │
│              └────────┬────────┘                     │
│                       │                              │
│                       ▼                              │
│              ┌─────────────────┐                     │
│              │ Generate Answer │ (LLM)               │
│              │ with Citations  │                     │
│              └────────┬────────┘                     │
│                       │                              │
│                       ▼                              │
│   Answer: "According to the Employee Handbook,       │
│   new parents receive 12 weeks paid leave..."        │
│   [Source: Employee Handbook, pg 24]                 │
│                                                      │
└──────────────────────────────────────────────────────┘

UC-DOC-04: Ask AI About Policy

Primary Actor: Employee

Preconditions

• Employee is authenticated
• AI service is available
• Policy documents are uploaded with RAG embeddings

Main Flow

1. Employee opens AI Assistant (chat interface)
2. Types policy question in natural language:
   • "How do I request time off?"
   • "What's the dress code?"
   • "Can I work remotely on Fridays?"
   • "What holidays do we get?"
3. AI processes question using RAG
4. AI responds with:
   • Direct answer to the question
   • Source document reference
   • Link to full document if user wants more detail
5. Employee can ask follow-up questions
6. Conversation context is maintained within session

Alternative Flows

A1: Question Outside HR Scope

1. Employee asks non-HR question
2. AI responds: "I can only answer questions about company policies and HR information."
3. Suggests rephrasing or contacting appropriate department

A2: AI Cannot Answer

1. No relevant documents found
2. AI responds: "I don't have information about that. Please contact HR at hr@company.com"
3. Optionally creates support ticket

A3: Sensitive Topic

1. Employee asks about specific person or salary
2. AI declines: "I can't provide information about individual employees."
3. Directs to appropriate resource

Postconditions

• Employee receives answer or appropriate redirect
• Interaction logged for quality improvement
• No modification of any data

Example Conversations

Example 1: Policy Question

Employee: How many vacation days do I get per year?
AI: Full-time employees receive 20 vacation days per year, 
    accrued monthly. Part-time employees receive pro-rated 
    vacation based on hours worked.
    [Source: Employee Handbook, Section 4.2]

Example 2: Process Question

Employee: How do I submit an expense report?
AI: To submit an expense report:
    1. Navigate to Finance → Expenses
    2. Click "New Expense Report"
    3. Upload receipts and fill in details
    4. Submit for manager approval
    [Source: Finance Policy Document]

Example 3: Escalation

Employee: I have a complaint about my manager
AI: I'm sorry to hear that. For workplace concerns, please 
    contact HR directly at hr@company.com or use the 
    anonymous feedback form. Would you like me to provide 
    the link to the feedback form?

UC-DOC-05: Download/View Document

Primary Actor: Users with access

Preconditions

• User is authenticated
• User has access to the document
• Document exists

Main Flow

1. User finds document via search or browse
2. Clicks on document title
3. System verifies access permission
4. For viewable formats (PDF, images):
   • Opens inline viewer
   • User can zoom, scroll, navigate pages
5. Download button available for all formats
6. User clicks Download
7. File downloads to local system

Alternative Flows

A1: Access Denied

1. User somehow reaches document they can't access
2. System displays "Access Denied"
3. Does not reveal document contents

A2: Document Deleted

1. Document was deleted after user found it
2. System displays "Document not found"

A3: Large Document

1. Document is very large
2. Preview shows first pages only
3. Full download available

Postconditions

• User views or downloads document
• Access logged in audit trail
• Download count incremented

UC-DOC-06: Delete Document

Primary Actor: Document owner, Tenant Admin

Preconditions

• Actor is authenticated
• Actor owns document or is Tenant Admin
• Document exists

Main Flow

1. Actor navigates to document
2. Clicks Delete (or selects from menu)
3. System displays confirmation:
   • Document title
   • Warning that deletion is permanent
   • Note that RAG embeddings will be removed
4. Actor confirms deletion
5. System:
   • Removes file from cloud storage
   • Deletes metadata record
   • Removes RAG embeddings from MongoDB
6. Document no longer appears in search

Alternative Flows

A1: Bulk Delete

1. Actor selects multiple documents
2. Bulk delete option available
3. Confirmation shows all selected documents

A2: Document Referenced in Workflows

1. Document is linked in onboarding task
2. System warns about references
3. Deletion removes references (with confirmation)

Postconditions

• Document completely removed from system
• RAG embeddings deleted
• Audit log records deletion (but not document content)

Business Rules

• Only owner or Tenant Admin can delete
• Deletion is permanent (no soft delete for files)
• Metadata audit trail preserved

UC-DOC-07: Employee Interacts with AI Chatbot

Primary Actor: Employee

Preconditions

• Employee is authenticated
• AI service is available

Main Flow

1. Employee clicks AI Assistant icon (floating button or sidebar)
2. Chat interface opens
3. Employee types question or selects from suggested topics:
   • Time Off
   • Benefits
   • Policies
   • How To...
4. AI responds conversationally
5. Employee can:
   • Ask follow-up questions
   • Rate response (helpful/not helpful)
   • Request human help if unsatisfied
6. Conversation ends when employee closes chat

Alternative Flows

A1: AI Confused

1. AI cannot understand question
2. Asks for clarification
3. Suggests rephrasing

A2: Request Human Help

1. Employee clicks "Talk to HR"
2. System creates support ticket with conversation context
3. Employee receives confirmation

A3: After Hours

1. Employee asks time-sensitive question
2. AI answers if possible from documents
3. For urgent matters, provides emergency contact

Postconditions

• Employee question answered or escalated
• Conversation logged (for improvement)
• Support ticket created if escalated

Suggested Topics

UC-DOC-08: Tag Document

Primary Actor: Document owner, Manager, Tenant Admin

Preconditions

• Actor is authenticated
• Actor has permission to tag documents
• Document exists
• Tags are configured for Document asset type

Main Flow

1. Actor navigates to document details
2. Views current tags on document
3. Clicks "Add Tag"
4. Selects from available tags:
   • Contract
   • Policy
   • Onboarding
   • Confidential
   • Template
   • Custom tenant-defined tags
5. Tag is added with visual indicator
6. Saves changes

Alternative Flows

A1: Remove Tag

1. Actor clicks 'X' on existing tag
2. Tag is removed from document
3. Document no longer appears in tag-filtered searches

A2: Create New Tag (if permitted)

1. Actor has tag creation permission
2. Types new tag name
3. System creates tag and applies it

Postconditions

• Document tagged for organization
• Appears in tag-filtered searches
• Audit log records tag changes

Common Document Tags

UC-DOC-09: Employee Uploads Personal Document

Primary Actor: Employee

Preconditions

• Employee is authenticated
• Has document upload permission

Main Flow

1. Employee navigates to Documents → My Documents → Upload
2. Selects file from local system
3. System validates file (size, type)
4. Enters document metadata (title, description)
5. Visibility defaults to PRIVATE
6. Employee can optionally change to:
   • Manager: Share with direct manager
   • Specific People: Select specific colleagues
7. Adds optional tags
8. Uploads document

Alternative Flows

A1: Share with Manager

1. Employee selects "Share with My Manager"
2. Document visible to employee + direct manager only

A2: Share with Specific People

1. Employee clicks "Share with..."
2. Searches and selects specific colleagues
3. Each person can view/download

Postconditions

• Document stored with PRIVATE visibility (or as selected)
• Only authorized users can access
• Appears in employee's "My Documents" section

Example Use Cases

• Personal certifications
• Expense receipts
• Performance self-review drafts
• Project proposals to share with manager

UC-DOC-10: Employee Shares Document with Manager

Primary Actor: Employee

Preconditions

• Employee is authenticated
• Document exists and is owned by employee
• Document is currently PRIVATE

Main Flow

1. Employee navigates to own document
2. Clicks "Share" button
3. Selects "Share with My Manager"
4. Confirms sharing
5. System updates visibility to MANAGER
6. Manager receives notification (optional)

Alternative Flows

A1: Expand to Team

1. Employee wants broader sharing
2. If permitted, can select TEAM visibility
3. All team members gain access

A2: Revoke Access

1. Employee changes visibility back to PRIVATE
2. Manager loses access immediately
3. Audit log records change

Postconditions

• Document visibility updated
• Manager can now view/download
• Audit trail records sharing action

Business Rules

• Employee can always share with own manager
• Cannot share with higher visibility levels without permission
• Sharing can be revoked at any time

UC-DOC-11: HR Uploads Company Policy

Primary Actor: Tenant Admin, HR Manager

Preconditions

• Actor is authenticated with HR/Admin role
• Has company document upload permission

Main Flow

1. HR navigates to Documents → Company Documents → Upload
2. Selects policy file
3. System validates file
4. Enters metadata:
   • Title: "Employee Handbook 2024"
   • Description: "Complete guide to company policies"
   • Category: Policy
5. Visibility defaults to COMPANY (all employees)
6. Can optionally restrict to:
   • All Employees: Everyone can access
   • All Managers: Only managers can access
   • Department: Specific department(s)
   • Specific People: Selected individuals
7. Adds tags (Policy, Handbook, 2024)
8. Uploads document

Alternative Flows

A1: Manager-Only Document

1. HR uploads sensitive document
2. Selects "All Managers" visibility
3. Only users with Manager role can access
4. Example: Management compensation guidelines

A2: Department-Specific Policy

1. HR uploads Engineering-specific policy
2. Selects "Department: Engineering"
3. Only Engineering employees can access

Postconditions

• Document uploaded with selected visibility
• Appears in Company Documents section
• RAG embeddings created for AI search
• All authorized users can access

Example Documents

• Employee Handbook
• PTO Policy
• Remote Work Guidelines
• Code of Conduct
• Benefits Summary

UC-DOC-12: HR Shares Document with Specific Group

Primary Actor: Tenant Admin, HR Manager

Preconditions

• Actor is authenticated with HR/Admin role
• Document exists (new or existing)

Main Flow

1. HR uploads or selects existing document
2. Chooses SPECIFIC visibility
3. Adds recipients using flexible selector:
   • By User: Search and select individuals
   • By Role: Select "All Managers", "All HR"
   • By Department: Select one or more departments
   • By Team: Select specific teams
4. For each recipient, sets permission:
   • View only
   • View + Download
5. Optionally sets expiration date
6. Saves visibility settings

Alternative Flows

A1: Confidential Executive Document

1. HR uploads executive compensation report
2. Selects SPECIFIC visibility
3. Adds only: CEO, CFO, HR Director
4. Sets to expire after 30 days

A2: Cross-Department Sharing

1. HR uploads reorg plan
2. Shares with: Department Heads + HR Team
3. Excludes affected employees until announcement

Postconditions

• Document visible only to specified recipients
• Each recipient type (user/role/dept) can access
• Expiration enforced if set
• Audit trail records all access

Recipient Options

UC-DOC-13: Manager Shares Team Document

Primary Actor: Manager

Preconditions

• Manager is authenticated
• Has team document upload permission
• Has direct reports

Main Flow

1. Manager navigates to Documents → Team Documents → Upload
2. Selects file (meeting notes, project doc)
3. Enters metadata
4. Visibility defaults to TEAM (direct reports)
5. Can expand to:
   • Department: Entire department
   • All Managers: Other managers
   • Specific People: Add individuals
6. Adds tags
7. Uploads document

Alternative Flows

A1: Cross-Team Collaboration

1. Manager working with another team
2. Selects SPECIFIC visibility
3. Adds own team + collaborating team members

A2: Restrict Within Team

1. Manager has sensitive doc for some team members
2. Selects SPECIFIC visibility
3. Adds only relevant team members

Postconditions

• Document shared with team
• Appears in team's shared documents
• Manager retains ownership

Example Documents

• Team meeting notes
• Project documentation
• Team processes and guidelines
• Training materials

UC-DOC-14: User Views Accessible Documents

Primary Actor: All users

Preconditions

• User is authenticated
• Documents exist in tenant

Main Flow

1. User navigates to Documents
2. System displays documents organized by section:
   • My Documents: Documents user uploaded (PRIVATE)
   • Shared with Me: Documents others shared with user
   • Team Documents: TEAM visibility docs from user's team
   • Company Documents: COMPANY visibility docs
3. Each document shows:
   • Title and description
   • Tags (color-coded)
   • Visibility indicator icon
   • Upload date and owner
4. User can filter by:
   • Section (My/Shared/Team/Company)
   • Tags
   • Date range
   • Search term
5. Clicks document to view/download

Alternative Flows

A1: No Access to Document

1. User searches for document
2. If no access, document not shown in results
3. User never knows it exists (security by obscurity)

A2: Shared Document Expired

1. Document had expiration date
2. After expiry, removed from user's view
3. Audit log records access revocation

Postconditions

• User sees only authorized documents
• Clear organization by visibility type
• Easy navigation and filtering

Document Sections View

┌────────────────────────────────────────────────────────────┐
│ Documents                                      [+ Upload]  │
├────────────────────────────────────────────────────────────┤
│                                                            │
│ 📁 My Documents (5)                                        │
│    └── Personal files only you can see                     │
│                                                            │
│ 📤 Shared with Me (12)                                     │
│    └── Documents others have shared with you               │
│                                                            │
│ 👥 Team Documents (8)                                      │
│    └── Shared by your team members                         │
│                                                            │
│ 🏢 Company Documents (24)                                  │
│    └── Company-wide policies and resources                 │
│                                                            │
├────────────────────────────────────────────────────────────┤
│ 🔍 Search documents...    [Filter by: Tags ▼] [Date ▼]    │
└────────────────────────────────────────────────────────────┘

Summary

Document Visibility Model

Visibility Levels (Hierarchical)

┌─────────────────────────────────────────────────────────────┐
│                    VISIBILITY HIERARCHY                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Level 1: PRIVATE (Default for Employees)                  │
│   └── Only document owner can access                        │
│                                                             │
│   Level 2: MANAGER                                          │
│   └── Owner + Owner's direct manager                        │
│                                                             │
│   Level 3: TEAM                                             │
│   └── Owner + All members of owner's team                   │
│                                                             │
│   Level 4: DEPARTMENT                                       │
│   └── Owner + All members of owner's department             │
│                                                             │
│   Level 5: ALL_MANAGERS                                     │
│   └── All users with Manager role                           │
│                                                             │
│   Level 6: ALL_EMPLOYEES                                    │
│   └── Everyone in the tenant                                │
│                                                             │
│   Level 7: COMPANY (Default for HR uploads)                 │
│   └── Everyone + appears in company docs section            │
│                                                             │
│   Level 8: SPECIFIC_PEOPLE                                  │
│   └── Custom list of users/roles/departments                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Default Visibility by Uploader Role

Visibility Icons

Permission Matrix

AI Chat Integration

Documents is a core AI feature. UC-DOC-03 (AI Search), UC-DOC-04 (Policy Q&A), and UC-DOC-07 (AI Chatbot) are the primary AI Chat interactions. See AI Chat Specification for full implementation details.

AI Chat-Enabled Actions

UC-DOC-03: AI-Powered Document Search via Chat

Example prompts:

• "Find the remote work policy"
• "Search for vacation policy documents"
• "What documents mention parental leave?"
• "Find engineering onboarding materials"

AI Chat Flow:

User: "Find the remote work policy"

AI: Shows Search Results Card
┌─────────────────────────────────────────────┐
│ Document Search Results                     │
│ Query: "remote work policy"                 │
│                                             │
│ Found 3 relevant documents:                 │
│                                             │
│ 1. Remote Work Policy 2024 (98% match)      │
│    Policy | Updated: Nov 15, 2024           │
│    "Guidelines for remote and hybrid..."    │
│    [View Document]                          │
│                                             │
│ 2. Employee Handbook (72% match)            │
│    Handbook | Section: Remote Work          │
│    "Chapter 8 covers remote work..."        │
│    [View Document]                          │
│                                             │
│ 3. IT Equipment Policy (45% match)          │
│    Policy | Section: Home Office Setup      │
│    [View Document]                          │
│                                             │
│ [Search Again] [Ask About These]            │
└─────────────────────────────────────────────┘

UC-DOC-04: Policy Q&A via AI Chat

Example prompts:

• "What's our parental leave policy?"
• "How do I submit an expense report?"
• "What are the company holidays this year?"
• "What's the dress code?"

AI Chat Flow:

User: "What's our parental leave policy?"

AI: Shows Answer Card (with sources)
┌─────────────────────────────────────────────┐
│ Answer from Company Documents               │
│                                             │
│ Based on the Employee Handbook (2024):      │
│                                             │
│ Primary caregivers receive 12 weeks of      │
│ fully paid parental leave. Secondary        │
│ caregivers receive 4 weeks. Leave can be    │
│ taken within 12 months of birth/adoption.   │
│                                             │
│ Additional details:                         │
│ - Can be combined with FMLA                 │
│ - Part-time return options available        │
│ - Benefits continue during leave            │
│                                             │
│ Sources:                                    │
│ - Employee Handbook, Chapter 5 (page 23)    │
│ - Parental Leave FAQ (updated Nov 2024)     │
│                                             │
│ [View Full Policy] [Ask Follow-up]          │
└─────────────────────────────────────────────┘

UC-DOC-07: Interactive AI Chatbot

Example conversation:

Employee: "I'm having a baby, what do I need to do?"

AI: Shows Guided Response
┌─────────────────────────────────────────────┐
│ Congratulations! Here's what you need to    │
│ know about parental leave at our company:   │
│                                             │
│ 1. Notify HR at least 30 days before leave  │
│ 2. Submit leave request in the system       │
│ 3. You're eligible for 12 weeks paid leave  │
│ 4. Benefits continue during your leave      │
│                                             │
│ Would you like me to help you with:         │
│ • [Submit parental leave request]           │
│ • [View full parental leave policy]         │
│ • [Calculate my leave dates]                │
│ • [Ask another question]                    │
│                                             │
│ Or type your follow-up question below.      │
└─────────────────────────────────────────────┘

Employee: "Submit parental leave request"

AI: Shows Confirmation Card
┌─────────────────────────────────────────────┐
│ Submit Parental Leave Request               │
│                                             │
│ Type: Parental Leave                        │
│ Duration: 12 weeks                          │
│ Expected Start: (please select)             │
│                                             │
│ What's your expected leave start date?      │
│                                             │
│ [Select Date]                               │
└─────────────────────────────────────────────┘

AI Chat Widget Specifications for Documents

Search Results Widget

interface SearchResultWidget {
  type: 'search_results'
  query: string
  results: Array<{
    title: string
    matchScore: number // 0-100
    category: string
    excerpt: string
    documentId: string
  }>
  totalResults: number
  actions: ['view', 'ask_about']
}

Answer Widget (with RAG sources)

interface AnswerWidget {
  type: 'answer'
  answer: string
  confidence: 'high' | 'medium' | 'low'
  sources: Array<{
    documentTitle: string
    section?: string
    pageNumber?: number
    documentId: string
  }>
  actions: ['view_sources', 'ask_followup']
}

Guided Response Widget

interface GuidedResponseWidget {
  type: 'guided_response'
  message: string
  suggestedActions: Array<{
    label: string
    action: string // tool to invoke
    params?: Record<string, any>
  }>
  allowFreeformFollowup: boolean
}

Business Rules for AI Chat Document Actions