Documentation

.

├── Quick_Start_Guide

├── Configuration

├── Core_Concepts

├── Troubleshooting

└── Installation_n_Setup

Quick_Start_Guide

Welcome to Sentopic

Sentopic transforms Reddit discussions into actionable business intelligence. This guide will get you from installation to your first insights in about 30 minutes.

Your First 30 Minutes

Step 1: Verify Configuration (5 minutes)

Before collecting data, verify your API credentials are properly configured.

Verify Reddit API

  • Open Sentopic → Settings (gear icon)
  • Navigate to Configuration tab
  • Click "Test Reddit Connection" to verify
  • If the test fails, see Reddit API Setup section for detailed configuration steps

Verify AI Provider (Optional)

  • In Settings → Configuration → LLM Provider, verify your API key is entered
  • Click "Test Connection" to verify
  • If not configured, see AI Provider Setup section

Step 2: Create Your First Collection (10 minutes)

Collections gather Reddit posts and comments for analysis. Let's start with a focused example.

Recommended First Collection

Goal: Collect recent technology discussions to understand trends and sentiment

Parameters:

  • Subreddit: r/technology
  • Sort Method: Top
  • Time Period: Year
  • Posts: 100
  • Root Comments: 5 per post
  • Replies: 3 per root comment
  • Min Upvotes: 10

Why these parameters?

  • Small enough to complete quickly (~5 minutes)
  • Large enough to provide meaningful insights
  • Quality filter ensures substantive discussions

Creating the Collection

  • Click "Collection Manager" in the header
  • Click "New Collection"
  • Enter the parameters above
  • Click "Start Collection"
  • Monitor progress in real-time

What's happening: Sentopic is querying Reddit's API to gather posts and their comment threads. The API has rate limits, so larger collections take longer.

Step 3: Create Your First Project (10 minutes)

Projects analyze your collections to answer specific research questions.

Example Project: Technology Trends Analysis

Research Question: "What technology trends are people most excited or concerned about?"

Recommended Keywords:

  • AI
  • machine learning
  • privacy
  • security
  • cloud computing

Why these keywords?

  • Focused yet meaningful scope
  • Likely to appear in tech discussions
  • Capture different aspects (innovation, concerns, infrastructure)

Creating the Project

  • Return to Projects Dashboard
  • Click "New Project"
  • Enter your research question
  • Add your keywords (or use "AI Suggest Keywords" for ideas)
  • Select your r/technology collection
  • Configure options:
  • Partial Matching: Enable (captures variations like "AI-powered", "privacy-focused")
  • Context Window: 100 words (balanced view)
  • Generate Summary: Enable (requires AI provider)
  • Click "Create Project"

Analysis time: About 15 seconds for 100 posts with 5 keywords

Step 4: Explore Your Results (5 minutes)

Once analysis completes, explore your findings:

Understanding the Dashboard

Keyword Overview

  • Total mentions across all keywords
  • Distribution by keyword
  • Click to see detailed breakdown per keyword

Keyword Relationships

  • Shows which keywords appear together
  • Network visualization of connections
  • Identifies themes and associations
  • Click edges to explore discussions containing both keywords

Keyword Trends

  • How mention frequency changes over time
  • Rising (↗), stable (→), or falling (↘) indicators
  • Multiple keyword comparison

Recent Discussions

  • Sample posts and comments containing your keywords
  • Highlighted keywords in context
  • Sentiment scores for each mention
  • Click "Explore All Mentions" to filter and search

AI Summary

  • Business-focused analysis of findings
  • Key themes and patterns
  • Pain points and opportunities
  • Competitive insights

Using the AI Chat Assistant

Ask natural language questions about your data:

  • "What are the main concerns about AI in these discussions?"
  • "Which keywords have the most negative sentiment?"
  • "What themes appear with 'privacy' mentions?"
  • "Compare sentiment between 'AI' and 'machine learning'"

The assistant searches your data and provides evidence-based answers.

Configuration

Reddit API Setup

Sentopic requires Reddit API credentials to collect data. Follow these steps to create your credentials:

Step 1: Create a Reddit App

  • Visit https://www.reddit.com/prefs/apps and sign in with your Reddit account
  • Scroll to the bottom and click "create another app..." or "are you a developer? create an app..."
  • Fill out the form:
  • Name: Any name you choose (e.g., "Sentopic Research Tool")
  • App type: Select "script" (IMPORTANT: Must be "script", not "web app")
  • Description: Optional (e.g., "Reddit analytics for business research")
  • About URL: Leave blank
  • Redirect URI: Enter http://localhost (required, even though it won't be used)
  • Permissions: Leave default selections
  • Click "create app"

Step 2: Locate Your Credentials

