Work Hub

Integration-first workspace connecting meeting transcription, email ingestion, document import, task management, AI-assisted drafting, calendar management, and automated research dispatch into a unified pipeline. Central task hub for all Haiven agents.

Overview

What It Does

Work Hub closes the loop between meetings, emails, deliverables, calendar, and automated research:

1. Receives approved meeting notes from Meeting Scribe via HMAC-verified webhook
2. Automatically ingests emails from any IMAP mailbox (polling, deduplication, attachment extraction)
3. Sends email via Microsoft Graph API (O365) with rate limiting and knowledge base logging
4. Manages calendar events via Microsoft Graph API — list, create, delete with conflict detection
5. Chunks and embeds all content into Qdrant for semantic search (2560-dim, Cosine)
6. Extracts and tracks tasks with company/project/tag/source taxonomy
7. Generates AI drafts by searching accumulated knowledge via RAG (meetings + docs + emails)
8. Supports historical import of documents, audio/video, PST archives, and batch backfill of Meeting Scribe notes
9. Accepts file uploads of PDF, DOCX, EML, HTML, CSV, ICS, and plain text via browser drag-and-drop
10. Auto-dispatches research tasks to the research-agent when a task is created with status queued and "Research:" in its title
11. Stores artifacts and voice instructions on tasks for agent write-back integration

Architecture

work.haiven.site (Traefik HTTPS)
        │
        ├── work-hub-frontend (React 19 SPA, nginx, port 3025)
        │     └── /api → reverse proxy to backend
        │
        └── work-hub (FastAPI, port 8030)
              ├── work-hub-db (PostgreSQL 16, port 5437)
              ├── qdrant:6333 (documents collection, 2560d, Cosine)
              ├── litellm:4000 (qwen3-embedding-4b + glm-4-7-flash)
              ├── haiven-knowledge:8022 (email send KB logging)
              ├── meeting-scribe:5010 (webhook source)
              └── research-agent:8000 (auto-dispatch via ResearchDispatcher)

Three containers: work-hub (FastAPI backend), work-hub-frontend (React SPA via nginx), work-hub-db (PostgreSQL 16)

Networks: web (frontend via Traefik), backend (all three containers)

GPU: None — embedding and LLM calls route through LiteLLM

Features

• Task Management: Create, edit, filter tasks with company/project/tag/source/source_application taxonomy. Status and priority tracking with full FSM-validated status transitions.
• Task Status FSM: Enforced transition graph — open → in_progress → done/blocked/archived, queued → context_ready → in_progress, blocked → in_progress.
• Task History: Full audit trail of every field change recorded in history JSONB array with timestamp, actor, and from/to values.
• Voice Instructions: Append timestamped voice instructions to tasks via PATCH /api/v1/tasks/{id}/voice-instructions; each entry carries processed: false flag for agent workflows.
• Artifact Write-Back: Research agent and briefing agent write structured artifacts to tasks via PATCH /api/v1/tasks/{id}/artifacts.
• Research Auto-Dispatch: Background poller (ResearchDispatcher) checks every 60 seconds for tasks with status=queued and "research" in the title. Automatically transitions queued → context_ready → in_progress and POSTs to research-agent with the task ID.
• AI Draft Generation: Click Draft on any task — RAG searches Qdrant for relevant context from meetings, docs, and emails; glm-4-7-flash generates a versioned draft.
• Email Send (Microsoft Graph): Send email via O365 with rate limiting (20/hr sliding window). Supports thread reply via thread_id. Logs each send to haiven-knowledge KB. Optional EMAIL_SIGNATURE appended automatically.
• Calendar Management (Microsoft Graph): Full CRUD for O365 calendar events — list events in a date range, create events with attendees and conflict detection (HTTP 409), delete events by ID.
• Meeting Browser: Semantic search across all embedded meeting notes. View full markdown-rendered meeting content.
• Taxonomy Management: Full CRUD for companies, projects, and tags. AI-discovered entity flagging.
• Document Import: Import single documents or full directories. Auto-chunked, embedded, and searchable.
• File Upload: Drag-and-drop or click-to-browse upload of PDF, DOCX, EML, HTML, CSV, ICS, and plain text (50 MB limit). Format-specific text extraction and smart chunking.
• PST Archive Import: Upload Outlook PST archives — readpst extracts all emails and calendar items, deduplicates by Message-ID, and ingests with full email metadata.
• Audio/Video Transcription: Upload MP3, M4A, WAV, OGG, WEBM, MP4, or FLAC files (500 MB limit); routed to haiven-transcribe for transcription, then embedded into Qdrant.
• IMAP Email Connector: Automated polling of any IMAP mailbox — UID-based incremental sync, attachment ingestion, rich metadata (14 fields per email).
• Backfill Pipeline: Ingest all historical Meeting Scribe notes in one operation with dry-run preview.
• Webhook Integration: Receives approved meetings from Meeting Scribe (HMAC-SHA256 verified).
• Health Monitoring: /health endpoint checks PostgreSQL, Qdrant, and LiteLLM connectivity.

