User Guide
How to use the NorthBuilt RAG System effectively.
Table of Contents
- Getting Started
- How to Ask Questions
- Understanding Responses
- Conversation Features
- Data Sources
- Tips for Teams
- Troubleshooting
- Privacy and Security
- Keyboard Shortcuts
- System Dashboard
- Frequently Asked Questions
Getting Started
Accessing the System
- Navigate to the web application URL provided by your administrator
- Click “Sign in with Google”
- Complete the Google authentication flow
- You will be redirected to the chat interface
First Query
Once signed in, you can immediately start asking questions:
- Type your question in the input field
- Press Enter or click Send
- Wait 2-5 seconds for the response
- Review the answer and source citations
How to Ask Questions
Best Practices
Be Specific
Instead of: “What happened in meetings?”
Try: “What did we discuss with Acme Corporation about their pricing concerns?”
Include Context
- Mention client names when relevant
- Reference time periods if applicable
- Include project names for context (displayed in sources)
Ask One Thing at a Time
Complex multi-part questions may yield less focused answers. Break them into separate queries.
Example Queries
| Good Query | Why It Works |
|---|---|
| “What were the action items from the last Acme meeting?” | Specific client and clear request |
| “What support issues has Globex reported about the API?” | Client + topic + context |
| “Summarize our discussions with Acme about enterprise pricing” | Client + topic + action |
| Query to Improve | Better Version |
|---|---|
| “meetings” | “What was discussed in recent client meetings?” |
| “what about acme” | “What are the key points from our Acme discussions?” |
| “help” | “What support tickets mention authentication issues?” |
Client Filtering
The system automatically detects client names in your questions and filters results accordingly. This means:
- “What did Acme say about pricing?” retrieves only Acme-related documents
- All projects under Acme are included for complete context
- You don’t need to select a client from a dropdown
If the system cannot determine which client you mean (e.g., multiple clients with similar names), it will ask for clarification.
Understanding Responses
Response Structure
Each response includes:
- Answer: The generated response based on your documents
- Sources: The documents used to generate the answer
- Relevance Scores: How well each source matched your query
Source Citations
Sources are displayed with:
| Field | Description |
|---|---|
| Document Number | Reference number (Source 1, Source 2, etc.) |
| Relevance Score | Percentage indicating match quality (95%, 75%, etc.) |
| Snippet | Relevant excerpt from the document, rendered with Markdown formatting |
| Metadata | Source type, client, project displayed as badges |
| View Document | Link to the original source document (opens in new tab) |
Click on a source card to expand it and view the full snippet, metadata badges, and document link.
Source Document Links
Each source includes a “View Document” link that opens the original document in a new browser tab. These links:
- Provide secure, time-limited access (1-hour expiry)
- Allow you to view the full document context
- Open in a new tab to preserve your conversation
Markdown Formatting
Source snippets are rendered with proper Markdown formatting, including:
- Headers and subheaders
- Bold and italic text
- Bulleted and numbered lists
- Code blocks
This makes it easier to read structured content from meeting notes, documentation, and other formatted sources.
When No Results Are Found
If the system cannot find relevant documents, it will:
- Indicate that no matching documents were found
- Suggest rephrasing your question
- Ask if you meant a different client
This is better than providing an incorrect or hallucinated answer.
Conversation Features
Follow-Up Questions
You can ask follow-up questions that reference previous context:
First query: “What did we discuss with Acme about pricing?”
Follow-up: “What were their concerns about the enterprise tier?”
The system maintains context within a session, so “their” refers to Acme.
Starting Fresh
To start a new, unrelated conversation:
- Refresh the page, OR
- Clear your query and mention a different client
Sessions maintain context for approximately 24 hours.
Data Sources
The system includes documents from multiple sources:
Fathom (Meeting Transcripts)
- Video meeting transcripts
- Automatically captured and indexed
- Includes speaker identification
- Searchable by client and meeting content
HelpScout (Support Conversations)
- Customer support tickets
- Email conversations
- Includes full thread history
- Searchable by client and issue content
Tips for Teams
Engineering Teams
- Search for technical discussions: “What architecture decisions were made for the API?”
- Find implementation details: “How did we implement authentication for Acme?”
- Reference past decisions: “What was the rationale for using S3 instead of DynamoDB?”
Sales Teams
- Research client history: “What has Acme expressed interest in?”
- Prepare for meetings: “Summarize our relationship with Globex”
- Find pricing discussions: “What pricing options did we discuss with Acme?”
Support Teams
- Find similar issues: “Have other clients reported API timeout issues?”
- Research client context: “What customizations does Acme have?”
- Check past resolutions: “How did we resolve the authentication issue for Globex?”
Marketing Teams
- Gather testimonials: “What positive feedback have clients given?”
- Research use cases: “How is Acme using our product?”
- Identify trends: “What features do clients request most?”
Troubleshooting
Common Issues
“No relevant documents found”
- Try rephrasing your question
- Check if you spelled the client name correctly
- Use alternative client names or aliases
“Which client did you mean?”
- The system found multiple matching clients
- Select the correct one from the options provided
- Be more specific in future queries
Slow response times
- Normal response time is 2-5 seconds
- First query after inactivity may be slower (cold start)
- Very complex queries may take longer
Session expired (401 error)
- Refresh the page to get a new authentication token
- Sign in again if prompted
Rate limit exceeded (429 error)
- Wait a moment and try again
- Reduce query frequency if making many requests
Getting Help
If you encounter issues not covered here:
- Check with your administrator
- Review system status for any outages
- Provide the error message when reporting issues
Privacy and Security
What Data Is Accessible
- Only documents associated with known clients
- Documents are filtered by client based on your query
- All projects under a client are accessible for complete context
Authentication
- Access requires Google authentication
- Sessions expire after inactivity
- Each user has their own session
Data Handling
- Queries are processed in AWS (us-east-1)
- Responses are not stored beyond the session
- Source documents remain in their original location
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Enter | Submit query |
| Shift+Enter | New line in query |
| Ctrl/Cmd+K | Focus query input |
| Escape | Clear current input |
System Dashboard
The System Dashboard provides visibility into system health and performance metrics. Access it via the sidebar navigation.
Dashboard Features
Metrics Overview
View key performance indicators including:
- Total queries processed
- Average response latency
- Error rate percentage
- Documents retrieved per query
Ingestion Metrics
Monitor document ingestion from all sources:
- Documents ingested (webhooks vs scheduled sync)
- Webhook processing success rate
- Sync job completion status
- Classification accuracy
Time Series Charts
Visualize trends over time:
- Query Volume: Requests per hour/day
- Latency Trends: Response time patterns
- Document Ingestion: Ingestion rate over time
Time Range Selection
Toggle between:
- Last 24 hours (hourly granularity)
- Last 7 days (6-hour granularity)
- Last 30 days (daily granularity)
Log Viewer
View recent logs from system components:
- Select a log group from the dropdown
- View timestamped log entries with level badges (INFO, WARN, ERROR)
- Load more logs with pagination
When to Use the Dashboard
- Morning checks: Verify system health at the start of the day
- After deployments: Confirm normal operation after updates
- Investigating issues: Check error rates and recent logs
- Performance monitoring: Track latency trends over time
Frequently Asked Questions
Q: How current is the data?
A: Documents are updated within 5-10 minutes of being added or modified in source systems (Fathom, HelpScout).
Q: Can I search across all clients?
A: If you don’t mention a specific client, the system may search broadly or ask for clarification. For best results, specify the client.
Q: Why don’t I see certain documents?
A: Documents must be properly tagged with client metadata. If a document appears to be missing, check with your administrator.
Q: Can I upload my own documents?
A: Currently, documents are ingested from integrated sources (Fathom, HelpScout). Direct upload is not supported via the web UI.
Q: How accurate are the responses?
A: Responses are generated based on retrieved documents. Relevance scores indicate confidence. Always verify critical information against source documents.
Q: Can I export my conversation?
A: Conversation export is not currently supported. You can copy/paste responses manually.
Last updated: 2026-01-11