After creating your app, you'll see it listed on the page:

  • Client ID: The string directly under your app's name (looks like random characters, e.g., abc123DEF456)
  • Client Secret: The longer string labeled "secret"
  • User Agent: You need to create this yourself in the format: AppName/1.0 by /u/YourRedditUsername

Example User Agent: SentopicResearch/1.0 by /u/john_researcher

Step 3: Enter Credentials in Sentopic

  • Launch Sentopic
  • Click the Settings icon (gear) in the top-right corner
  • Navigate to the Configuration tab
  • Under Reddit API Configuration, enter:
  • Client ID: Your client ID from Reddit
  • Client Secret: Your client secret from Reddit
  • User Agent: Your custom user agent string
  • Click "Test Reddit Connection" to verify your credentials work
  • If successful, you'll see a green success message

AI Provider Setup

AI features enhance Sentopic with keyword suggestions, analysis summaries, and the interactive chat assistant. Configuration is optional but recommended.

Note: You only need to configure one AI provider, not both. Choose based on your preference or existing accounts.

Anthropic (Claude) Setup

  • Visit https://console.anthropic.com/settings/keys
  • Create an account or sign in
  • Add billing information (pay-as-you-go)
  • Generate a new API key
  • In Sentopic Settings → Configuration → LLM Provider:
  • Select "Anthropic" as provider
  • Paste your API key
  • Click "Test Anthropic Connection"

OpenAI (GPT) Setup

  • Visit https://platform.openai.com/settings/organization/api-keys
  • Create an account or sign in
  • Add billing information (pay-as-you-go)
  • Generate a new API key
  • In Sentopic Settings → Configuration → LLM Provider:
  • Select "OpenAI" as provider
  • Paste your API key
  • Click "Test OpenAI Connection"

Core_Concepts

Collections vs Projects

Collections = Raw data from Reddit

  • Gather posts and comments from specific subreddits
  • Reusable across multiple projects
  • Think of them as your research library

Projects = Analysis and insights

  • Apply keywords to collections
  • Generate sentiment scores and relationships
  • Answer specific research questions
  • Can use multiple collections

Sentiment Scores

Sentopic analyzes the emotional tone of each keyword mention:

  • +0.3 to +1.0: Positive (praise, satisfaction, recommendations)
  • -0.3 to +0.3: Neutral (factual, mixed, balanced)
  • -0.3 to -1.0: Negative (criticism, complaints, concerns)

Business interpretation:

  • Highly positive (+0.7+): Strong advocacy, feature requests
  • Neutral: Factual discussions, comparisons
  • Highly negative (-0.7+): Major pain points, urgent issues

Keyword Strategy

Start Focused, Then Expand

Good first project: 3-5 specific keywords

  • Example: AI, machine learning, privacy

Avoid: 15+ broad keywords

  • Example: technology, computer, internet, software, hardware... (too generic)

Why? Focused keywords produce clearer insights. Use findings from one project to inform the next - this is an iterative research process.

Iterative Research Methodology

Effective analysis involves multiple projects that build on each other:

  • 1. Initial exploration: Broad keywords, discover patterns
  • 2. Analyze co-occurrences: Find unexpected keyword relationships
  • 3. Drill deeper: Create targeted follow-up projects
  • 4. Refine understanding: Iterate based on findings

Example progression:

  • Project 1: General tech sentiment (5 keywords)
  • Discovery: "AI" and "privacy" frequently co-occur with negative sentiment
  • Project 2: Focus on AI privacy concerns (targeted keywords)
  • Discovery: Specific concern around facial recognition
  • Project 3: Deep dive into facial recognition discussions

Troubleshooting

Common Issues

Reddit API Connection Fails

If the Reddit connection test fails:

  • Verify your app type is "script" (not "web app") on Reddit
  • Double-check Client ID and Client Secret for typos or extra spaces
  • Ensure your User Agent follows the format: AppName/Version by /u/username
  • Check that your Reddit account is in good standing

AI Features Not Working

  • Verify you've entered a valid API key in Settings
  • Check that your AI provider account has billing configured
  • Test the connection using the "Test Connection" button
  • Ensure you have available credits/usage quota

Cannot Connect to Backend

If Sentopic's frontend loads but shows connection errors:

  • Firewall issues: Add Sentopic to your firewall's allowed applications
  • Restart the application: Completely quit Sentopic and relaunch

Application Won't Start

  • Check system logs for error messages (Console.app on macOS, Event Viewer on Windows)
  • Verify you have sufficient disk space (1GB+)
  • Try reinstalling Sentopic
  • Restart your computer and try again

Performance Issues