Supported Import Formats

Prerequisites

Configuration

All environment variables use the WH_ prefix, except Microsoft Graph and email signature vars.

Core Settings

Transcription Settings

Research Auto-Dispatch Settings

The ResearchDispatcher polls every 60 seconds for status=queued tasks with "research" in the title. It transitions the task queued → context_ready → in_progress and POSTs to {WH_RESEARCH_URL}/research with {"query": "<title without prefix>", "task_id": "<uuid>", "auto_approve": true}.

IMAP Email Connector Settings

Microsoft Graph (Email Send + Calendar)

Both email send and calendar management share one Azure app registration. The OAuth2 refresh token flow is used (no interactive login required at runtime).

Required Azure AD scopes: https://graph.microsoft.com/Mail.Send, https://graph.microsoft.com/Calendars.ReadWrite, offline_access

When these variables are absent, the email send and calendar endpoints return 503 Service Unavailable.

Secrets are stored in /mnt/apps/docker/ai/work-hub/.env.

Database Schema

Nine PostgreSQL tables (all primary keys are UUIDs, all timestamps are timezone-aware):

Task Status FSM

Valid status transitions enforced by validate_status_transition():

open → in_progress → done
open → in_progress → blocked → in_progress
open → archived
queued → context_ready → in_progress
in_progress → done
in_progress → archived
done → archived

Qdrant Integration

Payload fields: document_id, doc_type, source, company, project, topics[], tags[], title, content, attendees[], meeting_type, scribe_job_id, source_file, created_at, ingested_at, chunk_index, total_chunks, email_from, email_to, email_cc, email_subject, email_date, email_message_id, email_in_reply_to, email_references, email_folder, email_importance, email_has_attachments, email_attachment_count, email_attachment_names, email_list_unsubscribe, email_account, parent_email_message_id, calendar_uid, calendar_summary, calendar_start, calendar_event_count, calendar_attendees

Indexed for filtering: doc_type, source, company, project, topics, tags, meeting_type, scribe_job_id (keyword); created_at (datetime)

API Endpoints

50+ endpoints across 10 groups:

Key endpoints:

GET  /health                                    # Service health (postgres, qdrant, litellm)

# Tasks
GET  /api/v1/tasks                              # List tasks (status, priority, company_id, project_id, assignee, source, source_application)
POST /api/v1/tasks                              # Create task
GET  /api/v1/tasks/{id}                         # Task detail
PATCH /api/v1/tasks/{id}                        # Update task (FSM-validated status transitions)
DELETE /api/v1/tasks/{id}                       # Hard-delete task
PATCH /api/v1/tasks/{id}/voice-instructions     # Append voice instruction
PATCH /api/v1/tasks/{id}/artifacts              # Append artifact reference
GET  /api/v1/tasks/{id}/history                 # Full change history array
POST /api/v1/tasks/{id}/draft                   # Generate AI draft (RAG + glm-4-7-flash)
GET  /api/v1/tasks/{id}/drafts                  # Draft history

# Meetings
GET  /api/v1/meetings                           # List meetings
GET  /api/v1/meetings/{id}                      # Meeting detail
POST /api/v1/meetings/search                    # Semantic search over meeting notes

# Taxonomy
GET  /api/v1/companies                          # List companies
POST /api/v1/companies                          # Create company
GET  /api/v1/companies/{id}                     # Company detail
PATCH /api/v1/companies/{id}                    # Update company
DELETE /api/v1/companies/{id}                   # Delete company
GET  /api/v1/projects                           # List projects (filter by company_id, status)
POST /api/v1/projects                           # Create project
GET  /api/v1/projects/{id}                      # Project detail
PATCH /api/v1/projects/{id}                     # Update project
DELETE /api/v1/projects/{id}                    # Delete project
GET  /api/v1/tags                               # List tags
POST /api/v1/tags                               # Create tag
DELETE /api/v1/tags/{id}                        # Delete tag

