Sniff — System Requirements Document

1. Introduction

This document outlines the system requirements for "Sniff," a web application designed as a community and topic intelligence platform for analyzing Reddit's public data. The application will provide insights into subreddits, topics, threads, and user behavior using various analytical features.

2. System Overview

"Sniff" is a web-based application that leverages Reddit's public data to perform topic and community analysis. It is built using Next.js, TypeScript, and TailwindCSS, with SQLite as the database. The application will utilize the OpenAI API for advanced text analysis and Reddit's official API for data ingestion.

3. Functional Requirements

Core Features

• As a user, I want to search for topics/issues using keywords, subreddit filters, and date ranges, so that I can find relevant public threads and comments.
• As a user, I want to analyze threads to understand post framing, comment sentiment, discussion angles, and viewpoints, so that I can gain insights into the conversation dynamics.
• As a user, I want to synthesize sentiment across multiple threads on the same topic to detect consensus and disagreement, so that I can track narrative evolution.
• As a user, I want to analyze subreddit intelligence to understand post volume trends, engagement distribution, and discourse style, so that I can assess community behavior.
• As a user, I want to compare topics across subreddits to identify shared and unique discussions, so that I can understand narrative diffusion.
• As a user, I want to track emerging topics and trends with visualizations like trend graphs and timelines, so that I can monitor attention shifts.
• As a user, I want to perform semantic searches using keywords and embeddings, so that I can find relevant posts with expanded query terms.
• As a user, I want to use an AI research assistant to answer questions about dominant narratives, with citations for each claim, so that I can trust the information provided.
• As a user, I want every AI-generated claim to include evidence and provenance details, so that I can verify the source and reliability of the information.
• As a user, I want to create watchlists for keywords, topics, or subreddits to receive alerts on significant changes, so that I can stay informed about important developments.
• As a user, I want alerts to trigger on sentiment shifts, sudden volume spikes, and topics spreading to new subreddits, so that I can respond to important changes.
• As a user, I want to generate reports with executive summaries, topic framing, sentiment breakdowns, and key discussion angles, so that I can share insights with others.
• As a user, I want to export reports as Markdown, HTML, or PDF, so that I can distribute them in various formats.
• As a user, I want data reliability scoring to assess thread and subreddit credibility, so that I can evaluate the trustworthiness of the information.
• As a user, I want an investigation workspace to save cases with topics, threads, notes, and reports, so that I can organize my research.
• As a user, I want to visualize data using Recharts for charts, so that I can easily interpret complex information.
• As a user, I want to identify first-time-appearance topics and sudden keyword spikes, so that I can detect emerging trends early.
• As a user, I want to build profiles of individual users with observed data and AI-generated analysis, so that I can understand user behavior.
• As a user, I want privacy controls to delete locally stored investigation data and maintain audit logs, so that I can manage data responsibly.

Hard Guardrails

• As a developer, I want to ensure no API route, DB table, or UI page accepts a username as a primary lookup key, so that user privacy is protected.
• As a developer, I want to rate-limit and cache Reddit API calls, so that the application complies with Reddit's API terms of service.
• As a developer, I want every exported report to include a data-limitations and "public data only" disclosure footer, so that users are aware of the data scope.

4. User Personas

• Research Analyst: Uses the platform to analyze community discussions and generate reports.
• Community Manager: Monitors subreddit trends and user behavior to manage community engagement.
• Data Scientist: Utilizes the platform's analytical features to conduct in-depth research on topics and narratives.

5. Core User Flows

Topic Search and Analysis

1. User inputs keywords and optional filters.
2. System fetches and displays matching threads and comments.
3. User selects a thread for detailed analysis.
4. System provides sentiment breakdown and discussion angles.

Report Generation

1. User selects topics and analysis parameters.
2. System compiles data into a report format.
3. User reviews and exports the report.

User Profile Analysis

1. User selects a Reddit user for profile analysis.
2. System aggregates observed data and AI-generated insights.
3. User reviews the profile with privacy controls in place.

6. Visuals Colors and Theme

• Primary: #1A73E8 (Deep Blue)
• Primary Light: #E8F0FE (Light Blue)
• Secondary: #34A853 (Green)
• Accent: #FBBC05 (Yellow)
• Highlight: #EA4335 (Red)
• Background: #FFFFFF (White)
• Surface: rgba(250, 250, 250, 0.8)
• Text: #202124 (Dark Gray)
• Text Muted: #5F6368 (Light Gray)
• Border: rgba(218, 220, 224, 0.2)

7. Signature Design Concept

The homepage of "Sniff" will feature an interactive galaxy map where each star represents a subreddit or topic. Users can click on stars to zoom into detailed analysis, drag to rotate the galaxy, and hover to highlight connections between topics. This dynamic visualization will be powered by @react-three/fiber and @react-three/drei, creating an engaging and exploratory experience that reflects the vastness and interconnectedness of Reddit discussions.

8. Interaction Model & Motion Direction

• Interaction Model: Parallax
• The landing page will feature layered depth via scroll, with decorative elements translating at different speeds to create a sense of depth. Real content will scroll naturally, providing a visually rich first impression.
• Internal pages will maintain a static interaction model for clarity and ease of reading.

9. Non-Functional Requirements

• The system must handle concurrent users efficiently.
• The application should load pages within 2 seconds under normal conditions.

10. Tech Stack

• Frontend: Next.js 15, TypeScript, TailwindCSS
• Backend: Next.js API routes
• Database: SQLite (via better-sqlite3 or Prisma)
• APIs: OpenAI API, Reddit's official API

11. Assumptions and Constraints

• The application will operate within the limitations of free-tier infrastructure.
• All data processing will comply with Reddit's API terms of service.

12. Glossary

• Subreddit: A community within Reddit focused on a specific topic.
• Thread: A series of messages or comments on a particular topic within a subreddit.
• Sentiment Analysis: The process of determining the emotional tone behind a series of words.
• Semantic Search: A search technique that considers the meaning of words and phrases rather than just matching keywords.