← Back to App

Epok Advisor Docs

Key User Flows

The Engagement Lifecycle

An engagement is the core unit of work — one advisor going through the Epok process. Every engagement follows a structured path with defined milestones.

Milestones (Progress Tracker)

The engagement has a visual milestone tracker in the Overview tab. Kendra manually marks each milestone complete.

[1] Intake         → Client signs up, pays deposit, receives questionnaire
[2] Discovery      → Questionnaire completed, initial docs submitted, first call
[3] Workshop 1     → Hypothesis testing session — themes identified
[4] Workshop 2     → Draft report review — co-creation with client
[5] Workshop 3     → Accountability & handoff — final report
[6] Complete       → Report delivered, optional ongoing setup

Each milestone has a corresponding "MS:" tag. The Overview tab shows "View docs" links that filter the Documents tab by the milestone's tag.

Visual states: Completed (colored, with date) · Current (highlighted) · Upcoming (greyed out)

Flow 1: Create & Prepare Engagement

  1. Kendra logs in (Google OAuth via @epokadvice.com)
  2. From Engagements list, clicks "New Engagement"
  3. Fills in advisor name, email, firm name, AUM range, optional notes
  4. System creates engagement + seeds 6 milestones (step 1 = current)
  5. Engagement detail shows 4 tabs: Overview, Documents, Questionnaires, Analysis
  6. Kendra prepares:
    • Creates engagement-scoped documents and folders
    • Assigns a questionnaire template to the engagement
    • Writes internal notes
    • Optionally assigns an associate

Flow 2: Questionnaire Workflow

  1. Kendra goes to top-level Questionnaires section in sidebar
  2. Creates or selects a questionnaire template (versioned question builder)
  3. Question types: text, textarea, select, multi-select, scale, yes/no
  4. From engagement Questionnaires tab, starts a new response linked to a published template version
  5. Three respondent modes:
    • Interviewer: Kendra fills in answers during a call
    • Client: Advisor fills in via their portal
    • Agent: AI fills in from engagement context (AI-assisted answer filling)
  6. AI fill: sends each question + engagement documents to LLM, auto-populates draft answers
  7. Completed responses are saved and available as context for analysis

Flow 3: Workshop & Content Capture

For each workshop:

  1. Pre-workshop: Review AI chat insights, prepare talking points using the KB
  2. During workshop: Kendra runs the session (external: Google Meet, Zoom, Otter.ai)
  3. Post-workshop:
    • Otter.ai recording auto-ingested via Zapier → /api/v1/ingest → lands in KB Inbox as Summary + Transcript documents
    • Kendra reviews in KB, uses "File to Engagement" to move docs into the engagement with milestone tag
    • Creates additional notes as engagement documents
    • Marks milestone complete in Overview tab

Flow 4: AI Chat

Available on every admin page via the slide-out chat panel (right side):

  1. User types a question or instruction
  2. System embeds the query → retrieves top-5 relevant document chunks via pgvector cosine similarity
  3. Retrieved context + user message sent to Claude Sonnet (default) or GPT-4o
  4. Response streamed via SSE
  5. Agent tools available: search KB, read documents, list engagements, create notes
  6. Chat history persisted per session in chat_messages table
  7. Model selector in chat header to switch between Claude and GPT-4o

Flow 5: AI Analysis

Per-engagement analysis with document references:

  1. From engagement Analysis tab, click "New Analysis"
  2. Write a prompt using the @-mention editor — type @ to search and reference specific engagement or KB documents
  3. Referenced documents become analysis inputs (linked via analysis_inputs table)
  4. Select model: Claude Sonnet (default), GPT-4o, or GPT-4o Mini
  5. Click Run → streaming LLM execution via SSE with real-time output display
  6. On completion, output is auto-saved as a content document tagged "Analysis Output" and linked to the engagement
  7. Refinement: Click "Refine with AI" → enter refinement instructions → current output + instructions sent back through the streaming endpoint to produce an updated version
  8. Analysis detail view shows full output with export options

Flow 6: Knowledge Base Management

  1. Navigate to Knowledge Base in sidebar (badge shows unfiled inbox doc count)
  2. Folder tree in left panel with nested folders, document list in main area
  3. Create folders, move documents between folders
  4. Tag documents with classification labels (multi-select)
  5. Filter by tag — clicking a tag shows all documents with that tag across all folders
  6. Create new documents with TipTap editor (rich WYSIWYG or raw markdown toggle)
  7. Version history sidebar shows all versions with timestamps and change summaries
  8. Publish → auto-embeds for AI search
  9. File to Engagement: On unfiled KB docs, select engagement + optional milestone tag → moves doc to engagement scope
  10. Inbox: Auto-ingested content (Otter.ai transcripts) lands here for triage

Flow 7: Export & Sharing

From any document or analysis output, the Copy & Export menu provides:

  1. Copy: Markdown source, plain text, or rich text (HTML) to clipboard
  2. Google Docs:
    • First use: OAuth redirect to connect Google account (tokens stored in profile)
    • Creates new Google Doc with title, formatted content
    • Optional: select target Google Drive folder via folder picker
  3. Gamma:
    • Choose format: Document, Presentation, or Webpage
    • POST creates generation → client polls for completion (30-90 seconds)
    • On success, link to view in Gamma
    • Auth: X-API-KEY header with sk-gamma-... key

Flow 8: External API & AI Agent Access

ChatGPT Integration

  1. ChatGPT connects via OAuth 2.1 → gets API key
  2. Uses OpenAPI spec at /api/v1/openapi.json to discover tools
  3. Calls POST /api/v1/tools or POST /api/v1/tools/:name to execute tools
  4. Can search KB, read documents, create notes, list engagements

Claude MCP Integration

  1. Claude connects via MCP + OAuth → gets API key
  2. POST /api/mcp — stateless JSON-RPC 2.0 endpoint
  3. Same tool set as REST API
  4. Handles: initialize, tools/list, tools/call, ping

Zapier / Otter.ai Auto-Ingestion

  1. Otter.ai records and transcribes a meeting
  2. Zapier triggers on new Otter recording
  3. Optionally saves to Google Drive (backup)
  4. POST to /api/v1/ingest with title, summary, transcript, meeting_date, source, participants
  5. Creates up to 2 KB documents (Summary + Transcript) in Inbox folder
  6. Auto-tagged "Auto-Ingested" + "Summary"/"Transcript"
  7. Auto-embedded for AI search

Flow 9: API Key Management

  1. Navigate to admin API Keys page (/admin/api-keys)
  2. Create new key — shown once, copy immediately
  3. Key format: epok_sk_... (base64url random)
  4. Keys are SHA-256 hashed in database; only prefix stored for identification
  5. Keys can be deactivated or deleted
  6. OAuth-created keys are auto-named (e.g. "OAuth: client_abc123")

Flow 10: Email Notifications

Resend-powered email for:

  • Questionnaire request invitations
  • Document sharing notifications
  • Content update notifications
  • HTML templates in docs/ folder (zapier-email-template.html, content-update-email.html)

Future Flows (Not Yet Built)

  • Client Portal: Full client-facing portal with milestone tracker, questionnaire completion, and published content viewing
  • Context Switching: Super admin views system as client for QA
  • Scheduling: Calendar integration for workshop booking
  • Atlas Point Integration: Tool access provisioning after engagement completion
  • Cohort Dashboard: View all active engagements as a cohort with milestone progress
  • Built-in Video: LiveKit-powered interview sessions with live transcription