# Import
POST /api/v1/import/document                    # Import single document (text/markdown)
POST /api/v1/import/upload                      # Multipart file upload (PDF, DOCX, EML, HTML, CSV, ICS, MD, TXT)
POST /api/v1/import/audio                       # Audio/video transcription import
POST /api/v1/import/directory                   # Import directory batch
POST /api/v1/import/pst                         # Outlook PST archive import

# Backfill
POST /api/v1/backfill/scribe-notes              # Backfill Meeting Scribe notes

# Webhooks
POST /api/webhooks/scribe                       # Scribe webhook receiver (HMAC-verified)

# Email — IMAP connector
POST /api/v1/email/sync                         # Trigger immediate incremental IMAP sync
POST /api/v1/email/backfill                     # Date-range email backfill
GET  /api/v1/email/status                       # Per-folder IMAP sync state
GET  /api/v1/email/config                       # IMAP config with password masked
GET  /api/v1/email/folders                      # Live IMAP folder list
POST /api/v1/email/send                         # Send email via Microsoft Graph (20/hr rate limit)

# Calendar — Microsoft Graph
GET  /api/v1/calendar/events                    # List events in date range
POST /api/v1/calendar/events                    # Create calendar event (409 on conflict)
DELETE /api/v1/calendar/events/{id}             # Delete calendar event

Full interactive docs at https://work.haiven.site/api/docs.

Task Filtering Parameters

GET /api/v1/tasks accepts these query parameters for filtering:

Agent Integration Endpoints

For agent-to-work-hub write-back:

# Append a voice instruction to a task
PATCH /api/v1/tasks/{id}/voice-instructions
{"instruction": "Make the summary shorter and focus on action items"}

# Append an artifact (research output, briefing draft, etc.)
PATCH /api/v1/tasks/{id}/artifacts
{"type": "research_output", "path": "<session_id>"}

# Update task status and context (research agent write-back)
PATCH /api/v1/tasks/{id}
{"status": "done", "context": "<JSON summary from research>"}

Deployment

First-Time Setup

# Create .env file
cat > /mnt/apps/docker/ai/work-hub/.env <<EOF
POSTGRES_USER=workhub
POSTGRES_PASSWORD=<strong-password>
POSTGRES_DB=workhub
WH_LITELLM_API_KEY=<litellm-api-key>
WH_WEBHOOK_SECRET=<random-32-char-hex>
# Research auto-dispatch
WH_RESEARCH_URL=http://research-agent:8000
# Optional: Microsoft Graph (email send + calendar)
# CONN_EMAIL_OAUTH2_CLIENT_ID=<azure-app-client-id>
# CONN_EMAIL_OAUTH2_CLIENT_SECRET=<azure-app-client-secret>
# CONN_EMAIL_OAUTH2_TENANT_ID=<azure-tenant-id>
# CONN_EMAIL_OAUTH2_REFRESH_TOKEN=<long-lived-refresh-token>
# EMAIL_SIGNATURE=Your Name | Title
# Optional: IMAP email connector
# WH_IMAP_ENABLED=true
# WH_IMAP_HOST=imap.gmail.com
# WH_IMAP_USERNAME=you@example.com
# WH_IMAP_PASSWORD=<app-password>
# WH_IMAP_FOLDERS=INBOX,Sent
EOF

# Start all three containers
cd /mnt/apps/docker/ai/work-hub
docker compose up -d

# Wait for DB to initialize, then backfill historical notes
sleep 10
curl -X POST https://work.haiven.site/api/v1/backfill/scribe-notes

Start / Stop

cd /mnt/apps/docker/ai/work-hub
docker compose up -d        # Start all containers
docker compose down         # Stop (preserves DB volume)
docker compose restart work-hub  # Restart backend only

Rebuild After Source Changes

cd /mnt/apps/docker/ai/work-hub
docker compose build work-hub --no-cache
docker compose up -d work-hub

View Logs

docker logs -f work-hub            # Backend
docker logs -f work-hub-frontend   # Frontend (nginx)
docker logs -f work-hub-db         # PostgreSQL

