Customer Journeys

This document describes the complete workflows for customers using Traces.

Journey 1: New Customer Onboarding

A new customer signs up and completes verification.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Signup    │ ──▶ │   Profile   │ ──▶ │ Verification│ ──▶ │   Ready     │
│             │     │   Setup     │     │   Pending   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps

1. Signup

   • Customer visits Traces portal
   • Clicks "Sign Up"
   • Authenticates via Clerk (email or SSO)
   • Account created with pending verification status

2. Profile Setup

   • Enter company name
   • Provide contact information (name, email, phone)
   • Accept terms of service
   • Submit for verification

3. Verification Pending

   • Analyst reviews customer information
   • Analyst verifies company legitimacy
   • Customer notified of outcome
   • Status changes to verified or rejected

4. Ready

   • Customer can now create credentials
   • Customer can request collections
   • Full platform access enabled

Key Events

• customer_created - Initial signup
• profile_submitted - Profile completed
• verification_completed - Analyst approved/rejected

---

Journey 2: Creating Credentials

A customer adds API credentials for a platform.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Select    │ ──▶ │   Enter     │ ──▶ │  Validate   │ ──▶ │   Ready     │
│   Platform  │     │   Creds     │     │   (Test)    │     │   To Use    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps

1. Select Platform

   • Navigate to Credentials
   • Click "Add Credentials"
   • Choose platform from available connectors
   • View authentication requirements

2. Enter Credentials

   • Select credential type (Bearer, API Key, OAuth2, etc.)
   • Enter credential values
   • Provide optional metadata (expiration date, notes)
   • Submit credentials

3. Validate (Test)

   • System tests credentials against platform
   • Makes test API call to verify access
   • Reports validation status:
     • valid - Ready to use
     • invalid - Incorrect credentials
     • expired - Token expired

4. Ready to Use

   • Credentials stored securely
   • Can be used for collections
   • Expiration monitored if provided

Key Events

• credential_created - Credential stored
• credential_validated - Test completed
• credential_access_logged - Every access recorded

---

Journey 3: Creating a Collection

A customer requests data collection from a platform.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Select    │ ──▶ │   Choose    │ ──▶ │ Configure   │ ──▶ │   Submit    │
│  Connector  │     │   Creds     │     │   Scope     │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps

1. Select Connector

   • Navigate to Collections → New
   • Browse available connectors
   • Review connector capabilities
   • Select desired platform

2. Choose Credentials

   • View available credentials for platform
   • Select valid, unexpired credential
   • Or add new credentials inline

3. Configure Scope

   • Set date range (from/to)
   • Apply filters (users, channels, etc.)
   • Provide business context (why collecting)
   • Set priority (normal, high, urgent)
   • Add case reference (optional)

4. Submit

   • Review collection summary
   • Confirm submission
   • Collection enters queue
   • Receive confirmation with estimated completion

Key Events

• collection_created - Request submitted
• credentials_validated - Creds verified before collection

---

Journey 4: Monitoring a Collection

A customer tracks collection progress in real-time.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Pending   │ ──▶ │    In       │ ──▶ │   Review    │ ──▶ │  Complete   │
│             │     │  Progress   │     │   Pending   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps

1. Pending

   • Collection created, awaiting start
   • Credentials being validated
   • Position in queue shown

2. In Progress

   • Real-time progress displayed:
     • Endpoints completed/total
     • Files collected
     • Data size
   • Live updates via SSE
   • Estimated completion time

3. Review Pending

   • Collection complete
   • Awaiting analyst review
   • Status: completed → reviewing

4. Complete

   • Analyst signed off
   • Ready for delivery
   • Download available

Real-time Updates

• Progress percentage
• Current endpoint
• File counts
• Error notifications

---

Journey 5: Downloading Results

A customer downloads their collected data.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Delivered  │ ──▶ │   Email     │ ──▶ │  Download   │ ──▶ │   Verify    │
│   Status    │     │   Notice    │     │    ZIP      │     │   Hash      │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Steps

1. Delivered Status

   • Collection status changes to delivered
   • Notification appears in dashboard

2. Email Notice

   • Customer receives email notification
   • Contains collection summary
   • Instructions for download

3. Download ZIP

   • Navigate to collection details
   • Click "Download"
   • Receive:
     • Secure download URL (time-limited)
     • ZIP password
     • File size
   • Download begins

4. Verify Hash

   • ZIP includes hash manifest
   • Customer can verify integrity
   • All file hashes listed
   • Chain of custody certificate included

Package Contents

collection-[id].zip
├── data/
│   ├── users.list.json
│   ├── channels.list.json
│   └── messages/
│       ├── channel_C123.json
│       └── channel_C456.json
├── metadata/
│   ├── manifest.json
│   ├── hashes.json
│   └── api_logs.json
└── certificate/
    └── chain_of_custody.pdf

---

Notification Flow

Event	Channel	Content
Collection created	In-app	Confirmation, estimated time
Collection started	Email	Status update
Collection completed	Email + in-app	Completion notice
Review complete	Email	Sign-off notification
Delivery ready	Email	Download instructions
Credential expiring	Email	Renewal reminder