If Sentopic runs slowly:

  • Close unnecessary applications to free up RAM
  • Start with smaller collections (500 posts) before scaling up
  • Reduce the number of keywords in your projects
  • Clear browser cache if using any web components

Platform-Specific Issues

macOS Issues

"Sentopic is damaged and can't be opened" - This security message sometimes appears on macOS. Run this Terminal command to fix it:

  • sudo xattr -rd com.apple.quarantine /Applications/Sentopic.app
  • Enter your Mac password when prompted, then try launching Sentopic again.

Gatekeeper Security Warnings - On first launch, macOS may block Sentopic because it's not code-signed. To open:

  • Right-click (or Control+click) on Sentopic.app in Applications
  • Select "Open" from the context menu
  • Click "Open" in the security dialog
  • After the first successful launch, you can open Sentopic normally

Windows Issues

Windows SmartScreen may block Sentopic as an unrecognized app. To proceed:

  • Click "More info" (small text link in the warning dialog)
  • Click "Run anyway" button that appears
  • This is standard for unsigned applications and is safe to proceed

Some antivirus programs may flag Sentopic as suspicious (false positive). If installation fails or features don't work:

  • Add Sentopic to your antivirus exclusion/whitelist
  • Location to whitelist: C:\Program Files\Sentopic
  • Consult your antivirus documentation for adding exclusions

Installation_n_Setup

System Requirements

Operating System:

  • macOS: 10.15 (Catalina) or later (Intel or Apple Silicon)

Hardware:

  • RAM: 4GB minimum, 8GB recommended
  • Disk Space: 1GB available
  • Internet Connection: Required for setup and data collection

macOS Installation

Step 1: Download the Installer

Download Sentopic-1.0.0-mac.dmg from your purchase confirmation email or customer download portal.

Step 2: Mount and Install

  • Locate the downloaded DMG file in your Downloads folder
  • Double-click Sentopic-1.0.0-mac.dmg to mount it
  • A Finder window will open showing the Sentopic application
  • Drag Sentopic.app to the Applications folder shortcut
  • Wait for the copy to complete
  • Eject the DMG by clicking the eject button next to "Sentopic" in Finder sidebar

Step 3: First Launch

macOS may show security warnings when launching Sentopic for the first time because the app is not currently code-signed by Apple.

Initial Launch Method:

  • Open your Applications folder
  • Right-click (or Control+click) on Sentopic.app
  • Select "Open" from the context menu
  • A security dialog will appear - click "Open" to proceed
  • The application will launch and initialize

For Future Launches: After the first successful launch, you can open Sentopic normally by double-clicking - macOS will remember your permission.

Uninstalling (macOS)

To remove Sentopic from your Mac:

  • Open your Applications folder
  • Drag Sentopic.app to the Trash
  • Empty Trash

To completely remove all user data (optional):

  • Remove application support: ~/Library/Application Support/Sentopic
  • Remove preferences: ~/Library/Preferences/com.sentopic.desktop.plist
  • Remove logs: ~/Library/Logs/Sentopic

Windows Installation

Step 1: Download the Installer

Download Sentopic-1.0.0.exe from your purchase confirmation email or customer download portal.

Step 2: Run the Installer

  • Locate the downloaded installer in your Downloads folder
  • Double-click Sentopic-1.0.0.exe to launch the installer

Step 3: Handle Windows Security Warning

Windows will show a security warning because the app is not currently code-signed by Microsoft.

When Windows SmartScreen displays "Windows protected your PC":

  • Click "More info" (small text link in the warning dialog)
  • A new button will appear: "Run anyway"
  • Click "Run anyway" to continue installation

This is a standard Windows security measure for unsigned applications. Your app is safe - Windows simply doesn't recognize the publisher yet.

Step 4: Complete Installation Wizard

  • The Sentopic installer will launch
  • Click "Next" to begin installation
  • Choose your installation location (default is recommended: C:\Program Files\Sentopic)
  • Review installation settings
  • Click "Install" to begin installation
  • Wait for installation to complete (typically 30-60 seconds)
  • Click "Finish" to close the installer

Shortcuts will be created on your Desktop and in the Start Menu.

Step 5: First Launch

  • Double-click the Sentopic desktop shortcut, or launch from Start Menu
  • If Windows Defender shows another SmartScreen warning, repeat the "More info" → "Run anyway" process
  • The application will launch and initialize (may take 10-15 seconds on first launch)

Uninstalling (Windows)

To remove Sentopic from your Windows PC:

  • Open Settings → Apps → Apps & features
  • Find Sentopic in the list
  • Click Uninstall
  • Follow the uninstaller wizard

To completely remove all user data (optional):

  • Navigate to: C:\Users\[YourUsername]\AppData\Roaming\Sentopic
  • Delete the entire Sentopic folder