Health Check

curl https://work.haiven.site/api/health
# Returns: {"status": "healthy", "postgres": true, "qdrant": true, "litellm": true, "version": "1.0.0"}

Resource Limits

Monitoring

Prometheus labels are set on the work-hub container:

prometheus.io/scrape: "true"
prometheus.io/port: "8030"
prometheus.io/path: "/metrics"

The /metrics endpoint exposes standard FastAPI/uvicorn process metrics.

Webhook Integration

Meeting Scribe sends approved meeting notes to Work Hub via HTTP webhook:

POST /api/webhooks/scribe
X-Hub-Signature-256: sha256=<hmac>
Content-Type: application/json

{
  "version": 1,
  "job_id": "uuid",
  "title": "Meeting Title",
  "notes_md": "## Agenda\n...",
  "tasks": [],
  "decisions": [],
  "metadata": {}
}

The webhook handler verifies HMAC-SHA256 using WH_WEBHOOK_SECRET, then chunks and embeds the notes into Qdrant and records the meeting in PostgreSQL.

Research Auto-Dispatch

The ResearchDispatcher runs as a background asyncio task inside the work-hub process:

1. Every 60 seconds, it queries PostgreSQL for tasks with status=queued and "research" in the title (case-insensitive).
2. For each matched task, it transitions: queued → context_ready → in_progress (via direct DB update, respecting FSM rules).
3. It strips the "Research: " prefix from the title and POSTs to {WH_RESEARCH_URL}/research:
   json { "query": "RAGAS framework comparison", "task_id": "uuid", "auto_approve": true }
4. The research-agent runs the pipeline and writes artifacts back via PATCH /api/v1/tasks/{id}/artifacts.

To trigger a research task manually:

curl -X POST https://work.haiven.site/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Research: RAGAS framework comparison",
    "status": "queued",
    "source": "agent",
    "source_application": "manual"
  }'
# Within 60 seconds the task transitions to in_progress and research-agent begins

Microsoft Graph Integration

Work Hub integrates with Microsoft 365 via the Graph API for two capabilities: sending email and managing calendar events. Both use the same Azure AD app registration and the OAuth2 refresh token flow — no interactive login is required at runtime.

Email Send

• Endpoint: POST /api/v1/email/send
• Rate limit: 20 sends per hour (in-memory sliding window)
• Thread reply: Pass thread_id (a Message-ID) to set In-Reply-To and References headers
• Signature: Set EMAIL_SIGNATURE env var; appended to every outbound message automatically
• KB logging: Each send is logged to haiven-knowledge (http://haiven-knowledge:8022/v1/ingest/text) as a fire-and-forget background task

curl -X POST https://work.haiven.site/api/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "colleague@example.com",
    "subject": "Follow-up from today'\''s meeting",
    "body": "Hi,\n\nJust following up on the action items..."
  }'

Calendar Events

• List: GET /api/v1/calendar/events?start=2026-03-01T00:00:00Z&end=2026-03-08T00:00:00Z — returns up to 50 events ordered by start time
• Create: POST /api/v1/calendar/events — creates event with attendees; returns 409 Conflict if a scheduling conflict is detected
• Delete: DELETE /api/v1/calendar/events/{event_id}

curl -X POST https://work.haiven.site/api/v1/calendar/events \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Sprint Planning",
    "start": "2026-03-10T14:00:00Z",
    "end": "2026-03-10T15:00:00Z",
    "attendees": ["alice@example.com", "bob@example.com"],
    "description": "Q1 sprint kickoff"
  }'

IMAP Email Connector

When WH_IMAP_ENABLED=true, Work Hub polls the configured IMAP mailbox in the background:

• Polling interval: Every WH_IMAP_POLL_INTERVAL seconds (default 5 minutes)
• Incremental sync: UID-based — only downloads messages not yet seen
• Deduplication: By Message-ID stored in Document.source_file — re-syncing never creates duplicates
• UIDVALIDITY detection: Detects server-side folder rebuilds and triggers a full re-sync of the affected folder only
• Attachment ingestion: PDF, DOCX, HTML, TXT, MD, CSV, and EML attachments are extracted and embedded as separate documents linked by parent_email_message_id
• 14 metadata fields: From, To, Cc, Subject, Date, Message-ID, In-Reply-To, References, folder, importance (high/normal/low), has_attachments, attachment_count, attachment_names, list_unsubscribe

