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
- 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 ([1], [2], etc.) |
| Snippet | Relevant excerpt from the document |
| Relevance Score | 0.0-1.0 indicating match quality |
| Metadata | Source type, client, project, date |
Example:
[1] (0.92) Meeting with Acme - we discussed the enterprise pricing tier...
Source: fathom | Client: Acme Corporation | Project: Enterprise Deal
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
Linear (Projects)
- Used for entity registry (client/project names)
- Teams in Linear map to clients
- Projects in Linear provide context
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 |
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-01