Email metadata endpoints return 503 Service Unavailable when WH_IMAP_ENABLED=false.

Triggering a Manual Sync

# Trigger immediate incremental sync
curl -X POST https://work.haiven.site/api/v1/email/sync

# Backfill emails from the past 7 days
curl -X POST "https://work.haiven.site/api/v1/email/backfill?since_date=2026-02-12&before_date=2026-02-19"

# Check sync state per folder
curl https://work.haiven.site/api/v1/email/status

# List available folders on the IMAP server
curl https://work.haiven.site/api/v1/email/folders

Troubleshooting

Backend fails to start

# Check database is healthy
docker ps --filter name=work-hub-db --format "{{.Status}}"

# Check logs for startup errors
docker logs work-hub --tail 50

# Verify .env is present and has required secrets
grep -v PASSWORD /mnt/apps/docker/ai/work-hub/.env

Draft generation returns no context

The AI draft agent searches Qdrant for relevant content. If no context is found:

# Check collection has data
curl http://localhost:6333/collections/documents

# Verify embedding model is available in LiteLLM
curl http://localhost:4000/v1/models | grep qwen3-embedding

Research dispatcher not firing

# Check dispatcher is running in logs
docker logs work-hub --tail 50 | grep -i "dispatcher"

# Verify task has status=queued and "research" in title
curl https://work.haiven.site/api/v1/tasks?status=queued | python3 -m json.tool

# Check WH_RESEARCH_URL is set
docker inspect work-hub | grep -A1 WH_RESEARCH

Email send fails with 503

# Verify Graph OAuth2 credentials are set
docker inspect work-hub | grep -i "CONN_EMAIL"

# Check rate limiter — max 20 sends per hour
docker logs work-hub --tail 50 | grep -i "rate limit\|email"

Calendar returns 503

# Verify the same CONN_EMAIL_OAUTH2_* vars are set (shared with email send)
docker inspect work-hub | grep -i "CONN_EMAIL_OAUTH2"

File upload fails

# Check file size (50 MB limit for documents, 500 MB for audio)
ls -lh /path/to/file

# Verify supported format
# Documents: .pdf .docx .eml .html .htm .csv .ics .md .txt
# Audio: .mp3 .m4a .wav .ogg .webm .mp4 .flac
# Check backend logs for extraction errors
docker logs work-hub --tail 50 | grep -i "upload\|extract"

PST import fails

# Verify readpst is installed inside the container
docker exec work-hub which readpst

# Check logs for extraction errors
docker logs work-hub --tail 50 | grep -i "pst\|readpst"

IMAP connector not syncing

# Verify feature flag is enabled
grep WH_IMAP_ENABLED /mnt/apps/docker/ai/work-hub/.env

# Check sync state for errors
curl https://work.haiven.site/api/v1/email/status | python3 -m json.tool

# Check backend logs for IMAP errors
docker logs work-hub --tail 100 | grep -i "imap\|email"

Webhook signature mismatch

Verify WH_WEBHOOK_SECRET matches the secret configured in Meeting Scribe. The signature is HMAC-SHA256 of the raw request body.

Container can't reach Qdrant

# Verify both services are on backend network
docker network inspect backend | grep -E "work-hub|qdrant"

# Test connectivity from inside container
docker exec work-hub curl -sf http://qdrant:6333/health

Frontend gets 502 from /api proxy

The nginx frontend proxies /api to http://work-hub:8030. Verify the backend container is healthy:

docker ps --filter name=work-hub --format "{{.Status}}"
curl http://localhost:8030/health

Project Status

All phases complete. Production-ready with 3 healthy containers. Integrated with research-agent (auto-dispatch), agent-briefing (task read/write), haiven-notification-hub, and Microsoft 365 (email send + calendar).

Related Services

• Meeting Scribe — Sends approved meeting notes via webhook
• Research Agent — Receives auto-dispatched research tasks; writes artifacts back
• Agent Briefing — Reads tasks for daily/EOD briefings; appends artifacts
• Qdrant — Vector database backend (documents collection)
• LiteLLM — Embedding (qwen3-embedding-4b) and LLM proxy (glm-4-7-flash)
• haiven-transcribe — Audio/video transcription engine (Canary/Parakeet/Whisper Turbo)
• haiven-knowledge — Knowledge base for email send logging