subculture-collective/discord-spywatcher
1
0
Fork 0
Code Issues 2 Pull Requests 23 Actions Packages Projects Releases Wiki Activity

[WIP] Comprehensive Documentation - User, Admin, and Developer Guides (#152)

Browse Source 
* Initial plan

* feat(docs): implement comprehensive VitePress documentation site

- Set up VitePress documentation platform with search and dark mode
- Created user guide with installation, quick start, and feature guides
- Added ghost detection comprehensive guide with examples
- Created admin guide with environment configuration
- Implemented developer guide with contributing guidelines
- Added API reference with code examples in multiple languages
- Configured navigation structure for all doc sections
- Added changelog and documentation README

Co-authored-by: onnwee <211922112+onnwee@users.noreply.github.com>

* feat(docs): add remaining guide pages and deployment workflow

- Created timeline analysis guide
- Added plugin system guide
- Implemented privacy controls guide
- Created advanced charts guide
- Added API authentication documentation
- Created GitHub Actions workflow for docs deployment
- Added logo SVG for documentation site
- Updated main README with documentation section

Co-authored-by: onnwee <211922112+onnwee@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: onnwee <211922112+onnwee@users.noreply.github.com>
This commit was merged in pull request #152.
This commit is contained in:
Copilot
2025-11-03 12:26:58 -06:00
committed by GitHub
parent 410d2d476d
commit 891ca30a9d
35 changed files with 11332 additions and 2956 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
.github/workflows/deploy-docs.yml vendored Normal file
View File

@@ -0,0 +1,59 @@
name: Deploy Documentation
on:
push:
branches:
- main
paths:
- 'docs/**'
- '.github/workflows/deploy-docs.yml'
workflow_dispatch:
# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Install dependencies
run: npm ci
- name: Build documentation
run: npm run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
deploy:
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

5
.gitignore vendored
View File

@@ -31,13 +31,16 @@ frontend/node_modules/
# Cache
.cache/
.parcel-cache/
.vitepress/
.vitepress/dist/
.vitepress/cache/
.nyc_output/
coverage/
*.lcov
# VitePress build output
docs/.vitepress/dist/
docs/.vitepress/cache/
# VSCode
.vscode-test
.tern-port

31
README.md
View File

@@ -32,10 +32,39 @@ Spywatcher is a full-stack surveillance and analytics tool for Discord servers.
backend/ # Discord bot + API server
frontend/ # React + Vite frontend client
sdk/ # TypeScript/JavaScript SDK for API integration
docs/ # Comprehensive documentation
docs/ # VitePress documentation site
.github/ # CI/CD workflows and automation
```
## 📚 Documentation
Comprehensive documentation is available at multiple levels:
- **[User Guide](./docs/guide/)** - Installation, features, and usage
- **[Admin Guide](./docs/admin/)** - Configuration and operations
- **[Developer Guide](./docs/developer/)** - Architecture and contributing
- **[API Reference](./docs/api/)** - Complete API documentation
### Building Documentation Locally
```bash
# Start development server
npm run docs:dev
# Build static site
npm run docs:build
# Preview build
npm run docs:preview
```
Documentation is built with [VitePress](https://vitepress.dev/) and includes:
- Interactive search
- Dark mode support
- Mobile-responsive design
- Code examples in multiple languages
- Comprehensive guides for all features
## 🔄 CI/CD Pipeline
This project uses GitHub Actions for continuous integration and deployment:

258
docs/.vitepress/config.mts Normal file
View File

@@ -0,0 +1,258 @@
import { defineConfig } from 'vitepress';
export default defineConfig({
title: 'Spywatcher',
description:
'Comprehensive documentation for Discord Spywatcher - surveillance and analytics for Discord servers',
lang: 'en-US',
lastUpdated: true,
cleanUrls: true,
ignoreDeadLinks: true,
head: [
['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
['meta', { name: 'theme-color', content: '#5865f2' }],
['meta', { property: 'og:type', content: 'website' }],
['meta', { property: 'og:locale', content: 'en' }],
['meta', { property: 'og:title', content: 'Spywatcher Documentation' }],
[
'meta',
{
property: 'og:description',
content: 'Discord surveillance and analytics documentation',
},
],
['meta', { property: 'og:site_name', content: 'Spywatcher Docs' }],
],
themeConfig: {
logo: '/logo.svg',
nav: [
{ text: 'Guide', link: '/guide/', activeMatch: '/guide/' },
{ text: 'Admin', link: '/admin/', activeMatch: '/admin/' },
{ text: 'Developer', link: '/developer/', activeMatch: '/developer/' },
{ text: 'API', link: '/api/', activeMatch: '/api/' },
{
text: 'Resources',
items: [
{ text: 'GitHub', link: 'https://github.com/subculture-collective/discord-spywatcher' },
{ text: 'Changelog', link: '/changelog' },
{ text: 'Contributing', link: '/developer/contributing' },
],
},
],
sidebar: {
'/guide/': [
{
text: 'Getting Started',
collapsed: false,
items: [
{ text: 'Introduction', link: '/guide/' },
{ text: 'Installation', link: '/guide/installation' },
{ text: 'Quick Start', link: '/guide/quick-start' },
{ text: 'Discord OAuth Setup', link: '/guide/oauth-setup' },
{ text: 'Guild Selection', link: '/guide/guild-selection' },
],
},
{
text: 'Core Features',
collapsed: false,
items: [
{ text: 'Dashboard Overview', link: '/guide/dashboard' },
{ text: 'Analytics', link: '/guide/analytics' },
{ text: 'Ghost Detection', link: '/guide/ghost-detection' },
{ text: 'Lurker Detection', link: '/guide/lurker-detection' },
{ text: 'Heatmap Visualization', link: '/guide/heatmap' },
{ text: 'Suspicion Scores', link: '/guide/suspicion-scores' },
{ text: 'Filters and Search', link: '/guide/filters' },
],
},
{
text: 'Advanced Features',
collapsed: false,
items: [
{ text: 'Timeline Analysis', link: '/guide/timeline' },
{ text: 'Advanced Charts', link: '/guide/advanced-charts' },
{ text: 'Privacy Controls', link: '/guide/privacy' },
{ text: 'Plugin System', link: '/guide/plugins' },
],
},
{
text: 'Help',
collapsed: false,
items: [
{ text: 'Troubleshooting', link: '/guide/troubleshooting' },
{ text: 'FAQ', link: '/guide/faq' },
],
},
],
'/admin/': [
{
text: 'Administration',
collapsed: false,
items: [
{ text: 'Overview', link: '/admin/' },
{ text: 'Admin Panel', link: '/admin/panel' },
{ text: 'User Management', link: '/admin/user-management' },
{ text: 'Ban Management', link: '/admin/ban-management' },
{ text: 'IP Blocking', link: '/admin/ip-blocking' },
{ text: 'Permission Management', link: '/admin/permissions' },
{ text: 'Audit Logs', link: '/admin/audit-logs' },
],
},
{
text: 'Configuration',
collapsed: false,
items: [
{ text: 'Environment Variables', link: '/admin/environment' },
{ text: 'Feature Flags', link: '/admin/feature-flags' },
{ text: 'Rate Limiting', link: '/admin/rate-limiting' },
{ text: 'Security Settings', link: '/admin/security' },
{ text: 'Integration Settings', link: '/admin/integrations' },
],
},
{
text: 'Operations',
collapsed: false,
items: [
{ text: 'Backup Procedures', link: '/admin/backup' },
{ text: 'Restore Procedures', link: '/admin/restore' },
{ text: 'Monitoring', link: '/admin/monitoring' },
{ text: 'Alert Handling', link: '/admin/alerts' },
{ text: 'Incident Response', link: '/admin/incident-response' },
{ text: 'Maintenance', link: '/admin/maintenance' },
],
},
],
'/developer/': [
{
text: 'Getting Started',
collapsed: false,
items: [
{ text: 'Development Setup', link: '/developer/' },
{ text: 'Prerequisites', link: '/developer/prerequisites' },
{ text: 'Local Environment', link: '/developer/local-environment' },
{ text: 'Database Setup', link: '/developer/database-setup' },
{ text: 'Running Tests', link: '/developer/testing' },
{ text: 'Debug Configuration', link: '/developer/debugging' },
{ text: 'Common Issues', link: '/developer/common-issues' },
],
},
{
text: 'Architecture',
collapsed: false,
items: [
{ text: 'System Architecture', link: '/developer/architecture' },
{ text: 'Database Schema', link: '/developer/database-schema' },
{ text: 'API Architecture', link: '/developer/api-architecture' },
{ text: 'Authentication Flow', link: '/developer/auth-flow' },
{ text: 'WebSocket Architecture', link: '/developer/websocket' },
{ text: 'Data Flow', link: '/developer/data-flow' },
],
},
{
text: 'Contributing',
collapsed: false,
items: [
{ text: 'How to Contribute', link: '/developer/contributing' },
{ text: 'Code of Conduct', link: '/developer/code-of-conduct' },
{ text: 'Code Style Guide', link: '/developer/code-style' },
{ text: 'Pull Request Process', link: '/developer/pull-requests' },
{ text: 'Testing Requirements', link: '/developer/test-requirements' },
{ text: 'Commit Conventions', link: '/developer/commit-conventions' },
{ text: 'Review Process', link: '/developer/review-process' },
],
},
{
text: 'Deployment',
collapsed: false,
items: [
{ text: 'Deployment Guide', link: '/developer/deployment' },
{ text: 'Infrastructure Setup', link: '/developer/infrastructure' },
{ text: 'Docker Guide', link: '/developer/docker' },
{ text: 'Kubernetes Guide', link: '/developer/kubernetes' },
{ text: 'Migration Procedures', link: '/developer/migrations' },
{ text: 'Monitoring Setup', link: '/developer/monitoring-setup' },
{ text: 'Scaling Guide', link: '/developer/scaling' },
],
},
],
'/api/': [
{
text: 'API Reference',
collapsed: false,
items: [
{ text: 'Introduction', link: '/api/' },
{ text: 'Authentication', link: '/api/authentication' },
{ text: 'Rate Limiting', link: '/api/rate-limiting' },
{ text: 'Error Handling', link: '/api/errors' },
{ text: 'Pagination', link: '/api/pagination' },
],
},
{
text: 'REST API',
collapsed: false,
items: [
{ text: 'Analytics', link: '/api/analytics' },
{ text: 'Users', link: '/api/users' },
{ text: 'Ghosts', link: '/api/ghosts' },
{ text: 'Lurkers', link: '/api/lurkers' },
{ text: 'Suspicion Scores', link: '/api/suspicion' },
{ text: 'Timeline', link: '/api/timeline' },
{ text: 'Bans', link: '/api/bans' },
{ text: 'Privacy', link: '/api/privacy' },
],
},
{
text: 'WebSocket API',
collapsed: false,
items: [
{ text: 'WebSocket Events', link: '/api/websocket' },
{ text: 'Real-time Updates', link: '/api/realtime' },
],
},
{
text: 'SDK',
collapsed: false,
items: [
{ text: 'TypeScript/JavaScript', link: '/api/sdk-typescript' },
{ text: 'Python', link: '/api/sdk-python' },
],
},
],
},
socialLinks: [
{
icon: 'github',
link: 'https://github.com/subculture-collective/discord-spywatcher',
},
],
search: {
provider: 'local',
},
editLink: {
pattern:
'https://github.com/subculture-collective/discord-spywatcher/edit/main/docs/:path',
text: 'Edit this page on GitHub',
},
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2024-present Spywatcher Team',
},
},
markdown: {
theme: {
light: 'github-light',
dark: 'github-dark',
},
lineNumbers: true,
},
});

227
docs/README.md Normal file
View File

@@ -0,0 +1,227 @@
# Spywatcher Documentation
This directory contains the comprehensive documentation for Spywatcher, built with [VitePress](https://vitepress.dev/).
## Documentation Structure
```
docs/
├── .vitepress/ # VitePress configuration
│ └── config.ts # Site configuration
├── guide/ # User guides
│ ├── index.md # Guide home
│ ├── installation.md # Installation guide
│ ├── quick-start.md # Quick start guide
│ └── ... # Feature guides
├── admin/ # Administrator guides
│ ├── index.md # Admin home
│ └── ... # Admin documentation
├── developer/ # Developer guides
│ ├── index.md # Developer home
│ └── ... # Development docs
├── api/ # API reference
│ ├── index.md # API home
│ └── ... # API endpoints
├── index.md # Documentation homepage
└── changelog.md # Version history
```
## Local Development
### Prerequisites
- Node.js 18+
- npm 8+
### Setup
```bash
# Install dependencies (from repository root)
npm install
# Start development server
npm run docs:dev
```
The documentation will be available at `http://localhost:5173/`.
### Build
```bash
# Build documentation
npm run docs:build
# Preview build
npm run docs:preview
```
## Writing Documentation
### Creating New Pages
1. Create a new `.md` file in the appropriate directory
2. Add front matter if needed
3. Update `.vitepress/config.ts` to add it to navigation
4. Use markdown with VitePress enhancements
### Markdown Features
VitePress supports:
- Standard markdown
- Custom containers (tip, warning, danger)
- Code syntax highlighting
- Mermaid diagrams
- Vue components
### Example Page
```markdown
# Page Title
Brief introduction to the topic.
## Section
Content with **bold** and *italic* text.
### Code Example
\`\`\`typescript
// TypeScript code example
const example = "highlighted code";
\`\`\`
::: tip
Helpful tip for users
:::
::: warning
Important warning
:::
## Related
- [Related Page 1](./page1)
- [Related Page 2](./page2)
```
### Custom Containers
```markdown
::: tip
Helpful information
:::
::: warning
Important warnings
:::
::: danger
Critical information
:::
::: info
Informational content
:::
```
### Code Groups
```markdown
::: code-group
\`\`\`typescript [TypeScript]
const example = "TypeScript";
\`\`\`
\`\`\`python [Python]
example = "Python"
\`\`\`
:::
```
## Deploying Documentation
### GitHub Pages
Documentation can be deployed to GitHub Pages:
```bash
# Build documentation
npm run docs:build
# Deploy to GitHub Pages
# (Configure in .github/workflows/deploy-docs.yml)
```
### Other Platforms
The built documentation (in `docs/.vitepress/dist`) can be deployed to:
- Netlify
- Vercel
- AWS S3
- Any static hosting service
## Contributing
When contributing documentation:
1. Follow the existing structure
2. Use clear, concise language
3. Include code examples
4. Add screenshots for UI features
5. Link to related documentation
6. Test locally before submitting
See [Contributing Guide](./developer/contributing.md) for more details.
## Style Guide
### Writing Style
- Use active voice
- Write in second person ("you")
- Keep sentences short
- Use bullet points for lists
- Include examples
### Formatting
- Use proper markdown headings (h1, h2, h3)
- Code snippets should be properly highlighted
- Use tables for structured data
- Add alt text to images
- Use consistent terminology
### Code Examples
- Include complete, working examples
- Add comments to explain complex code
- Show both TypeScript and JavaScript when applicable
- Include error handling
- Use realistic variable names
## Search
VitePress includes built-in search functionality. All content is automatically indexed.
## Version Control
Documentation is version-controlled alongside code:
- Update docs in the same PR as code changes
- Keep docs in sync with features
- Update changelog for documentation changes
## Links
- [VitePress Documentation](https://vitepress.dev/)
- [Markdown Guide](https://www.markdownguide.org/)
- [Spywatcher Repository](https://github.com/subculture-collective/discord-spywatcher)
## Questions?
If you have questions about documentation:
- Open an issue on GitHub
- Check the [Contributing Guide](./developer/contributing.md)
- Review the [Developer Guide](./developer/)

303
docs/admin/environment.md Normal file
View File

@@ -0,0 +1,303 @@
# Environment Variables
Complete reference for configuring Spywatcher through environment variables.
## Core Configuration
### Application
```bash
# Node environment
NODE_ENV=production|development|test
# Application URLs
FRONTEND_URL=https://app.spywatcher.com
BACKEND_URL=https://api.spywatcher.com
# Server ports
PORT=3001
FRONTEND_PORT=5173
```
### Discord
```bash
# Bot configuration
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_CLIENT_ID=your_client_id
DISCORD_CLIENT_SECRET=your_client_secret
DISCORD_REDIRECT_URI=https://app.spywatcher.com/auth/callback
# Guild settings
DISCORD_GUILD_ID=your_guild_id # Optional: primary guild
```
### Database
```bash
# PostgreSQL connection
DATABASE_URL=postgresql://user:password@localhost:5432/spywatcher
# Connection pool settings
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10
DATABASE_TIMEOUT=30000
```
### Redis
```bash
# Redis connection
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your_redis_password # Optional
# Redis configuration
REDIS_DB=0
REDIS_KEY_PREFIX=spywatcher:
```
## Security
### Authentication
```bash
# JWT configuration
JWT_SECRET=your_secure_random_secret_here
JWT_EXPIRES_IN=7d
# Session configuration
SESSION_SECRET=another_secure_secret
SESSION_MAX_AGE=604800000 # 7 days in milliseconds
```
### Encryption
```bash
# Data encryption
ENCRYPTION_KEY=your_encryption_key_here
ENCRYPTION_ALGORITHM=aes-256-gcm
```
## Features
### Feature Flags
```bash
# Enable/disable features
FEATURE_GHOST_DETECTION=true
FEATURE_LURKER_DETECTION=true
FEATURE_SUSPICION_SCORING=true
FEATURE_PLUGINS=true
FEATURE_PUBLIC_API=true
FEATURE_WEBHOOKS=false
```
### Rate Limiting
```bash
# API rate limits (requests per minute)
RATE_LIMIT_FREE=10
RATE_LIMIT_PRO=100
RATE_LIMIT_ENTERPRISE=1000
# Daily quotas
QUOTA_FREE=1000
QUOTA_PRO=100000
QUOTA_ENTERPRISE=unlimited
```
## Monitoring
### Logging
```bash
# Log level
LOG_LEVEL=info|debug|warn|error
# Log format
LOG_FORMAT=json|pretty
# Log destination
LOG_FILE=/var/log/spywatcher/app.log
```
### Sentry
```bash
# Sentry error tracking
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project
SENTRY_ENVIRONMENT=production
SENTRY_TRACE_SAMPLE_RATE=0.1
```
### Prometheus
```bash
# Prometheus metrics
PROMETHEUS_ENABLED=true
PROMETHEUS_PORT=9090
PROMETHEUS_PATH=/metrics
```
## Operations
### Backups
```bash
# Backup configuration
BACKUP_ENABLED=true
BACKUP_SCHEDULE="0 2 * * *" # Daily at 2 AM
BACKUP_RETENTION_DAYS=30
BACKUP_LOCATION=/backups
```
### Maintenance
```bash
# Maintenance mode
MAINTENANCE_MODE=false
MAINTENANCE_MESSAGE="System maintenance in progress"
```
## Third-party Services
### Email (Optional)
```bash
# SMTP configuration
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@spywatcher.com
SMTP_PASSWORD=your_smtp_password
SMTP_FROM=Spywatcher <noreply@spywatcher.com>
```
### Storage (Optional)
```bash
# S3-compatible storage
S3_ENABLED=false
S3_BUCKET=spywatcher-backups
S3_REGION=us-east-1
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
```
## Development
### Development-specific
```bash
# Development tools
DEBUG=*
HOT_RELOAD=true
SOURCE_MAPS=true
# Database
DATABASE_LOGGING=true
PRISMA_STUDIO_PORT=5555
```
### Testing
```bash
# Test environment
TEST_DATABASE_URL=postgresql://test:test@localhost:5432/spywatcher_test
TEST_REDIS_URL=redis://localhost:6380
```
## Environment Files
### Location
Environment files should be placed in:
- Root: `.env`
- Backend: `backend/.env`
- Frontend: `frontend/.env`
### Example Structure
```bash
# Root .env (shared)
NODE_ENV=production
DISCORD_BOT_TOKEN=token_here
# Backend .env (backend-specific)
DATABASE_URL=postgresql://...
PORT=3001
# Frontend .env (frontend-specific)
VITE_API_URL=http://localhost:3001
VITE_WS_URL=ws://localhost:3001
```
## Security Best Practices
### Secrets Management
1. **Never commit secrets** to version control
2. **Use strong random values** for secrets:
```bash
openssl rand -base64 32
```
3. **Rotate secrets regularly**
4. **Use environment-specific files**
5. **Consider secret management tools** (Vault, AWS Secrets Manager)
### Access Control
1. Limit access to environment files
2. Use proper file permissions (600)
3. Encrypt sensitive values
4. Use different secrets per environment
## Validation
### Check Configuration
```bash
# Validate environment
npm run config:validate
# Show configuration (secrets hidden)
npm run config:show
```
### Required Variables
Minimum required for basic operation:
- `DISCORD_BOT_TOKEN`
- `DISCORD_CLIENT_ID`
- `DISCORD_CLIENT_SECRET`
- `DATABASE_URL`
- `JWT_SECRET`
## Troubleshooting
### Missing Variables
Error: "Missing required environment variable"
**Solution:** Ensure all required variables are set in `.env`
### Invalid Values
Error: "Invalid configuration value"
**Solution:** Check variable formats match expected patterns
### Conflicts
Error: "Configuration conflict detected"
**Solution:** Ensure development and production configs don't conflict
## Related
- [Feature Flags](./feature-flags)
- [Security Settings](./security)
- [Deployment Guide](/developer/deployment)
::: warning Security
Never commit `.env` files to version control! Always use `.env.example` as a template.
:::

282
docs/admin/index.md Normal file
View File

@@ -0,0 +1,282 @@
# Admin Guide
Welcome to the Spywatcher Administration Guide. This guide covers server administration, configuration, and operations for Spywatcher.
## Overview
As an administrator, you're responsible for:
- 🔧 **Configuration**: Environment, features, and integrations
- 👥 **User Management**: Accounts, permissions, and access control
- 🚫 **Ban Management**: User bans and IP blocking
- 📊 **Monitoring**: System health and performance
- 🔐 **Security**: Audit logs and incident response
- 💾 **Operations**: Backups, maintenance, and scaling
## Quick Links
### Administration Tasks
- **[Admin Panel Overview](./panel)** - Your administrative dashboard
- **[User Management](./user-management)** - Manage user accounts
- **[Ban Management](./ban-management)** - Handle bans and restrictions
- **[IP Blocking](./ip-blocking)** - Block malicious IP addresses
- **[Permission Management](./permissions)** - Configure access control
- **[Audit Logs](./audit-logs)** - Review administrative actions
### Configuration
- **[Environment Variables](./environment)** - Core configuration
- **[Feature Flags](./feature-flags)** - Enable/disable features
- **[Rate Limiting](./rate-limiting)** - Configure API limits
- **[Security Settings](./security)** - Security configuration
- **[Integration Settings](./integrations)** - External services
### Operations
- **[Backup Procedures](./backup)** - Data backup strategies
- **[Restore Procedures](./restore)** - Recovery from backups
- **[Monitoring](./monitoring)** - System monitoring setup
- **[Alert Handling](./alerts)** - Responding to alerts
- **[Incident Response](./incident-response)** - Security incidents
- **[Maintenance](./maintenance)** - Routine maintenance tasks
## Admin Roles
Spywatcher has different administrative privilege levels:
### Super Admin
**Full system access**:
- All configuration changes
- User account management
- System-wide operations
- Database access
- Security settings
### Server Admin
**Server-specific administration**:
- Server configuration
- User permissions for their servers
- Server-level bans
- Analytics access
- Audit log review
### Moderator
**Limited administrative functions**:
- View analytics
- Review user reports
- Temporary bans
- Limited user management
## Getting Started
### First-Time Setup
1. **[Configure Environment](./environment)** - Set up core settings
2. **[Enable Features](./feature-flags)** - Choose which features to activate
3. **[Configure Security](./security)** - Set up authentication and encryption
4. **[Set Up Monitoring](./monitoring)** - Enable health checks and alerts
5. **[Configure Backups](./backup)** - Set up automated backups
### Daily Tasks
- Review audit logs
- Check system health dashboards
- Handle user reports
- Monitor rate limiting metrics
- Review security alerts
### Weekly Tasks
- Review backup integrity
- Analyze usage patterns
- Update security rules
- Clean up old data
- Performance optimization
### Monthly Tasks
- Full system audit
- Update dependencies
- Review and update documentation
- Capacity planning
- Security assessment
## Admin Dashboard
The admin panel provides:
### System Overview
- **Active Users**: Currently logged in
- **API Requests**: Per minute/hour/day
- **Error Rate**: System errors and warnings
- **Resource Usage**: CPU, memory, database
### Quick Actions
- Create/manage users
- Review recent bans
- Check audit logs
- Export analytics
- System maintenance
### Alerts
- Security incidents
- System errors
- Performance degradation
- Quota violations
- Unusual activity patterns
## Security Considerations
### Access Control
- Use strong passwords and 2FA
- Limit admin access to necessary personnel
- Regularly review admin permissions
- Enable audit logging for all admin actions
- Use separate accounts for different privilege levels
### Data Protection
- Encrypt sensitive data at rest
- Use TLS for all connections
- Regularly update security certificates
- Implement proper key rotation
- Follow data retention policies
### Monitoring
- Enable intrusion detection
- Monitor for unusual patterns
- Set up automated alerts
- Regular security audits
- Keep software updated
## Common Administrative Tasks
### Adding a New Admin
1. Navigate to **Admin Panel** > **Users**
2. Click **"Create Admin User"**
3. Set username and initial password
4. Assign appropriate role (Super Admin, Server Admin, Moderator)
5. Enable 2FA requirement
6. Send credentials securely
### Handling User Reports
1. Review report in **Admin Panel** > **Reports**
2. Investigate using timeline and analytics
3. Check audit logs for suspicious activity
4. Take appropriate action (warn, ban, no action)
5. Document decision in case notes
### Managing Server Resources
1. Check **Monitoring** dashboard
2. Review resource usage trends
3. Adjust rate limits if needed
4. Scale infrastructure if necessary
5. Document changes in operations log
### Responding to Security Incidents
1. Review alert details
2. Follow [Incident Response](./incident-response) procedures
3. Contain the incident
4. Investigate root cause
5. Implement fixes
6. Document incident and response
## Best Practices
### ✅ Do's
1. **Regular Backups**: Automate and verify backups
2. **Monitor Actively**: Don't ignore alerts
3. **Document Changes**: Keep detailed change logs
4. **Test Updates**: Use staging environment
5. **Review Logs**: Regular audit log review
6. **Secure Access**: Strong authentication required
7. **Update Regularly**: Keep system and dependencies updated
### ❌ Don'ts
1. **Don't Share Credentials**: Each admin has unique account
2. **Don't Skip Backups**: Data loss is preventable
3. **Don't Ignore Warnings**: Small issues become big problems
4. **Don't Rush Changes**: Test in staging first
5. **Don't Disable Logging**: Audit trail is essential
6. **Don't Use Weak Passwords**: Security is paramount
7. **Don't Operate Solo**: Have backup admins trained
## Configuration Files
### Environment Configuration
Located in `.env` files:
```bash
# Example admin-relevant configuration
DATABASE_URL=postgresql://user:pass@host:5432/db
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secure-secret
ADMIN_EMAIL=admin@example.com
BACKUP_ENABLED=true
BACKUP_SCHEDULE="0 2 * * *"
MONITORING_ENABLED=true
SENTRY_DSN=https://your-sentry-dsn
```
### Feature Flags
Control features via environment or admin panel:
```bash
FEATURE_GHOST_DETECTION=true
FEATURE_SUSPICION_SCORING=true
FEATURE_PLUGINS=true
FEATURE_PUBLIC_API=true
```
## Support and Resources
### Documentation
- **[Configuration Guide](./environment)** - Detailed config reference
- **[Operations Manual](./backup)** - Operational procedures
- **[Security Guide](./security)** - Security best practices
### Tools
- **Admin CLI**: Command-line administration tools
- **Monitoring Dashboards**: Grafana, Prometheus
- **Log Analysis**: Loki, Elasticsearch
- **Database Tools**: pgAdmin, SQL clients
### Getting Help
- **[GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)** - Report bugs or issues
- **[Developer Guide](/developer/)** - Technical deep-dives
- **Community Support** - Discord server (coming soon)
## What's Next?
Get started with these guides:
1. **[Admin Panel Overview](./panel)** - Learn the admin interface
2. **[Environment Configuration](./environment)** - Configure your instance
3. **[User Management](./user-management)** - Manage user accounts
4. **[Monitoring Setup](./monitoring)** - Set up monitoring and alerts
---
::: tip Need Help?
If you encounter issues or need clarification, check the [troubleshooting guide](/guide/troubleshooting) or open an issue on GitHub.
:::

126
docs/api/authentication.md Normal file
View File

@@ -0,0 +1,126 @@
# Authentication
Learn how to authenticate with the Spywatcher API.
## Authentication Methods
### JWT Bearer Token
The primary authentication method uses JWT bearer tokens.
#### Getting Your API Key
1. Sign in to Spywatcher dashboard
2. Navigate to **Settings** > **API Keys**
3. Click **Create New API Key**
4. Copy your key (starts with `spy_live_`)
#### Using Your Token
Include the token in the Authorization header:
```http
Authorization: Bearer spy_live_your_api_key_here
```
### OAuth2 (Coming Soon)
OAuth2 authentication for third-party applications.
## API Key Management
### Creating Keys
- Name your keys descriptively
- Create separate keys for different applications
- Use environment-specific keys
### Key Security
- Never commit keys to version control
- Rotate keys regularly
- Use environment variables
- Revoke compromised keys immediately
### Permissions
API keys can have limited permissions:
- Read-only access
- Write access
- Admin access
## Code Examples
::: code-group
```typescript [TypeScript]
const apiKey = process.env.SPYWATCHER_API_KEY;
const response = await fetch('https://api.spywatcher.com/api/analytics', {
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
});
```
```python [Python]
import os
import requests
api_key = os.getenv('SPYWATCHER_API_KEY')
response = requests.get(
'https://api.spywatcher.com/api/analytics',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
)
```
```bash [cURL]
curl -H "Authorization: Bearer spy_live_your_api_key" \
-H "Content-Type: application/json" \
https://api.spywatcher.com/api/analytics
```
:::
## Error Responses
### 401 Unauthorized
**Cause**: Invalid or missing token
**Response**:
```json
{
"error": "Unauthorized",
"message": "Invalid or missing authentication token",
"statusCode": 401
}
```
### 403 Forbidden
**Cause**: Valid token but insufficient permissions
**Response**:
```json
{
"error": "Forbidden",
"message": "Insufficient permissions for this resource",
"statusCode": 403
}
```
## Related
- [API Reference](./index)
- [Rate Limiting](./rate-limiting)
- [Error Handling](./errors)
::: warning Security
Never expose API keys in client-side code or commit them to version control.
:::

518
docs/api/ghosts.md Normal file
View File

@@ -0,0 +1,518 @@
# Ghost Detection API
Retrieve ghost detection scores for users in a guild.
## Get Ghost Scores
Retrieve ghost detection scores for users based on presence and message activity.
### Request
```http
GET /api/ghosts?guildId={guildId}&limit=50
Authorization: Bearer {token}
```
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `guildId` | string | No | Filter by guild ID. If omitted, returns data for all accessible guilds. |
| `limit` | integer | No | Number of results to return (1-100, default: 50) |
| `minPresenceCount` | integer | No | Minimum presence count threshold (default: 30) |
| `maxMessageCount` | integer | No | Maximum message count threshold (default: 10) |
| `minScore` | number | No | Minimum ghost score (default: 0) |
| `sort` | string | No | Sort field: `score`, `presenceCount`, `messageCount` (default: `score`) |
| `order` | string | No | Sort order: `asc` or `desc` (default: `desc`) |
### Response
```json
{
"data": [
{
"userId": "123456789",
"username": "SilentBob#1234",
"avatar": "https://cdn.discordapp.com/avatars/123456789/abc123.png",
"presenceCount": 150,
"messageCount": 5,
"ghostScore": 25.0,
"lastSeen": "2024-11-03T12:00:00.000Z",
"accountCreated": "2023-01-15T10:00:00.000Z",
"roles": ["@Member", "@Verified"],
"multiClientCount": 45
}
],
"meta": {
"total": 42,
"page": 1,
"limit": 50,
"totalPages": 1
}
}
```
### Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `userId` | string | Discord user ID |
| `username` | string | Discord username with discriminator |
| `avatar` | string | URL to user's avatar image |
| `presenceCount` | integer | Number of times user was detected online |
| `messageCount` | integer | Number of messages sent |
| `ghostScore` | number | Calculated ghost score (presenceCount / (messageCount + 1)) |
| `lastSeen` | string | ISO 8601 timestamp of last presence |
| `accountCreated` | string | ISO 8601 timestamp of account creation |
| `roles` | array | List of role names |
| `multiClientCount` | integer | Number of times multiple clients were used simultaneously |
## Error Responses
### 401 Unauthorized
Invalid or missing authentication token.
```json
{
"error": "Unauthorized",
"message": "Invalid or missing authentication token",
"statusCode": 401
}
```
### 403 Forbidden
Insufficient permissions to access guild data.
```json
{
"error": "Forbidden",
"message": "You do not have permission to access this guild's data",
"statusCode": 403
}
```
### 404 Not Found
Guild not found or bot not in guild.
```json
{
"error": "Not Found",
"message": "Guild not found or bot is not a member",
"statusCode": 404
}
```
### 429 Too Many Requests
Rate limit exceeded.
```json
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Try again in 60 seconds.",
"statusCode": 429,
"retryAfter": 60
}
```
## Code Examples
::: code-group
```typescript [TypeScript]
import { SpywatcherClient } from '@spywatcher/sdk';
const client = new SpywatcherClient({
apiKey: 'spy_live_your_api_key',
});
// Get ghost scores for a guild
const ghosts = await client.ghosts.list({
guildId: '123456789',
minScore: 10,
limit: 50,
});
console.log(`Found ${ghosts.meta.total} ghost users`);
ghosts.data.forEach(ghost => {
console.log(`${ghost.username}: ${ghost.ghostScore}`);
});
```
```typescript [TypeScript (Fetch)]
const response = await fetch(
'https://api.spywatcher.com/api/ghosts?guildId=123456789&minScore=10',
{
headers: {
'Authorization': `Bearer ${apiKey}`,
},
}
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log('Ghost users:', data.data);
```
```python [Python]
import requests
response = requests.get(
'https://api.spywatcher.com/api/ghosts',
params={
'guildId': '123456789',
'minScore': 10,
'limit': 50
},
headers={'Authorization': f'Bearer {api_key}'}
)
if response.status_code == 200:
data = response.json()
print(f"Found {data['meta']['total']} ghost users")
for ghost in data['data']:
print(f"{ghost['username']}: {ghost['ghostScore']}")
else:
print(f"Error: {response.status_code}")
print(response.json())
```
```javascript [JavaScript]
fetch('https://api.spywatcher.com/api/ghosts?guildId=123456789&minScore=10', {
headers: {
'Authorization': `Bearer ${apiKey}`,
},
})
.then(res => {
if (!res.ok) throw new Error(`HTTP error! status: ${res.status}`);
return res.json();
})
.then(data => {
console.log(`Found ${data.meta.total} ghost users`);
data.data.forEach(ghost => {
console.log(`${ghost.username}: ${ghost.ghostScore}`);
});
})
.catch(error => console.error('Error:', error));
```
```bash [cURL]
curl -X GET \
'https://api.spywatcher.com/api/ghosts?guildId=123456789&minScore=10&limit=50' \
-H 'Authorization: Bearer spy_live_your_api_key'
```
```go [Go]
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
type GhostResponse struct {
Data []struct {
Username string `json:"username"`
GhostScore float64 `json:"ghostScore"`
PresenceCount int `json:"presenceCount"`
MessageCount int `json:"messageCount"`
} `json:"data"`
Meta struct {
Total int `json:"total"`
} `json:"meta"`
}
func main() {
apiKey := "spy_live_your_api_key"
guildId := "123456789"
url := fmt.Sprintf("https://api.spywatcher.com/api/ghosts?guildId=%s&minScore=10", guildId)
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result GhostResponse
json.Unmarshal(body, &result)
fmt.Printf("Found %d ghost users\n", result.Meta.Total)
for _, ghost := range result.Data {
fmt.Printf("%s: %.2f\n", ghost.Username, ghost.GhostScore)
}
}
```
:::
## Run Ghost Detection Scan
Trigger a new ghost detection scan for a guild.
### Request
```http
POST /api/ghosts/scan
Authorization: Bearer {token}
Content-Type: application/json
```
### Body
```json
{
"guildId": "123456789",
"minPresenceCount": 30,
"maxMessageCount": 10,
"timeRange": {
"start": "2024-01-01T00:00:00.000Z",
"end": "2024-12-31T23:59:59.999Z"
}
}
```
### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `guildId` | string | Yes | Guild ID to scan |
| `minPresenceCount` | integer | No | Minimum presence threshold (default: 30) |
| `maxMessageCount` | integer | No | Maximum message threshold (default: 10) |
| `timeRange` | object | No | Date range for analysis |
| `timeRange.start` | string | No | Start date (ISO 8601) |
| `timeRange.end` | string | No | End date (ISO 8601) |
### Response
```json
{
"data": {
"scanId": "scan_abc123xyz",
"guildId": "123456789",
"status": "processing",
"startedAt": "2024-11-03T12:00:00.000Z",
"estimatedCompletion": "2024-11-03T12:05:00.000Z"
}
}
```
### Check Scan Status
```http
GET /api/ghosts/scan/{scanId}
Authorization: Bearer {token}
```
**Response:**
```json
{
"data": {
"scanId": "scan_abc123xyz",
"status": "completed",
"resultsCount": 42,
"completedAt": "2024-11-03T12:04:30.000Z",
"results": "/api/ghosts?scanId=scan_abc123xyz"
}
}
```
## Get User Ghost Details
Get detailed ghost analysis for a specific user.
### Request
```http
GET /api/ghosts/{userId}
Authorization: Bearer {token}
```
### Response
```json
{
"data": {
"userId": "123456789",
"username": "SilentBob#1234",
"ghostScore": 25.0,
"presenceCount": 150,
"messageCount": 5,
"analysis": {
"classification": "Strong Ghost",
"riskLevel": "medium",
"recommendations": [
"Monitor for pattern changes",
"Check if account is legitimate bot",
"Review channel access history"
]
},
"timeline": [
{
"date": "2024-11-01",
"presences": 15,
"messages": 0
},
{
"date": "2024-11-02",
"presences": 18,
"messages": 1
}
],
"patterns": {
"peakHours": [9, 10, 11, 14, 15, 16],
"activeChannels": ["#general", "#announcements"],
"averageSessionDuration": 3600,
"multiClientUsage": 0.3
}
}
}
```
## Webhooks
Subscribe to ghost detection events via webhooks:
### Events
- `ghost.detected` - New ghost user identified
- `ghost.score_changed` - Ghost score changed significantly
- `ghost.scan_completed` - Scan finished
### Example Webhook Payload
```json
{
"event": "ghost.detected",
"timestamp": "2024-11-03T12:00:00.000Z",
"data": {
"userId": "123456789",
"username": "SilentBob#1234",
"ghostScore": 25.0,
"guildId": "987654321",
"previousScore": null
}
}
```
## Rate Limits
Ghost detection endpoints have specific rate limits:
| Endpoint | FREE | PRO | ENTERPRISE |
|----------|------|-----|------------|
| `GET /api/ghosts` | 10/hour | 100/hour | 1000/hour |
| `POST /api/ghosts/scan` | 1/day | 10/day | Unlimited |
| `GET /api/ghosts/{userId}` | 100/hour | 1000/hour | 10000/hour |
## Best Practices
### 1. Use Appropriate Thresholds
```typescript
// For active communities
const activeServerGhosts = await client.ghosts.list({
minPresenceCount: 50,
maxMessageCount: 5,
});
// For smaller communities
const smallServerGhosts = await client.ghosts.list({
minPresenceCount: 20,
maxMessageCount: 10,
});
```
### 2. Cache Results
```typescript
// Cache results for 1 hour
const cacheKey = `ghosts:${guildId}`;
const cached = await redis.get(cacheKey);
if (cached) {
return JSON.parse(cached);
}
const ghosts = await client.ghosts.list({ guildId });
await redis.setex(cacheKey, 3600, JSON.stringify(ghosts));
return ghosts;
```
### 3. Handle Pagination
```typescript
async function getAllGhosts(guildId: string) {
const allGhosts = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const response = await client.ghosts.list({
guildId,
page,
limit: 100,
});
allGhosts.push(...response.data);
hasMore = response.meta.hasNext;
page++;
}
return allGhosts;
}
```
### 4. Use Filters Effectively
```typescript
// Get only high-risk ghosts
const highRiskGhosts = await client.ghosts.list({
guildId,
minScore: 25,
sort: 'score',
order: 'desc',
});
// Get recently active ghosts
const recentGhosts = await client.ghosts.list({
guildId,
minScore: 10,
sort: 'lastSeen',
order: 'desc',
});
```
## Related Endpoints
- **[Lurker Detection API](./lurkers)** - Similar detection for lurkers
- **[Suspicion Scores API](./suspicion)** - Comprehensive behavior analysis
- **[User Timeline API](./timeline)** - Individual user activity tracking
- **[Analytics API](./analytics)** - Server-wide analytics
## See Also
- **[Ghost Detection Guide](/guide/ghost-detection)** - User guide
- **[Understanding Ghost Scores](/guide/suspicion-scores)** - Score interpretation
- **[Best Practices](/guide/troubleshooting)** - Usage recommendations
---
::: tip Interactive Testing
Try the ghost detection API in our [Swagger UI](http://localhost:3001/api/docs) for interactive testing and exploration.
:::

409
docs/api/index.md Normal file
View File

@@ -0,0 +1,409 @@
# API Reference
Welcome to the Spywatcher API documentation. This guide covers the REST API, WebSocket API, and SDK usage.
## Overview
The Spywatcher API provides programmatic access to all surveillance and analytics features. Build custom integrations, automation tools, or third-party applications.
## Base URL
```
Production: https://api.spywatcher.com/api
Development: http://localhost:3001/api
```
## Interactive Documentation
Spywatcher includes interactive API documentation:
- **Swagger UI**: [http://localhost:3001/api/docs](http://localhost:3001/api/docs)
- **ReDoc**: [http://localhost:3001/api/redoc](http://localhost:3001/api/redoc)
Both interfaces allow you to:
- Browse all endpoints
- Test API calls directly
- View request/response schemas
- Try authentication
## Authentication
All API requests require authentication using JWT Bearer tokens.
### Get API Token
1. Sign in to the Spywatcher dashboard
2. Navigate to **Settings** > **API Keys**
3. Click **"Create New API Key"**
4. Copy your key (starts with `spy_live_`)
### Using Your Token
Include the token in the `Authorization` header:
```bash
curl -H "Authorization: Bearer spy_live_your_api_key_here" \
https://api.spywatcher.com/api/analytics
```
::: warning Security
Never commit API keys to version control or expose them in client-side code.
:::
## Rate Limiting
API requests are rate-limited based on your subscription tier:
| Tier | Rate Limit | Daily Quota |
|------|------------|-------------|
| **FREE** | 10 req/min | 1,000 req/day |
| **PRO** | 100 req/min | 100,000 req/day |
| **ENTERPRISE** | 1,000 req/min | Unlimited |
Rate limit information is included in response headers:
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699027200
```
Learn more about [Rate Limiting](./rate-limiting).
## Response Format
All API responses follow a consistent JSON format:
### Success Response
```json
{
"data": {
// Response data
},
"meta": {
"total": 42,
"page": 1,
"limit": 50
}
}
```
### Error Response
```json
{
"error": "Unauthorized",
"message": "Invalid or missing authentication token",
"statusCode": 401
}
```
Learn more about [Error Handling](./errors).
## Pagination
List endpoints support pagination:
```http
GET /api/users?page=2&limit=50
```
**Parameters:**
- `page`: Page number (default: 1)
- `limit`: Results per page (default: 50, max: 100)
**Response includes:**
```json
{
"data": [...],
"meta": {
"total": 250,
"page": 2,
"limit": 50,
"totalPages": 5,
"hasNext": true,
"hasPrev": true
}
}
```
Learn more about [Pagination](./pagination).
## Filtering and Sorting
### Filtering
Use query parameters to filter results:
```http
GET /api/users?status=online&role=member
```
### Sorting
Use `sort` parameter:
```http
GET /api/users?sort=createdAt:desc
```
Syntax: `field:direction` where direction is `asc` or `desc`.
## Date Ranges
Endpoints that support date filtering accept:
```http
GET /api/analytics?startDate=2024-01-01&endDate=2024-12-31
```
Format: ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ss.sssZ`)
## API Endpoints
### Analytics
- **[GET /api/analytics](./analytics)** - Get server analytics
- **[GET /api/analytics/users](./analytics#user-analytics)** - User analytics
- **[GET /api/analytics/trends](./analytics#trends)** - Activity trends
### Users
- **[GET /api/users](./users)** - List users
- **[GET /api/users/:id](./users#get-user)** - Get user details
- **[GET /api/users/:id/timeline](./users#user-timeline)** - User timeline
### Ghost Detection
- **[GET /api/ghosts](./ghosts)** - Get ghost scores
- **[POST /api/ghosts/scan](./ghosts#run-scan)** - Run detection
### Lurker Detection
- **[GET /api/lurkers](./lurkers)** - Get lurker data
- **[POST /api/lurkers/scan](./lurkers#run-scan)** - Run detection
### Suspicion Scores
- **[GET /api/suspicion](./suspicion)** - Get suspicion scores
- **[GET /api/suspicion/:userId](./suspicion#user-score)** - User score
### Timeline
- **[GET /api/timeline](./timeline)** - Get activity timeline
- **[GET /api/timeline/:userId](./timeline#user-timeline)** - User timeline
### Bans
- **[GET /api/bans](./bans)** - List bans
- **[POST /api/bans](./bans#create-ban)** - Create ban
- **[DELETE /api/bans/:id](./bans#remove-ban)** - Remove ban
### Privacy
- **[GET /api/privacy/settings](./privacy)** - Get privacy settings
- **[PUT /api/privacy/settings](./privacy#update-settings)** - Update settings
## WebSocket API
Real-time updates via WebSocket:
```javascript
const ws = new WebSocket('ws://localhost:3001');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Update:', data);
};
```
Learn more about [WebSocket Events](./websocket).
## SDKs
Official SDKs for easy integration:
### TypeScript/JavaScript
```bash
npm install @spywatcher/sdk
```
```typescript
import { SpywatcherClient } from '@spywatcher/sdk';
const client = new SpywatcherClient({
apiKey: 'spy_live_your_api_key',
});
const analytics = await client.analytics.get();
```
Learn more: [TypeScript SDK Guide](./sdk-typescript)
### Python SDK (Coming Soon)
```python
from spywatcher import SpywatcherClient
client = SpywatcherClient(api_key='spy_live_your_api_key')
analytics = client.analytics.get()
```
Learn more: [Python SDK Guide](./sdk-python)
## Code Examples
All endpoints include code examples in multiple languages:
::: code-group
```typescript [TypeScript]
const response = await fetch('https://api.spywatcher.com/api/analytics', {
headers: {
'Authorization': `Bearer ${apiKey}`,
},
});
const data = await response.json();
```
```python [Python]
import requests
response = requests.get(
'https://api.spywatcher.com/api/analytics',
headers={'Authorization': f'Bearer {api_key}'}
)
data = response.json()
```
```javascript [JavaScript]
fetch('https://api.spywatcher.com/api/analytics', {
headers: {
'Authorization': `Bearer ${apiKey}`,
},
})
.then(res => res.json())
.then(data => console.log(data));
```
```bash [cURL]
curl -H "Authorization: Bearer spy_live_your_api_key" \
https://api.spywatcher.com/api/analytics
```
:::
## Webhooks (Coming Soon)
Configure webhooks to receive event notifications:
- User banned
- High suspicion score detected
- Ghost user identified
- Unusual activity detected
## API Versions
Current version: **v1**
All endpoints are versioned: `/api/v1/...`
Version information is included in responses:
```json
{
"apiVersion": "1.0.0",
"data": {...}
}
```
## API Status
Check API status:
- **Status Page**: [https://status.spywatcher.com](https://status.spywatcher.com)
- **Health Endpoint**: [GET /health](./health)
## OpenAPI Specification
Download the OpenAPI spec:
- **JSON**: [/api/openapi.json](http://localhost:3001/api/openapi.json)
- **YAML**: [/api/openapi.yaml](http://localhost:3001/api/openapi.yaml)
Use with code generation tools like:
- [OpenAPI Generator](https://openapi-generator.tech/)
- [Swagger Codegen](https://swagger.io/tools/swagger-codegen/)
## Best Practices
### 1. Handle Rate Limits
```typescript
if (response.status === 429) {
const retryAfter = response.headers.get('X-RateLimit-Reset');
// Wait and retry
}
```
### 2. Implement Retry Logic
```typescript
async function apiCallWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fetch(url, options);
} catch (error) {
if (i === maxRetries - 1) throw error;
await sleep(1000 * Math.pow(2, i)); // Exponential backoff
}
}
}
```
### 3. Cache Responses
```typescript
// Cache analytics data for 5 minutes
const cacheKey = 'analytics';
const cached = cache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < 300000) {
return cached.data;
}
```
### 4. Use Webhooks for Real-time Updates
Instead of polling, configure webhooks for event-driven updates.
### 5. Monitor Your Usage
Track your API usage to avoid hitting quotas:
```typescript
const usage = await client.quota.get();
console.log(`Used ${usage.used} of ${usage.limit} requests`);
```
## Support
Need help with the API?
- **[GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)** - Report bugs or issues
- **[Developer Guide](/developer/)** - Technical documentation
- **[Stack Overflow](https://stackoverflow.com/questions/tagged/spywatcher)** - Community Q&A
## What's Next?
- **[Authentication Guide](./authentication)** - Learn about authentication
- **[Analytics API](./analytics)** - Fetch analytics data
- **[Ghost Detection API](./ghosts)** - Access ghost detection
- **[TypeScript SDK](./sdk-typescript)** - Use the official SDK
---
::: tip Pro Tip
Use the interactive Swagger UI at `/api/docs` to explore and test the API without writing code!
:::

163
docs/changelog.md Normal file
View File

@@ -0,0 +1,163 @@
# Changelog
All notable changes to Spywatcher will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Comprehensive VitePress documentation site
- User guide with installation, quick start, and feature guides
- Admin guide for configuration and operations
- Developer guide with architecture and contribution guidelines
- API reference with code examples in multiple languages
- Interactive Swagger/OpenAPI documentation
- Search functionality across all documentation
- Dark mode support
- Mobile-responsive documentation layout
### Documentation
- Getting Started Guide
- Ghost Detection documentation
- Lurker Detection documentation
- Suspicion Scores explanation
- Heatmap visualization guide
- Dashboard overview
- Analytics guide
- Filters and search guide
- Troubleshooting guide
- FAQ section
- Environment configuration reference
- API endpoint documentation with examples
## [1.0.0] - 2024-11-01
### Added
- Discord bot for presence and message tracking
- React-based web dashboard
- REST API with authentication
- Ghost detection algorithm
- Lurker detection
- Suspicion scoring system
- Real-time WebSocket updates
- PostgreSQL database with Prisma ORM
- Redis caching
- Docker support for development and production
- CI/CD pipelines with GitHub Actions
- Prometheus and Grafana monitoring
- Comprehensive test suite
### Features
- Multi-client login detection
- Role drift tracking
- Channel activity analytics
- User presence analytics
- Behavioral pattern analysis
- Export capabilities (CSV, JSON, PDF)
- Filter and search functionality
- Plugin system
- Public API with SDK
### Security
- Discord OAuth2 authentication
- JWT session management
- Role-based access control
- Rate limiting
- Audit logging
- Privacy controls
## [0.9.0] - 2024-10-15
### Added
- Beta release for testing
- Core analytics engine
- Basic web interface
- Discord bot foundation
### Changed
- Migrated from SQLite to PostgreSQL
- Improved presence tracking accuracy
- Enhanced security measures
### Fixed
- WebSocket connection stability
- Memory leak in presence tracker
- Race conditions in analytics calculations
## [0.1.0] - 2024-09-01
### Added
- Initial project setup
- Basic Discord bot
- Proof of concept analytics
- SQLite database
---
## Version History
- **1.0.0** - First stable release (November 2024)
- **0.9.0** - Beta release (October 2024)
- **0.1.0** - Initial proof of concept (September 2024)
## Upgrade Guide
### Upgrading to 1.0.0 from 0.9.0
1. **Backup your database**
```bash
npm run db:backup
```
2. **Update dependencies**
```bash
npm install
```
3. **Run database migrations**
```bash
cd backend
npx prisma migrate deploy
```
4. **Update environment variables**
- Check `.env.example` for new variables
- Update your `.env` file accordingly
5. **Restart services**
```bash
docker-compose restart
```
## Breaking Changes
### Version 1.0.0
- **Database Migration Required**: Upgraded from SQLite to PostgreSQL
- **API Changes**: Some endpoint paths have changed
- **Configuration**: New environment variables required
- **Authentication**: Updated JWT implementation
## Deprecations
### Version 1.0.0
- SQLite support has been removed
- Legacy API v0 endpoints are no longer supported
- Old webhook format is deprecated (migrate to new format)
## Support
For issues or questions about releases:
- [GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)
- [Documentation](/guide/)
- [Developer Guide](/developer/)
---
[Unreleased]: https://github.com/subculture-collective/discord-spywatcher/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/subculture-collective/discord-spywatcher/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/subculture-collective/discord-spywatcher/compare/v0.1.0...v0.9.0
[0.1.0]: https://github.com/subculture-collective/discord-spywatcher/releases/tag/v0.1.0

356
docs/developer/contributing.md Normal file
View File

@@ -0,0 +1,356 @@
# Contributing to Spywatcher
Thank you for your interest in contributing to Spywatcher! This guide will help you get started.
## Code of Conduct
We are committed to providing a welcoming and inclusive environment. Please be respectful and professional in all interactions.
### Our Standards
- Use welcoming and inclusive language
- Be respectful of differing viewpoints
- Accept constructive criticism gracefully
- Focus on what's best for the community
- Show empathy towards other community members
## Ways to Contribute
### Reporting Bugs
Found a bug? Please report it!
1. **Check existing issues** to avoid duplicates
2. **Use the bug template** when creating a new issue
3. **Include details:**
- Description of the bug
- Steps to reproduce
- Expected behavior
- Actual behavior
- Screenshots if applicable
- Environment details (OS, Node version, etc.)
### Suggesting Features
Have an idea for improvement?
1. **Check existing feature requests**
2. **Use the feature request template**
3. **Explain:**
- The problem you're trying to solve
- Your proposed solution
- Why it would be valuable
- Alternative solutions considered
### Contributing Code
Ready to code? Great!
1. **Fork the repository**
2. **Create a branch**: `git checkout -b feature/your-feature`
3. **Make your changes**
4. **Write tests**
5. **Ensure all tests pass**
6. **Submit a pull request**
## Development Setup
### Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Redis 6+
- Git
### Setup Steps
```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/discord-spywatcher.git
cd discord-spywatcher
# Add upstream remote
git remote add upstream https://github.com/subculture-collective/discord-spywatcher.git
# Install dependencies
npm install
cd backend && npm install
cd ../frontend && npm install
# Copy environment files
cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
# Set up database
cd backend
npx prisma migrate dev
```
## Development Workflow
### 1. Create a Branch
```bash
git checkout -b feature/my-new-feature
```
Branch naming conventions:
- `feature/feature-name` - New features
- `fix/bug-description` - Bug fixes
- `docs/what-changed` - Documentation
- `refactor/what-changed` - Code refactoring
- `test/what-added` - Test additions
### 2. Make Changes
- Follow the [code style guide](./code-style)
- Write clear, concise code
- Add comments where necessary
- Update documentation
### 3. Write Tests
- Add unit tests for new functions
- Add integration tests for API endpoints
- Add E2E tests for user workflows
- Ensure all tests pass
```bash
# Run tests
npm test
# Run with coverage
npm run test:coverage
```
### 4. Commit Changes
Follow [Conventional Commits](https://www.conventionalcommits.org/):
```bash
feat: add ghost detection API endpoint
fix: resolve WebSocket connection issue
docs: update installation guide
test: add integration tests for analytics
refactor: simplify suspicion scoring logic
chore: update dependencies
```
Commit message format:
```
<type>(<scope>): <subject>
<body>
<footer>
```
Examples:
```bash
git commit -m "feat(api): add ghost detection endpoint
- Implements GET /api/ghosts
- Includes filtering and sorting
- Adds comprehensive tests
- Updates OpenAPI spec
Closes #123"
```
### 5. Keep Your Fork Updated
```bash
git fetch upstream
git rebase upstream/main
```
### 6. Push Changes
```bash
git push origin feature/my-new-feature
```
## Pull Request Process
### Before Submitting
✅ Checklist:
- [ ] Code follows style guide
- [ ] All tests pass
- [ ] New tests added for new features
- [ ] Documentation updated
- [ ] No console.log or debug code
- [ ] Commit messages follow convention
- [ ] Branch is up to date with main
### Submitting PR
1. **Go to GitHub** and create a Pull Request
2. **Fill out the template** completely
3. **Link related issues** using "Closes #123"
4. **Describe your changes** clearly
5. **Add screenshots** for UI changes
6. **Request review** from maintainers
### PR Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
Describe tests added/modified
## Screenshots
If applicable, add screenshots
## Checklist
- [ ] Code follows style guide
- [ ] Tests pass
- [ ] Documentation updated
```
### Review Process
1. **Automated checks** run (CI/CD)
2. **Maintainer review** (may request changes)
3. **Address feedback** if needed
4. **Approval** by maintainer(s)
5. **Merge** into main branch
## Code Style
### TypeScript/JavaScript
- Use TypeScript for type safety
- Follow ESLint rules
- Use Prettier for formatting
- Write descriptive variable names
- Avoid `any` types when possible
```typescript
// Good
async function getUserAnalytics(userId: string): Promise<Analytics> {
const user = await prisma.user.findUnique({
where: { id: userId },
include: { analytics: true },
});
return user.analytics;
}
// Bad
async function getStuff(id: any): Promise<any> {
const data = await prisma.user.findUnique({ where: { id } });
return data.analytics;
}
```
### React/TSX
- Use functional components
- Use hooks appropriately
- Keep components small and focused
- Use proper prop types
```tsx
// Good
interface UserCardProps {
user: User;
onSelect: (id: string) => void;
}
export function UserCard({ user, onSelect }: UserCardProps) {
return (
<div className="card" onClick={() => onSelect(user.id)}>
<h3>{user.username}</h3>
</div>
);
}
```
### Testing
- Write clear test descriptions
- Follow AAA pattern (Arrange, Act, Assert)
- Mock external dependencies
- Test edge cases
```typescript
describe('Ghost Score Calculation', () => {
it('should calculate correct score with messages', () => {
// Arrange
const presenceCount = 100;
const messageCount = 5;
// Act
const score = calculateGhostScore(presenceCount, messageCount);
// Assert
expect(score).toBe(16.67);
});
});
```
## Documentation
### When to Update Docs
Update documentation when you:
- Add new features
- Change existing behavior
- Fix bugs that affect usage
- Update APIs
- Change configuration
### Documentation Style
- Use clear, concise language
- Include code examples
- Add screenshots for UI features
- Use proper markdown formatting
- Link to related documentation
## Getting Help
Need help contributing?
- **Discord** (coming soon)
- **GitHub Discussions**
- **GitHub Issues** - Tag with `question`
- **Email** - maintainers@spywatcher.com (if urgent)
## Recognition
Contributors are recognized in:
- CONTRIBUTORS.md file
- GitHub Contributors page
- Release notes
- Documentation credits
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
## Questions?
Don't hesitate to ask questions! We're here to help:
- Open an issue tagged with `question`
- Reach out to maintainers
- Check existing documentation
Thank you for contributing to Spywatcher! 🎉
---
See also:
- [Development Setup](./local-environment)
- [Code Style Guide](./code-style)
- [Testing Guide](./testing)
- [Pull Request Guide](./pull-requests)

549
docs/developer/index.md Normal file
View File

@@ -0,0 +1,549 @@
# Developer Guide
Welcome to the Spywatcher Developer Guide! This guide will help you set up your development environment, understand the architecture, and contribute to the project.
## Overview
Spywatcher is a full-stack Discord surveillance and analytics application built with:
- **Backend**: Node.js, Express, TypeScript, Prisma
- **Frontend**: React, Vite, Tailwind CSS
- **Database**: PostgreSQL
- **Cache**: Redis
- **Bot**: discord.js
## Quick Start for Developers
### 1. Prerequisites
Ensure you have installed:
- **Node.js**: v18+ ([Download](https://nodejs.org/))
- **npm**: v8+ (comes with Node.js)
- **Git**: Version control
- **PostgreSQL**: v14+ (or use Docker)
- **Redis**: v6+ (or use Docker)
- **Docker** (optional but recommended)
### 2. Clone and Install
```bash
# Clone repository
git clone https://github.com/subculture-collective/discord-spywatcher.git
cd discord-spywatcher
# Install root dependencies (git hooks, etc.)
npm install
# Install backend dependencies
cd backend
npm install
# Install frontend dependencies
cd ../frontend
npm install
```
### 3. Set Up Environment
```bash
# Copy example environment files
cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
```
Edit the files with your Discord credentials and database URLs.
### 4. Start Development
**Option A: Using Docker (Recommended)**
```bash
# Start all services
docker-compose -f docker-compose.dev.yml up
```
**Option B: Manual Start**
```bash
# Terminal 1: Start PostgreSQL and Redis (if not using Docker)
# Terminal 2: Start Discord bot
cd backend
npm run dev
# Terminal 3: Start API server
cd backend
npm run dev:api
# Terminal 4: Start frontend
cd frontend
npm run dev
```
## Development Workflow
### Git Workflow
1. **Fork** the repository
2. **Clone** your fork
3. **Create** a feature branch: `git checkout -b feature/your-feature`
4. **Make** changes and commit with conventional commits
5. **Push** to your fork
6. **Create** a Pull Request
### Commit Convention
We use [Conventional Commits](https://www.conventionalcommits.org/):
```bash
feat: add ghost detection API endpoint
fix: resolve WebSocket connection issue
docs: update installation guide
test: add integration tests for analytics
refactor: simplify suspicion scoring logic
chore: update dependencies
```
### Code Quality
Before committing, ensure:
```bash
# Run linters
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format
# Type check
npm run type-check
# Run tests
npm test
```
### Git Hooks
Pre-commit hooks automatically run:
- ESLint on changed files
- Prettier on changed files
- Type checking
Commit message hooks validate:
- Conventional commit format
- Message length and structure
## Project Structure
```
discord-spywatcher/
├── backend/ # Backend services
│ ├── src/
│ │ ├── index.ts # Discord bot entry
│ │ ├── server.ts # API server entry
│ │ ├── routes/ # API routes
│ │ ├── services/ # Business logic
│ │ ├── middleware/ # Express middleware
│ │ ├── analytics/ # Analytics engine
│ │ └── types/ # TypeScript types
│ ├── prisma/ # Database schema
│ ├── __tests__/ # Tests
│ └── plugins/ # Plugin system
├── frontend/ # React frontend
│ ├── src/
│ │ ├── pages/ # Page components
│ │ ├── components/ # Reusable components
│ │ ├── hooks/ # Custom React hooks
│ │ ├── store/ # State management
│ │ ├── lib/ # Utilities
│ │ └── types/ # TypeScript types
│ └── e2e/ # E2E tests
├── docs/ # Documentation (VitePress)
├── sdk/ # TypeScript SDK
├── scripts/ # Utility scripts
├── k8s/ # Kubernetes configs
├── terraform/ # Infrastructure as code
└── docker-compose.*.yml # Docker configs
```
## Key Concepts
### Architecture Overview
```mermaid
graph TB
subgraph Client
FE[React Frontend]
end
subgraph Backend
API[Express API]
BOT[Discord Bot]
WS[WebSocket Server]
end
subgraph Data
PG[(PostgreSQL)]
RD[(Redis Cache)]
end
subgraph External
DA[Discord API]
end
FE -->|HTTPS| API
FE -->|WebSocket| WS
API --> PG
API --> RD
BOT --> DA
BOT --> PG
WS --> RD
```
### Authentication Flow
1. User clicks "Sign in with Discord"
2. Redirects to Discord OAuth2
3. User authorizes application
4. Discord redirects back with code
5. Backend exchanges code for access token
6. Backend creates JWT session token
7. Frontend stores JWT and uses for API calls
### Data Flow
1. **Discord Bot** listens for presence and message events
2. **Bot** writes events to PostgreSQL
3. **Analytics Engine** processes raw data into metrics
4. **API Server** serves metrics to frontend
5. **Frontend** displays analytics
6. **WebSocket** pushes real-time updates
## Testing
### Backend Tests
```bash
cd backend
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests
npm run test:integration
# Run with coverage
npm run test:coverage
# Watch mode
npm run test:watch
```
### Frontend Tests
```bash
cd frontend
# Run unit tests
npm test
# Run E2E tests
npm run test:e2e
# Run with coverage
npm run test:coverage
```
### Writing Tests
**Unit Test Example** (`backend/__tests__/unit/analytics.test.ts`):
```typescript
import { calculateGhostScore } from '../../src/analytics/ghost';
describe('Ghost Score Calculation', () => {
it('should calculate ghost score correctly', () => {
const score = calculateGhostScore(100, 5);
expect(score).toBe(16.67);
});
it('should handle zero messages', () => {
const score = calculateGhostScore(100, 0);
expect(score).toBe(100);
});
});
```
**Integration Test Example** (`backend/__tests__/integration/api.test.ts`):
```typescript
import request from 'supertest';
import { app } from '../../src/server';
describe('Analytics API', () => {
it('GET /api/analytics returns analytics data', async () => {
const response = await request(app)
.get('/api/analytics')
.set('Authorization', `Bearer ${testToken}`)
.expect(200);
expect(response.body).toHaveProperty('totalUsers');
expect(response.body).toHaveProperty('activeUsers');
});
});
```
## API Development
### Creating a New Endpoint
1. **Define Route** (`backend/src/routes/myFeature.ts`):
```typescript
import { Router } from 'express';
import { authenticate } from '../middleware/auth';
const router = Router();
router.get('/my-feature', authenticate, async (req, res) => {
try {
const data = await getMyFeatureData(req.user.id);
res.json(data);
} catch (error) {
res.status(500).json({ error: 'Internal server error' });
}
});
export default router;
```
2. **Add Service Logic** (`backend/src/services/myFeature.ts`):
```typescript
import { prisma } from '../config/database';
export async function getMyFeatureData(userId: string) {
const data = await prisma.myFeature.findMany({
where: { userId },
});
return data;
}
```
3. **Register Route** (`backend/src/server.ts`):
```typescript
import myFeatureRouter from './routes/myFeature';
app.use('/api/my-feature', myFeatureRouter);
```
4. **Add Tests**
5. **Update OpenAPI Spec**
6. **Update Documentation**
## Database Development
### Schema Changes
1. **Edit Prisma Schema** (`backend/prisma/schema.prisma`):
```prisma
model MyNewModel {
id String @id @default(uuid())
userId String
data Json
createdAt DateTime @default(now())
user User @relation(fields: [userId], references: [id])
@@index([userId])
}
```
2. **Create Migration**:
```bash
cd backend
npx prisma migrate dev --name add_my_new_model
```
3. **Generate Client**:
```bash
npx prisma generate
```
### Database Queries
Use Prisma Client for type-safe queries:
```typescript
// Find many with relations
const users = await prisma.user.findMany({
where: {
isActive: true,
},
include: {
presences: true,
messages: true,
},
orderBy: {
createdAt: 'desc',
},
});
// Aggregations
const stats = await prisma.presence.aggregate({
where: {
userId: userId,
},
_count: true,
_avg: {
duration: true,
},
});
```
## Frontend Development
### Creating a New Page
1. **Create Page Component** (`frontend/src/pages/MyFeature.tsx`):
```tsx
import React from 'react';
import { useMyFeature } from '../hooks/useMyFeature';
export default function MyFeature() {
const { data, loading, error } = useMyFeature();
if (loading) return <Loading />;
if (error) return <Error message={error} />;
return (
<div className="container mx-auto p-4">
<h1 className="text-2xl font-bold">My Feature</h1>
{/* Your component JSX */}
</div>
);
}
```
2. **Create Custom Hook** (`frontend/src/hooks/useMyFeature.ts`):
```typescript
import { useState, useEffect } from 'react';
import { api } from '../lib/api';
export function useMyFeature() {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
async function fetchData() {
try {
const result = await api.get('/my-feature');
setData(result.data);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
}
fetchData();
}, []);
return { data, loading, error };
}
```
3. **Add Route** (`frontend/src/App.tsx`):
```tsx
import MyFeature from './pages/MyFeature';
<Route path="/my-feature" element={<MyFeature />} />
```
## Debugging
### Backend Debugging
**VS Code Configuration** (`.vscode/launch.json`):
```json
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Backend",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev:api"],
"cwd": "${workspaceFolder}/backend",
"skipFiles": ["<node_internals>/**"]
}
]
}
```
### Frontend Debugging
Use React DevTools and browser developer tools:
- Install [React Developer Tools](https://react.dev/learn/react-developer-tools)
- Use browser console for debugging
- Enable React DevTools Profiler for performance
### Database Debugging
```bash
# View current schema
npx prisma db pull
# Open Prisma Studio (GUI)
npx prisma studio
# View migration status
npx prisma migrate status
```
## Documentation
When adding features, update:
1. **Code Comments**: JSDoc for functions
2. **README Files**: Update relevant READMEs
3. **API Documentation**: Update OpenAPI spec
4. **User Guide**: Add user-facing documentation
5. **Developer Guide**: Add technical details
## Resources
- **[Architecture Guide](./architecture)** - System design details
- **[API Architecture](./api-architecture)** - API design patterns
- **[Database Schema](./database-schema)** - Database structure
- **[Contributing Guide](./contributing)** - Contribution guidelines
- **[Testing Guide](./testing)** - Testing strategies
## Next Steps
1. **[Set up your environment](./local-environment)**
2. **[Understand the architecture](./architecture)**
3. **[Run the tests](./testing)**
4. **[Read the contributing guide](./contributing)**
5. **[Start coding!](./contributing)**
---
::: tip Getting Help
Join our development discussions on GitHub or open an issue if you need help!
:::

108
docs/guide/advanced-charts.md Normal file
View File

@@ -0,0 +1,108 @@
# Advanced Charts
Explore advanced visualization options for server analytics.
## Overview
Spywatcher provides multiple chart types for visualizing your Discord server's activity patterns and trends.
## Chart Types
### Line Charts
**Best for**: Trends over time
- Activity trends
- User growth
- Message volume
- Presence patterns
### Bar Charts
**Best for**: Comparisons
- Channel activity comparison
- User activity comparison
- Role distribution
- Time period comparisons
### Pie Charts
**Best for**: Distribution
- Channel usage breakdown
- Role distribution
- Activity type distribution
- User status distribution
### Heatmaps
**Best for**: Pattern detection
- Time-based activity
- Channel activity matrix
- User engagement patterns
### Scatter Plots
**Best for**: Correlations
- Ghost score vs message count
- Presence vs activity
- Multi-dimensional analysis
## Customization
### Chart Options
Configure:
- Colors and themes
- Data ranges
- Aggregation periods
- Filters
- Labels and legends
### Interactive Features
- Zoom and pan
- Hover tooltips
- Click to drill down
- Export as image
- Full-screen mode
## Advanced Analytics
### Combining Charts
Create dashboards with multiple charts:
- Overview dashboard
- User analysis dashboard
- Channel insights dashboard
- Security monitoring dashboard
### Custom Queries
Build custom visualizations:
1. Select data source
2. Choose chart type
3. Configure axes and filters
4. Save as preset
## Export
Export charts as:
- PNG images
- SVG vectors
- PDF reports
- Data (CSV/JSON)
## Related
- [Analytics](./analytics)
- [Heatmap](./heatmap)
- [Dashboard](./dashboard)
- [Advanced Visualizations](/docs/ADVANCED_VISUALIZATIONS.md)
::: tip
Save frequently used chart configurations as presets for quick access.
:::

99
docs/guide/analytics.md Normal file
View File

@@ -0,0 +1,99 @@
# Analytics
Comprehensive analytics and metrics for understanding your Discord server's activity patterns.
## Overview
Spywatcher provides detailed analytics across multiple dimensions:
- User activity trends
- Message patterns
- Presence statistics
- Channel utilization
- Role distribution
- Behavioral patterns
## Analytics Views
### Server Overview
High-level metrics:
- Total users
- Active users
- Message count
- Presence events
- Average session duration
### User Analytics
Per-user metrics:
- Activity score
- Message frequency
- Presence patterns
- Multi-client usage
- Role history
### Channel Analytics
Channel-specific data:
- Message volume
- Active users per channel
- Peak activity times
- Channel popularity
### Time-based Analytics
Temporal analysis:
- Daily activity trends
- Weekly patterns
- Monthly comparisons
- Historical data
## Filters
### Date Range
Select time periods:
- Last 24 hours
- Last 7 days
- Last 30 days
- Last 90 days
- Custom range
### User Filters
Filter by:
- Role
- Join date
- Activity level
- Status
### Channel Filters
Analyze specific:
- Channels
- Categories
- Channel types
## Export
Export analytics data in multiple formats:
- CSV for spreadsheets
- JSON for programmatic access
- PDF reports
## Visualizations
- Line charts for trends
- Bar charts for comparisons
- Pie charts for distribution
- Heatmaps for patterns
## Related
- [Dashboard](./dashboard)
- [Heatmap](./heatmap)
- [Advanced Charts](/docs/ADVANCED_CHARTS_GUIDE.md)
::: tip Best Practice
Review analytics weekly to identify trends and patterns in your server's activity.
:::

166
docs/guide/dashboard.md Normal file
View File

@@ -0,0 +1,166 @@
# Dashboard Overview
The Spywatcher dashboard is your central hub for monitoring Discord server activity and accessing analytics.
## Dashboard Layout
### Header
- **Server Selector**: Switch between monitored servers
- **User Menu**: Access settings and logout
- **Notifications**: View alerts and updates
- **Search**: Quick search for users and data
### Sidebar Navigation
- Dashboard (Home)
- Analytics
- Ghost Detection
- Lurker Detection
- Suspicion Scores
- Heatmap
- Timeline
- Settings
### Main Content Area
The dashboard displays real-time overview cards and activity feeds.
## Overview Cards
### Total Users
Shows the total number of members in the selected server.
- **Metric**: Total member count
- **Update Frequency**: Real-time
- **Click Action**: View detailed user list
### Active Users
Members who have been online in the last 24 hours.
- **Metric**: Active user count
- **Trend Indicator**: Compared to previous 24h
- **Click Action**: View active user list
### Ghost Users
Users with high presence but low message activity.
- **Metric**: Current ghost user count
- **Threshold**: Based on your settings
- **Click Action**: Open ghost detection view
### Lurkers
Passive users who rarely engage.
- **Metric**: Identified lurker count
- **Score Range**: Based on activity thresholds
- **Click Action**: View lurker analysis
### Suspicion Score Average
Average suspicion score across all monitored users.
- **Metric**: Mean suspicion score
- **Range**: 0-100
- **Trend**: Compared to previous period
## Recent Activity Feed
### Presence Changes
Real-time feed of user status changes:
- User went online
- User went offline
- Status updates
- Multi-client detection
### Message Activity
Recent message activity indicators:
- Message count trends
- Channel activity spikes
- Unusual messaging patterns
### Behavioral Alerts
Automated alerts for:
- High suspicion scores
- Ghost user detected
- Unusual multi-client activity
- Mass user join/leave
## Quick Actions
### Run Detection
- Ghost Detection Scan
- Lurker Detection Scan
- Full Analytics Refresh
### Export Data
- Export current view to CSV
- Download analytics report
- Generate PDF summary
### Manage Filters
- Create filter preset
- Load saved filters
- Reset to defaults
## Real-time Updates
The dashboard uses WebSocket connections for live updates:
- 🟢 **Connected**: Real-time updates active
- 🟡 **Connecting**: Attempting to connect
- 🔴 **Disconnected**: No real-time updates
## Customization
### Widget Layout
Drag and drop widgets to customize your dashboard layout.
### Card Settings
Click the settings icon on any card to:
- Toggle visibility
- Adjust refresh rate
- Configure thresholds
- Set alert preferences
### Theme
Switch between light and dark mode using the theme toggle.
## Keyboard Shortcuts
- `Ctrl/Cmd + K`: Quick search
- `Ctrl/Cmd + B`: Toggle sidebar
- `G then D`: Go to Dashboard
- `G then A`: Go to Analytics
- `R`: Refresh current view
## Mobile View
The dashboard is fully responsive and optimized for mobile devices:
- Collapsible sidebar
- Touch-optimized controls
- Simplified card layout
- Swipe gestures for navigation
## Related Features
- [Analytics](./analytics) - Detailed metrics and trends
- [Ghost Detection](./ghost-detection) - Find silent users
- [Heatmap](./heatmap) - Visual activity patterns
::: tip Pro Tip
Customize your dashboard layout to focus on the metrics most important to your server's needs.
:::

171
docs/guide/faq.md Normal file
View File

@@ -0,0 +1,171 @@
# Frequently Asked Questions
Common questions about Spywatcher.
## General
### What is Spywatcher?
Spywatcher is a Discord surveillance and analytics tool that monitors user presence, messages, and behavior patterns to provide insights about your server.
### Is Spywatcher free?
Spywatcher has multiple tiers:
- **FREE**: Basic features, limited API access
- **PRO**: Advanced features, higher quotas
- **ENTERPRISE**: Full features, unlimited access
### Is my data secure?
Yes. Spywatcher uses:
- Discord OAuth2 authentication
- Encrypted data storage
- Secure API connections
- Privacy controls
## Setup and Configuration
### How do I install Spywatcher?
See the [Installation Guide](./installation) for detailed instructions. The easiest method is using Docker.
### What permissions does the bot need?
Required permissions:
- View Channels
- Read Message History
- View Server Insights
Privileged intents:
- Presence Intent
- Server Members Intent
- Message Content Intent
### Can I monitor multiple servers?
Yes! You can monitor any server where the Spywatcher bot is present and you have appropriate permissions.
## Features
### What is ghost detection?
Ghost detection identifies users who are frequently online but rarely participate. See [Ghost Detection Guide](./ghost-detection).
### How are suspicion scores calculated?
Suspicion scores use multiple factors including presence patterns, message activity, and behavioral changes. See [Suspicion Scores](./suspicion-scores).
### Can I export data?
Yes, you can export data in CSV, JSON, or PDF formats from any view.
### Does Spywatcher work with voice channels?
Spywatcher primarily tracks presence and text messages. Voice channel tracking is limited to presence in voice channels.
## Privacy and Security
### What data does Spywatcher collect?
Spywatcher collects:
- User presence events
- Message counts (not content by default)
- User roles and permissions
- Timestamp data
### Can users opt out?
Yes, users can request data deletion and opt out of tracking through privacy settings.
### Is message content stored?
By default, only message counts are stored, not content. Message content tracking can be enabled but requires explicit consent.
### Who can see the analytics?
Only server administrators and users with appropriate permissions can access analytics for their servers.
## Technical
### What tech stack is used?
- Backend: Node.js, Express, TypeScript, Prisma
- Frontend: React, Vite, Tailwind CSS
- Database: PostgreSQL
- Cache: Redis
- Bot: discord.js
### Can I self-host Spywatcher?
Yes! Spywatcher is open-source. See the [Installation Guide](./installation) and [Deployment Guide](/developer/deployment).
### Is there an API?
Yes! Spywatcher provides a comprehensive REST API. See [API Documentation](/api/).
### How do I contribute?
See the [Contributing Guide](/developer/contributing) for information on contributing to Spywatcher.
## Troubleshooting
### Bot is offline
Check:
1. Bot token is correct
2. Privileged intents are enabled
3. Bot has been invited to server
4. Backend service is running
### No data showing
Ensure:
1. Bot has been running for some time
2. Bot has proper permissions
3. Users are active in the server
4. Date range filters are appropriate
### Authentication fails
Try:
1. Clearing browser cache
2. Using different browser
3. Checking OAuth2 configuration
4. Re-inviting the bot
For more issues, see [Troubleshooting](./troubleshooting).
## Support
### How do I get help?
- Read the documentation
- Check [GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)
- Join the community Discord (coming soon)
### How do I report bugs?
Open an issue on [GitHub](https://github.com/subculture-collective/discord-spywatcher/issues) with:
- Description of the bug
- Steps to reproduce
- Expected behavior
- Actual behavior
- Logs and error messages
### How do I request features?
Open a feature request on [GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues) with:
- Description of the feature
- Use case
- Why it would be valuable
## More Questions?
If your question isn't answered here:
- Check the relevant guide sections
- Search [GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)
- Open a new issue
::: tip
The documentation search (Ctrl/Cmd + K) can help you find answers quickly!
:::

117
docs/guide/filters.md Normal file
View File

@@ -0,0 +1,117 @@
# Filters and Search
Use filters and search to find specific data quickly.
## Quick Search
Press `Ctrl/Cmd + K` to open quick search:
- Search for users by username or ID
- Jump to any page
- Search documentation
- View recent actions
## Filter Panel
Access filters using the filter icon in any view.
### Common Filters
#### Date Range
- Last 24 hours
- Last 7 days
- Last 30 days
- Last 90 days
- Custom range
#### User Filters
- **Role**: Filter by Discord roles
- **Status**: Online, offline, idle, DND
- **Activity Level**: Active, inactive, ghost
- **Join Date**: Before/after specific date
#### Activity Filters
- **Message Count**: Minimum/maximum
- **Presence Count**: Minimum/maximum
- **Suspicion Score**: Score range
- **Ghost Score**: Score threshold
#### Channel Filters
- Specific channels
- Channel categories
- Channel types (text, voice, announcement)
## Filter Presets
### Creating Presets
1. Configure filters
2. Click "Save as Preset"
3. Name your preset
4. Access from presets menu
### Built-in Presets
- **High Activity Users**: Active members
- **New Members**: Recently joined
- **Ghosts**: High ghost scores
- **Moderators**: Staff activity
- **Suspicious**: High suspicion scores
## Advanced Search
### Search Syntax
Use advanced search operators:
```
username:john # Search by username
role:moderator # Filter by role
score:>50 # Suspicion score above 50
messages:>100 # More than 100 messages
joined:<2024-01-01 # Joined before date
```
### Combining Filters
Chain multiple filters:
```
role:member status:online messages:>10
```
## Sorting
Sort results by:
- Username (A-Z or Z-A)
- Activity level (high to low)
- Join date (newest/oldest)
- Suspicion score (high to low)
- Last seen (recent/oldest)
## Exporting Filtered Results
After applying filters:
1. Click "Export"
2. Choose format (CSV, JSON, PDF)
3. Download filtered data
## Tips
- Save frequently used filters as presets
- Use quick search for individual users
- Combine multiple filters for precision
- Export filtered data for analysis
## Related
- [Dashboard](./dashboard)
- [Analytics](./analytics)
- [Quick Start](./quick-start)
::: tip Keyboard Shortcut
Press `Ctrl/Cmd + K` anywhere to open quick search!
:::

428
docs/guide/ghost-detection.md Normal file
View File

@@ -0,0 +1,428 @@
# Ghost Detection
Ghost detection identifies users who are frequently present in the Discord server but rarely participate in conversations.
## What is a Ghost User?
A ghost user is someone who:
- ✅ Has **high presence counts** (online frequently)
- ✅ Has **low message counts** (rarely speaks)
- ❓ May be lurking or using automated tools
- ❓ Could be legitimate passive observers
## How It Works
Spywatcher calculates a **"ghost score"** for each user based on their activity patterns:
```
Ghost Score = Presence Count / (Message Count + 1)
```
### Why This Formula?
- **Presence Count**: Number of times the bot detected the user online
- **Message Count**: Number of messages sent in tracked channels
- **+1 Denominator**: Prevents division by zero for users with no messages
- **Higher Score**: Indicates more "ghostly" behavior (high presence, low participation)
### Example Calculation
For a user named "SilentBob":
```json
{
"userId": "123456789",
"username": "SilentBob#1234",
"presenceCount": 150,
"messageCount": 5,
"ghostScore": 25.0
}
```
**Calculation**: 150 / (5 + 1) = 25.0
This user has been online 150 times but only sent 5 messages, indicating strong ghost-like behavior.
## Interpreting Results
### Ghost Score Ranges
| Score Range | Classification | Interpretation |
|-------------|---------------|----------------|
| **> 50** | 🔴 **Extreme Ghost** | Almost certainly automated or surveillance account |
| **25-50** | 🟠 **Strong Ghost** | Very high presence with minimal participation |
| **10-25** | 🟡 **Likely Ghost** | High presence, low participation |
| **5-10** | 🟢 **Passive Lurker** | Moderate presence, some participation |
| **< 5** | ✅ **Normal User** | Balanced presence and participation |
### What Each Level Means
#### Extreme Ghost (> 50)
**Characteristics:**
- Online constantly but virtually never speaks
- May be a bot monitoring the server
- Could be using automated tools
- Possible surveillance or data collection account
**Recommended Action:**
- Investigate account creation date
- Check if the account is a bot
- Review permissions and roles
- Consider restricting access to sensitive channels
#### Strong Ghost (25-50)
**Characteristics:**
- Very frequent online presence
- Minimal message activity
- May be legitimate lurker or passive consumer
- Could be monitoring specific channels
**Recommended Action:**
- Monitor for pattern changes
- Check if they react to messages
- Review channel access history
- Consider reaching out to understand their usage
#### Likely Ghost (10-25)
**Characteristics:**
- Regular online presence
- Occasional messages
- Possibly shy or passive community member
- May prefer reading to writing
**Recommended Action:**
- Generally acceptable behavior
- Monitor for changes
- Encourage participation through events
- No immediate action needed
## Using the Ghost Detection Tool
### Step 1: Access Ghost Detection
Navigate to **Ghost Detection** from the sidebar or dashboard.
### Step 2: Configure Detection Parameters
Set your detection criteria:
#### Minimum Presence Count
- **Default**: 50
- **Purpose**: Only analyze users with sufficient data
- **Low values**: More users, less reliable
- **High values**: Fewer users, more reliable
```
Recommended: 30-100 depending on server activity
```
#### Maximum Message Count
- **Default**: 10
- **Purpose**: Threshold for "low participation"
- **Low values**: Stricter (fewer messages = ghost)
- **High values**: More lenient
```
Recommended: 5-15 depending on server culture
```
#### Time Period
- **Options**: 7 days, 30 days, 90 days, All time
- **Default**: 30 days
- **Purpose**: Analyze recent or historical behavior
```
Recommended: 30 days for current behavior
```
### Step 3: Run Detection
Click **"Run Detection"** to analyze users based on your criteria.
### Step 4: Review Results
Results are displayed in a sortable table:
| Column | Description |
|--------|-------------|
| **Username** | User's Discord name and discriminator |
| **Presence Count** | Times detected online |
| **Message Count** | Messages sent in period |
| **Ghost Score** | Calculated score |
| **Last Seen** | Last online timestamp |
| **Actions** | View details, timeline, or export |
### Step 5: Investigate Users
Click **"Details"** on any user to see:
- **Activity Timeline**: When they were online
- **Channel Distribution**: Which channels they visit
- **Message Patterns**: When they do speak
- **Role History**: Changes in permissions
- **Multi-client Usage**: Simultaneous device usage
## Advanced Features
### Filtering Results
Refine your ghost list with filters:
#### By Score Range
```
Minimum Score: 10
Maximum Score: 50
```
Shows only users within specific ghost score range.
#### By Role
```
Role Filter: @Members, @Verified
```
Analyze specific role groups for ghost behavior.
#### By Join Date
```
Joined After: 2024-01-01
Joined Before: 2024-12-31
```
Focus on users who joined in a specific period.
### Batch Operations
Select multiple users and:
- **Export Data**: Download as CSV or JSON
- **Add to Watchlist**: Monitor for changes
- **Generate Report**: Create summary document
- **Set Alert Thresholds**: Get notified of changes
### Automated Monitoring
Set up automatic ghost detection:
1. Go to **Settings** > **Scheduled Tasks**
2. Enable **"Weekly Ghost Scan"**
3. Configure parameters:
- Schedule: Every Monday at 9:00 AM
- Minimum Score: 15
- Notification: Discord webhook
4. Save configuration
You'll receive weekly reports automatically.
## Common Scenarios
### Scenario 1: Bot Accounts
**Observation**: User with score > 100, online 24/7
**Analysis**:
```json
{
"username": "SuspiciousBot#0001",
"presenceCount": 5000,
"messageCount": 0,
"ghostScore": 5000,
"pattern": "Constant online presence, never offline"
}
```
**Action**: Likely a bot. Verify and remove if unauthorized.
### Scenario 2: Legitimate Lurker
**Observation**: User with score 8, occasionally speaks
**Analysis**:
```json
{
"username": "ShyMember#1234",
"presenceCount": 80,
"messageCount": 10,
"ghostScore": 7.27,
"pattern": "Regular presence, minimal but genuine participation"
}
```
**Action**: Normal behavior, no action needed.
### Scenario 3: Surveillance Account
**Observation**: New account with immediate high presence
**Analysis**:
```json
{
"username": "NewAccount#5678",
"presenceCount": 200,
"messageCount": 1,
"ghostScore": 100,
"accountAge": "7 days",
"pattern": "Joined recently, immediately active but silent"
}
```
**Action**: Investigate thoroughly. May be monitoring server.
## Best Practices
### ✅ Do's
1. **Use Context**: Consider server culture and purpose
2. **Investigate First**: High scores don't always mean malicious intent
3. **Regular Monitoring**: Run detection weekly or bi-weekly
4. **Adjust Thresholds**: Tune parameters for your community
5. **Combine Metrics**: Use with suspicion scores and timeline analysis
### ❌ Don'ts
1. **Don't Auto-Ban**: Never automatically ban based solely on ghost score
2. **Don't Ignore Low Scores**: Some malicious users may participate occasionally
3. **Don't Forget Legitimate Use Cases**: Some users prefer passive consumption
4. **Don't Overlook New Users**: New members may need time to engage
5. **Don't Ignore Context**: Time zones and activity patterns matter
## Legitimate Ghost Users
Not all ghosts are problematic:
### Voice Chat Participants
Users who primarily use voice channels:
- High presence in voice
- Low message count
- Legitimate participation
### Timezone Differences
Users in different timezones:
- Online when chat is slow
- May appear as ghosts despite being active
### Content Consumers
Users who prefer reading:
- Genuine interest in community
- Passive consumption is their style
- May participate through reactions
### Moderators
Staff using monitoring tools:
- High presence for oversight
- Low public messages
- Legitimate administrative role
## Integration with Other Features
### Suspicion Scores
Ghost detection feeds into suspicion scoring:
- High ghost score increases suspicion
- Combined with other behavioral signals
- More comprehensive threat assessment
### Timeline Analysis
View ghost users' timelines:
- Identify presence patterns
- Correlate with server events
- Detect coordinated behavior
### Privacy Controls
Respect user privacy:
- Some users opt out of tracking
- Ghost scores may be limited
- Check privacy status in user details
## Troubleshooting
### No Users Detected
**Cause**: Thresholds too strict or insufficient data
**Solution**: Lower presence count minimum or extend time period
### Too Many Users
**Cause**: Thresholds too lenient
**Solution**: Increase minimum presence count or decrease message count threshold
### Inaccurate Scores
**Cause**: Bot not tracking all presence events
**Solution**: Verify bot has proper intents and permissions
## Export and Reporting
### CSV Export
Export ghost detection results:
```csv
Username,UserID,PresenceCount,MessageCount,GhostScore,LastSeen
SilentBob#1234,123456789,150,5,25.0,2024-11-03T12:00:00Z
```
### JSON Export
```json
[
{
"userId": "123456789",
"username": "SilentBob#1234",
"presenceCount": 150,
"messageCount": 5,
"ghostScore": 25.0,
"lastSeen": "2024-11-03T12:00:00Z",
"roles": ["@Member", "@Verified"],
"accountCreated": "2023-01-15T10:00:00Z"
}
]
```
### Report Generation
Generate PDF reports with:
- Executive summary
- Top ghost users
- Trend analysis
- Recommendations
## Related Features
- **[Lurker Detection](./lurker-detection)** - Similar but different metrics
- **[Suspicion Scores](./suspicion-scores)** - Comprehensive behavior analysis
- **[Timeline Analysis](./timeline)** - Individual user tracking
- **[Heatmap](./heatmap)** - Visual activity patterns
::: tip Pro Tip
Combine ghost detection with timeline analysis to understand if users are consistent ghosts or if their behavior changed recently.
:::
::: warning Important
Some legitimate users may have high ghost scores (moderators, voice-only users, different timezones). Always investigate before taking action.
:::
## Next Steps
1. **[Run your first ghost detection](./quick-start#step-5-run-your-first-detection)**
2. **[Learn about suspicion scores](./suspicion-scores)**
3. **[Explore timeline analysis](./timeline)**

50
docs/guide/guild-selection.md Normal file
View File

@@ -0,0 +1,50 @@
# Guild Selection
Choose which Discord servers to monitor with Spywatcher.
## Selecting Your Server
After signing in, you'll see a list of all servers where:
1. You are a member
2. The Spywatcher bot is present
3. You have appropriate permissions
### Selection Steps
1. View the guild list
2. Check server details (member count, bot status)
3. Click "Select" on your desired server
4. Confirm selection
## Multiple Servers
Monitor multiple servers by:
- Selecting additional servers from the guild list
- Using the server switcher in the navigation bar
## Server Requirements
For a server to appear in the list:
- ✅ Spywatcher bot must be invited
- ✅ Bot must have required permissions
- ✅ You must have access to view server insights
## Switching Servers
Use the server dropdown in the top navigation to quickly switch between monitored servers.
## Permissions
You need these Discord permissions:
- View Channels
- Read Message History
- View Server Insights (for full analytics)
::: warning Bot Required
The Spywatcher bot must be invited to your server before you can monitor it. See the [Installation Guide](./installation#discord-bot-setup) for details.
:::
## Related
- [Installation Guide](./installation)
- [Quick Start](./quick-start)

105
docs/guide/heatmap.md Normal file
View File

@@ -0,0 +1,105 @@
# Heatmap Visualization
Visualize server activity patterns with interactive heatmaps.
## What is a Heatmap?
A heatmap displays activity intensity across:
- Time periods (hours, days, weeks)
- Channels
- User groups
Color intensity indicates activity level:
- 🔴 Red: High activity
- 🟡 Yellow: Moderate activity
- 🟢 Green: Low activity
- ⚪ White: No activity
## Heatmap Types
### Time-based Heatmap
Shows activity by:
- Hour of day (24-hour view)
- Day of week
- Week of month
**Use Cases:**
- Identify peak activity times
- Schedule announcements
- Plan events
### Channel Heatmap
Displays activity across channels:
- Message volume per channel
- User participation by channel
- Channel popularity trends
**Use Cases:**
- Identify active/inactive channels
- Channel reorganization
- Moderation resource allocation
### User Activity Heatmap
Shows user engagement patterns:
- Active hours per user
- Participation frequency
- Activity distribution
## Configuration
### Time Range
Select period to analyze:
- Last 7 days
- Last 30 days
- Custom range
### Granularity
Choose detail level:
- Hourly
- Daily
- Weekly
### Filters
Filter by:
- Channels
- User roles
- Activity types
## Interpretation
### Peak Times
Identify when your server is most active for:
- Event scheduling
- Announcement timing
- Moderation coverage
### Inactive Periods
Find quiet times for:
- Maintenance windows
- Bot updates
- System changes
### Channel Usage
Understand which channels are:
- Highly active (may need more moderation)
- Underutilized (consider archiving)
- Growing in popularity
## Related
- [Analytics](./analytics)
- [Dashboard](./dashboard)
- [Advanced Charts](/docs/ADVANCED_CHARTS_GUIDE.md)
::: tip Pro Tip
Use heatmaps weekly to understand changing activity patterns in your server.
:::

66
docs/guide/index.md Normal file
View File

@@ -0,0 +1,66 @@
# User Guide
Welcome to the Spywatcher User Guide! This guide will help you understand and use all the features of Spywatcher to monitor and analyze your Discord server.
## What is Spywatcher?
Spywatcher is a comprehensive surveillance and analytics tool for Discord servers. It monitors user presence, tracks activity patterns, and provides insights into server behavior through an intuitive web dashboard.
## Key Features
### 🔍 Detection Systems
- **Ghost Detection**: Identify users who are frequently online but rarely participate
- **Lurker Detection**: Find passive observers who don't engage with the community
- **Suspicion Scoring**: Automated scoring system for unusual behavior patterns
### 📊 Analytics & Visualization
- **Interactive Dashboards**: Real-time overview of server activity
- **Heatmaps**: Visualize activity patterns across time and channels
- **Timeline Analysis**: Track user behavior over time
- **Advanced Charts**: Multiple visualization types for deep insights
### 🔐 Security & Privacy
- **Discord OAuth2**: Secure authentication through Discord
- **Role-Based Access**: Control who can view sensitive analytics
- **Privacy Controls**: Configure what data is tracked and displayed
- **Audit Logs**: Track all administrative actions
### ⚡ Real-time Updates
- **WebSocket Integration**: Live updates without page refresh
- **Instant Notifications**: Get alerted to important events
- **Live Analytics**: Watch server activity in real-time
## Getting Started
New to Spywatcher? Start here:
1. **[Installation Guide](./installation)** - Set up Spywatcher for your server
2. **[Quick Start](./quick-start)** - Get up and running in minutes
3. **[Discord OAuth Setup](./oauth-setup)** - Connect your Discord account
4. **[Guild Selection](./guild-selection)** - Choose which servers to monitor
## Core Features
Once you're set up, explore these features:
- **[Dashboard Overview](./dashboard)** - Understand your main control panel
- **[Analytics](./analytics)** - Deep dive into server metrics
- **[Ghost Detection](./ghost-detection)** - Find silent observers
- **[Lurker Detection](./lurker-detection)** - Identify passive users
- **[Heatmap Visualization](./heatmap)** - See activity patterns
- **[Suspicion Scores](./suspicion-scores)** - Understand behavior ratings
- **[Filters and Search](./filters)** - Find specific data quickly
## Need Help?
- **[Troubleshooting](./troubleshooting)** - Common issues and solutions
- **[FAQ](./faq)** - Frequently asked questions
- **[GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)** - Report bugs or request features
## What's Next?
Ready to dive in? Head to the [Installation Guide](./installation) to get started!

275
docs/guide/installation.md Normal file
View File

@@ -0,0 +1,275 @@
# Installation
This guide will walk you through installing Spywatcher on your system.
## Prerequisites
Before installing Spywatcher, ensure you have:
- **Node.js**: Version 18 or higher ([Download](https://nodejs.org/))
- **npm**: Version 8 or higher (comes with Node.js)
- **Discord Bot**: A Discord bot application ([Create one](https://discord.com/developers/applications))
- **PostgreSQL**: Version 14 or higher (for production)
- **Redis**: Version 6 or higher (for caching)
::: tip Docker Alternative
If you prefer Docker, skip to [Docker Installation](#docker-installation-recommended) for a simpler setup.
:::
## Installation Methods
### Docker Installation (Recommended)
The easiest way to run Spywatcher is using Docker Compose:
#### Step 1: Clone the Repository
```bash
git clone https://github.com/subculture-collective/discord-spywatcher.git
cd discord-spywatcher
```
#### Step 2: Configure Environment
Copy the example environment file and configure it:
```bash
cp .env.example .env
```
Edit `.env` with your settings:
```bash
# Discord Configuration
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_CLIENT_ID=your_client_id_here
DISCORD_CLIENT_SECRET=your_client_secret_here
DISCORD_REDIRECT_URI=http://localhost:5173/auth/callback
# Database
DATABASE_URL=postgresql://spywatcher:password@postgres:5432/spywatcher
# Redis
REDIS_URL=redis://redis:6379
# JWT Secret (generate a secure random string)
JWT_SECRET=your_secure_jwt_secret_here
# Application
NODE_ENV=development
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:3001
```
::: warning Security Note
Never commit your `.env` file to version control! Always generate secure random strings for `JWT_SECRET`.
:::
#### Step 3: Start the Application
For development:
```bash
docker-compose -f docker-compose.dev.yml up
```
For production:
```bash
docker-compose -f docker-compose.prod.yml up -d
```
#### Step 4: Access the Application
Once the containers are running:
- **Frontend Dashboard**: [http://localhost:5173](http://localhost:5173)
- **Backend API**: [http://localhost:3001](http://localhost:3001)
- **API Documentation**: [http://localhost:3001/api/docs](http://localhost:3001/api/docs)
### Manual Installation
For more control over the installation:
#### Step 1: Clone the Repository
```bash
git clone https://github.com/subculture-collective/discord-spywatcher.git
cd discord-spywatcher
```
#### Step 2: Install Backend Dependencies
```bash
cd backend
npm install
```
#### Step 3: Install Frontend Dependencies
```bash
cd ../frontend
npm install
```
#### Step 4: Set Up Database
Install PostgreSQL and create a database:
```sql
CREATE DATABASE spywatcher;
CREATE USER spywatcher WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE spywatcher TO spywatcher;
```
#### Step 5: Configure Environment
Create `.env` files for backend and frontend:
**Backend** (`backend/.env`):
```bash
DATABASE_URL=postgresql://spywatcher:your_password@localhost:5432/spywatcher
REDIS_URL=redis://localhost:6379
DISCORD_BOT_TOKEN=your_bot_token
DISCORD_CLIENT_ID=your_client_id
DISCORD_CLIENT_SECRET=your_client_secret
JWT_SECRET=your_secure_jwt_secret
PORT=3001
```
**Frontend** (`frontend/.env`):
```bash
VITE_API_URL=http://localhost:3001
VITE_WS_URL=ws://localhost:3001
```
#### Step 6: Run Database Migrations
```bash
cd backend
npx prisma migrate deploy
npx prisma generate
```
#### Step 7: Start the Services
In separate terminals:
**Start the Discord Bot:**
```bash
cd backend
npm run dev
```
**Start the API Server:**
```bash
cd backend
npm run dev:api
```
**Start the Frontend:**
```bash
cd frontend
npm run dev
```
## Discord Bot Setup
### Step 1: Create Discord Application
1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click **New Application**
3. Name your application (e.g., "Spywatcher")
4. Click **Create**
### Step 2: Create Bot User
1. Navigate to the **Bot** section
2. Click **Add Bot**
3. Confirm by clicking **Yes, do it!**
4. Copy the **Bot Token** (you'll need this for `DISCORD_BOT_TOKEN`)
### Step 3: Configure Bot Permissions
Enable these **Privileged Gateway Intents**:
- ✅ Presence Intent
- ✅ Server Members Intent
- ✅ Message Content Intent
### Step 4: Configure OAuth2
1. Navigate to **OAuth2** > **General**
2. Add redirect URL: `http://localhost:5173/auth/callback`
3. For production, also add: `https://yourdomain.com/auth/callback`
### Step 5: Invite Bot to Server
1. Go to **OAuth2** > **URL Generator**
2. Select these **Scopes**:
- `bot`
- `applications.commands`
3. Select these **Bot Permissions**:
- Read Messages/View Channels
- Read Message History
- View Server Insights
4. Copy the generated URL and open it in your browser
5. Select your server and authorize
## Verification
After installation, verify everything is working:
### 1. Check Backend Health
```bash
curl http://localhost:3001/health
```
Expected response:
```json
{
"status": "ok",
"timestamp": "2024-11-03T16:00:00.000Z",
"uptime": 123.456,
"database": "connected",
"redis": "connected"
}
```
### 2. Check Frontend
Open [http://localhost:5173](http://localhost:5173) in your browser. You should see the Spywatcher login page.
### 3. Check Discord Bot
In your Discord server, verify the bot appears online and has the correct permissions.
## Next Steps
Now that Spywatcher is installed:
1. **[Quick Start Guide](./quick-start)** - Complete your first-time setup
2. **[Discord OAuth Setup](./oauth-setup)** - Connect your Discord account
3. **[Guild Selection](./guild-selection)** - Choose servers to monitor
## Troubleshooting
### Bot Not Connecting
- Verify `DISCORD_BOT_TOKEN` is correct
- Check that Privileged Gateway Intents are enabled
- Ensure the bot has been invited to your server
### Database Connection Failed
- Verify PostgreSQL is running: `pg_isready`
- Check `DATABASE_URL` is correct
- Ensure the database exists and user has permissions
### Frontend Can't Connect to Backend
- Verify backend is running on port 3001
- Check `VITE_API_URL` in frontend `.env`
- Ensure no firewall is blocking the connection
For more issues, see the [Troubleshooting Guide](./troubleshooting).

51
docs/guide/lurker-detection.md Normal file
View File

@@ -0,0 +1,51 @@
# Lurker Detection
Identify passive users who rarely engage with your Discord community.
## What is a Lurker?
A lurker is a user who:
- Is a member of the server
- Rarely or never sends messages
- May or may not be online frequently
- Passively consumes content without participating
## Lurker vs Ghost
| Characteristic | Lurker | Ghost |
|----------------|--------|-------|
| **Online Presence** | Variable | High |
| **Message Activity** | Very Low | Very Low |
| **Primary Metric** | Message count | Presence/Message ratio |
## Detection Algorithm
Lurkers are identified based on:
1. Low message count over time period
2. Account age (excludes new members)
3. Server join date
4. Reaction activity (optional)
## Using Lurker Detection
1. Navigate to **Lurker Detection**
2. Set detection parameters
3. Run scan
4. Review results
## Legitimate Lurkers
Not all lurkers are problematic:
- New members still getting comfortable
- Different timezone users
- Content consumers (readers vs writers)
- Voice-only participants
::: tip
Consider server culture when interpreting lurker data. Some communities naturally have more passive members.
:::
## Related
- [Ghost Detection](./ghost-detection)
- [Suspicion Scores](./suspicion-scores)

50
docs/guide/oauth-setup.md Normal file
View File

@@ -0,0 +1,50 @@
# Discord OAuth Setup
Learn how to connect your Discord account to Spywatcher for secure authentication.
## What is Discord OAuth?
OAuth2 is Discord's secure authentication protocol that allows Spywatcher to verify your identity without accessing your password.
## Setup Steps
### 1. Click "Sign in with Discord"
On the Spywatcher login page, click the Discord sign-in button.
### 2. Review Permissions
Discord will show the permissions Spywatcher requests:
- View your Discord profile
- View your server memberships
- Access basic account information
### 3. Authorize
Click "Authorize" to grant permissions.
### 4. Redirected
You'll be redirected back to Spywatcher, now logged in.
## Troubleshooting
### Authorization Failed
- Ensure you're logged into Discord
- Check browser popup blockers
- Try a different browser
- Clear cookies and try again
### Permissions Denied
If you denied permissions, you'll need to re-authorize the application.
::: tip Security
Spywatcher never sees or stores your Discord password. OAuth2 provides secure, token-based authentication.
:::
## Related
- [Installation Guide](./installation)
- [Quick Start](./quick-start)

73
docs/guide/plugins.md Normal file
View File

@@ -0,0 +1,73 @@
# Plugin System
Extend Spywatcher functionality with custom plugins.
## Overview
The plugin system allows you to add custom features and integrations to Spywatcher without modifying core code.
## Available Plugins
Browse plugins in the plugin directory:
- Analytics extensions
- Custom detections
- Integration plugins
- Automation tools
## Installing Plugins
1. Navigate to **Settings** > **Plugins**
2. Browse available plugins
3. Click "Install" on desired plugin
4. Configure plugin settings
5. Enable plugin
## Creating Plugins
### Plugin Structure
```typescript
// plugin.ts
export default {
name: 'my-plugin',
version: '1.0.0',
description: 'Custom plugin description',
async initialize(context) {
// Plugin initialization
},
async execute(data) {
// Plugin logic
}
};
```
### Plugin API
Plugins have access to:
- Database queries
- Analytics data
- User information
- Event hooks
- API endpoints
## Plugin Development
See the [Plugin Development Guide](/docs/PLUGIN_SYSTEM.md) for detailed information on creating custom plugins.
## Security
- Plugins run in sandboxed environment
- Limited API access
- Permission system
- Code review for published plugins
## Related
- [Developer Guide](/developer/)
- [Plugin System Documentation](/docs/PLUGIN_SYSTEM.md)
::: warning
Only install plugins from trusted sources. Plugins have access to server data.
:::

142
docs/guide/privacy.md Normal file
View File

@@ -0,0 +1,142 @@
# Privacy Controls
Manage privacy settings and data collection in Spywatcher.
## Privacy Philosophy
Spywatcher respects user privacy while providing valuable analytics:
- Minimal data collection
- User consent
- Data anonymization options
- Clear retention policies
## Privacy Settings
### User Privacy
Individual users can:
- Opt out of tracking
- Request data deletion
- Export their data
- View what's collected
### Admin Privacy
Administrators can configure:
- What data to collect
- How long to retain data
- Who can access analytics
- Data anonymization rules
## Data Collection
### What We Collect
By default, Spywatcher collects:
- Presence events (online/offline)
- Message counts (not content)
- User roles
- Timestamps
### Optional Collection
With consent:
- Message content (for content analysis)
- Voice channel activity
- Detailed presence data
### What We Don't Collect
Spywatcher never collects:
- Passwords
- Private messages content (unless explicitly enabled)
- Payment information
- Personal identification documents
## Data Retention
### Retention Periods
- **Active data**: 90 days
- **Analytics aggregates**: 1 year
- **Audit logs**: 2 years
- **Deleted user data**: Purged immediately
### Configuring Retention
Administrators can configure:
```bash
# Environment variables
DATA_RETENTION_DAYS=90
AUDIT_LOG_RETENTION_DAYS=730
```
## Data Access
### Who Can Access Data
- **Server Admins**: Full access to their server data
- **Moderators**: Limited access based on permissions
- **Users**: Access to their own data only
### Access Logs
All data access is logged:
- Who accessed data
- What data was accessed
- When access occurred
- Why access was requested (if provided)
## GDPR Compliance
Spywatcher supports GDPR requirements:
- Right to access
- Right to deletion
- Right to portability
- Right to correction
- Data processing agreements
## User Rights
### Request Your Data
Users can request:
1. All collected data
2. Data export (JSON/CSV)
3. Data deletion
4. Correction of inaccurate data
### Opt-Out
To opt out of tracking:
1. Navigate to Privacy Settings
2. Enable "Opt Out of Tracking"
3. Confirm decision
Note: Opting out may limit some features.
## Data Security
### Encryption
- Data encrypted at rest
- TLS for data in transit
- Encrypted backups
- Secure key management
### Access Control
- Role-based access control
- Two-factor authentication
- Session management
- Audit logging
## Related
- [Security Guide](../admin/security)
- [Admin Guide](../admin/)
- [FAQ](./faq)
::: tip
Regular privacy audits help ensure compliance and build user trust.
:::

251
docs/guide/quick-start.md Normal file
View File

@@ -0,0 +1,251 @@
# Quick Start
Get up and running with Spywatcher in under 10 minutes!
## Prerequisites
Before starting, make sure you have:
- ✅ Spywatcher installed ([Installation Guide](./installation))
- ✅ A Discord bot created and added to your server
- ✅ Backend and frontend services running
## Step 1: Access the Dashboard
Open your browser and navigate to:
```
http://localhost:5173
```
You'll see the Spywatcher login page.
## Step 2: Sign In with Discord
1. Click the **"Sign in with Discord"** button
2. Authorize Spywatcher to access your Discord account
3. Review the requested permissions:
- View your Discord profile
- View your server memberships
- Access basic account information
4. Click **"Authorize"**
::: tip First-time Authorization
The first time you sign in, Discord will ask you to authorize the application. This is a one-time setup.
:::
## Step 3: Select Your Server
After authentication, you'll see the **Guild Selection** page:
1. View all Discord servers where the Spywatcher bot is present
2. Click **"Select"** on the server you want to monitor
3. Confirm your selection
::: info Multiple Servers
You can monitor multiple servers. Switch between them using the server selector in the navigation bar.
:::
## Step 4: Explore the Dashboard
You'll land on the main dashboard showing:
### Overview Cards
- **Total Users**: Number of members in the server
- **Active Users**: Users active in the last 24 hours
- **Ghost Users**: Users with high presence but low participation
- **Lurkers**: Users who rarely engage
### Recent Activity
- Real-time feed of user presence changes
- Message activity trends
- Behavioral alerts
### Quick Actions
- View detailed analytics
- Check ghost detection results
- Review suspicion scores
- Access heatmaps
## Step 5: Run Your First Detection
### Ghost Detection
1. Click **"Ghost Detection"** in the sidebar
2. Set your parameters:
- **Minimum Presence Count**: 50 (default)
- **Maximum Message Count**: 10 (default)
3. Click **"Run Detection"**
4. Review the results:
- Users sorted by "ghost score"
- Higher scores = more "ghostly" behavior
- Click any user for detailed analysis
### Suspicion Scoring
1. Navigate to **"Suspicion Scores"**
2. View automatically calculated scores
3. Scores are based on:
- Presence patterns
- Message frequency
- Multi-client usage
- Behavioral anomalies
4. Click **"Details"** on any user to investigate
## Step 6: Configure Filters
Customize what you see:
1. Click the **Filter** icon in any view
2. Set filter criteria:
- **Date Range**: Last 7 days, 30 days, or custom
- **Minimum Activity**: Filter by activity threshold
- **Role Filter**: Show specific roles only
- **Status Filter**: Online, offline, or both
3. Click **"Apply Filters"**
4. Save filters as presets for quick access
## Step 7: Enable Real-time Updates
Stay synchronized with live Discord activity:
1. Look for the **WebSocket status** indicator (top-right)
2. When connected, you'll see: 🟢 **Live**
3. Real-time updates include:
- Presence changes
- New messages
- User joins/leaves
- Status updates
::: warning Connection Issues
If the WebSocket disconnects, the dashboard will attempt to reconnect automatically. Check your network connection if issues persist.
:::
## Step 8: Set Up Alerts (Optional)
Configure notifications for important events:
1. Go to **Settings** > **Alerts**
2. Enable alert types:
- High suspicion score detected
- New ghost user identified
- Unusual multi-client activity
- Mass user join/leave events
3. Choose notification method:
- Browser notifications
- Discord webhook
- Email (if configured)
4. Save your preferences
## Common First Tasks
### View Server Analytics
```
Dashboard → Analytics → Select Time Range
```
See comprehensive metrics about your server activity.
### Check Heatmap
```
Dashboard → Heatmap → Configure View
```
Visualize activity patterns across time periods and channels.
### Review Timeline
```
Dashboard → Timeline → Select User
```
Track individual user behavior over time.
### Export Data
```
Any View → Export Button → Choose Format (CSV/JSON)
```
Download data for external analysis.
## Navigation Tips
### Sidebar Navigation
- **Dashboard**: Main overview
- **Analytics**: Detailed metrics
- **Ghost Detection**: Find silent users
- **Lurkers**: Identify passive users
- **Suspicion Scores**: Behavior analysis
- **Heatmap**: Activity visualization
- **Timeline**: User history
- **Settings**: Configuration
### Keyboard Shortcuts
- `Ctrl/Cmd + K`: Quick search
- `Ctrl/Cmd + /`: Show keyboard shortcuts
- `Ctrl/Cmd + B`: Toggle sidebar
- `G then D`: Go to Dashboard
- `G then A`: Go to Analytics
- `G then H`: Go to Heatmap
### Quick Search
Press `Ctrl/Cmd + K` to open quick search:
- Search for users by username or ID
- Jump to any page quickly
- Search help documentation
- Access recent views
## Best Practices
### 1. Start with Default Settings
Don't customize too much initially. Use default detection thresholds to understand typical behavior first.
### 2. Review Weekly
Check ghost detection and suspicion scores weekly to identify trends and patterns.
### 3. Use Filters Strategically
Create filter presets for common views:
- "High Activity Members"
- "Recently Joined"
- "Moderator Activity"
### 4. Monitor Heatmaps
Weekly heatmap review helps identify:
- Peak activity times
- Inactive periods
- Channel usage patterns
### 5. Investigate Before Acting
High suspicion scores don't always mean malicious behavior. Always investigate before taking action.
## What's Next?
Now that you're familiar with the basics:
1. **[Dashboard Overview](./dashboard)** - Learn about all dashboard features
2. **[Ghost Detection](./ghost-detection)** - Deep dive into ghost detection
3. **[Analytics](./analytics)** - Understand all available metrics
4. **[Suspicion Scores](./suspicion-scores)** - Learn the scoring algorithm
## Need Help?
- **[Troubleshooting Guide](./troubleshooting)** - Solve common issues
- **[FAQ](./faq)** - Frequently asked questions
- **[GitHub Issues](https://github.com/subculture-collective/discord-spywatcher/issues)** - Report bugs
Happy monitoring! 🔍

129
docs/guide/suspicion-scores.md Normal file
View File

@@ -0,0 +1,129 @@
# Suspicion Scores
Understand how Spywatcher calculates behavioral suspicion scores.
## What are Suspicion Scores?
Suspicion scores are automated ratings (0-100) that indicate potentially unusual or suspicious user behavior.
## Score Calculation
Scores are based on multiple factors:
### Presence Patterns (30%)
- Unusual online hours
- Constant availability
- Sudden pattern changes
### Message Activity (25%)
- Message frequency
- Content patterns
- Spam indicators
### Multi-client Usage (20%)
- Simultaneous device usage
- Client switching patterns
- Abnormal client combinations
### Account Characteristics (15%)
- Account age
- Join date
- Username patterns
### Behavioral Changes (10%)
- Sudden activity spikes
- Pattern shifts
- Role changes
## Score Ranges
| Score | Classification | Action |
|-------|---------------|---------|
| **80-100** | 🔴 High Risk | Immediate investigation |
| **60-79** | 🟠 Medium Risk | Monitor closely |
| **40-59** | 🟡 Low Risk | Occasional review |
| **0-39** | ✅ Normal | No action needed |
## Interpreting Scores
### High Scores (80-100)
**Possible Causes:**
- Bot or automated account
- Account compromise
- Coordinated behavior
- Malicious intent
**Recommended Actions:**
- Investigate immediately
- Review timeline
- Check correlations with other users
- Consider temporary restrictions
### Medium Scores (60-79)
**Possible Causes:**
- Unusual but not necessarily malicious
- Legitimate power users
- Timezone differences
- Platform limitations
**Recommended Actions:**
- Monitor activity
- Note patterns
- Compare with historical data
- No immediate action
### Low Scores (40-59)
**Possible Causes:**
- Minor anomalies
- New users adjusting
- Occasional unusual behavior
**Recommended Actions:**
- Passive monitoring
- No intervention needed
## False Positives
Legitimate users may have high scores:
- Moderators with unusual hours
- International users
- Power users with unique patterns
- Voice-only participants
Always investigate before taking action.
## Using Suspicion Scores
### View Scores
Navigate to **Suspicion Scores** to see:
- User list sorted by score
- Score trends over time
- Contributing factors
### Set Alerts
Configure alerts for:
- Scores above threshold
- Sudden score increases
- Multiple high-score users
### Export Data
Export suspicion data for:
- Detailed analysis
- Reporting
- Historical tracking
## Related
- [Ghost Detection](./ghost-detection)
- [Lurker Detection](./lurker-detection)
- [Timeline Analysis](./timeline)
::: warning Important
Suspicion scores are indicators, not proof. Always investigate before taking moderation action.
:::

76
docs/guide/timeline.md Normal file
View File

@@ -0,0 +1,76 @@
# Timeline Analysis
Track and analyze user behavior over time with the timeline feature.
## Overview
The timeline view provides a chronological view of user activity, showing patterns and changes in behavior over time.
## Features
### User Timeline
View individual user activity:
- Presence events
- Message activity
- Status changes
- Role changes
- Multi-client usage
### Time Periods
Analyze activity across:
- Last 24 hours
- Last 7 days
- Last 30 days
- Custom date range
### Activity Types
Track different event types:
- **Online/Offline**: Presence changes
- **Messages**: Message activity spikes
- **Roles**: Role additions/removals
- **Clients**: Device switching patterns
## Using Timeline
1. Navigate to Timeline view
2. Search for a user or select from list
3. Choose time period
4. Apply filters (event types, channels)
5. Analyze patterns
## Timeline Visualization
The timeline displays events as:
- Interactive timeline chart
- Event markers for significant activities
- Hover tooltips with details
- Zoom and pan controls
## Pattern Detection
Identify patterns such as:
- Regular online hours
- Activity spikes
- Unusual behavior changes
- Coordinated activity
## Export
Export timeline data for:
- Detailed analysis
- Record keeping
- Reporting
- Evidence collection
## Related
- [Ghost Detection](./ghost-detection)
- [Suspicion Scores](./suspicion-scores)
- [Heatmap](./heatmap)
::: tip
Use timeline analysis to understand if unusual behavior is a one-time event or a pattern.
:::

176
docs/guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,176 @@
# Troubleshooting
Solutions to common issues with Spywatcher.
## Installation Issues
### Bot Won't Connect
**Symptoms:** Bot shows offline in Discord
**Solutions:**
1. Verify `DISCORD_BOT_TOKEN` is correct
2. Check Privileged Gateway Intents are enabled
3. Ensure bot is invited to server
4. Review backend logs for errors
### Database Connection Failed
**Symptoms:** Backend errors, can't start services
**Solutions:**
1. Verify PostgreSQL is running: `pg_isready`
2. Check `DATABASE_URL` format
3. Ensure database exists
4. Verify user has permissions
5. Check firewall rules
### Frontend Can't Connect
**Symptoms:** API errors in browser console
**Solutions:**
1. Verify backend is running on correct port
2. Check `VITE_API_URL` in frontend `.env`
3. Ensure no CORS issues
4. Check browser developer console for errors
## Authentication Issues
### OAuth Fails
**Symptoms:** Can't log in with Discord
**Solutions:**
1. Verify Discord OAuth2 credentials
2. Check redirect URI matches configuration
3. Clear browser cookies and cache
4. Try different browser
5. Check Discord OAuth2 settings
### Session Expired
**Symptoms:** Logged out unexpectedly
**Solutions:**
1. Re-authenticate with Discord
2. Check `JWT_SECRET` hasn't changed
3. Verify session timeout settings
## Data Issues
### No Data Showing
**Symptoms:** Empty dashboard, no analytics
**Solutions:**
1. Ensure bot has been running for some time
2. Check bot permissions in Discord
3. Verify Privileged Intents are enabled
4. Review database for data
5. Check time range filters
### Incorrect Ghost Scores
**Symptoms:** Unexpected or inaccurate scores
**Solutions:**
1. Verify detection thresholds
2. Check time range selection
3. Ensure sufficient data collected
4. Review bot tracking configuration
### Missing Users
**Symptoms:** Users not appearing in analytics
**Solutions:**
1. Check user privacy settings
2. Verify bot can see user
3. Check role visibility settings
4. Review bot permissions
## Performance Issues
### Slow Dashboard
**Symptoms:** Dashboard loads slowly
**Solutions:**
1. Check network connection
2. Reduce date range in filters
3. Limit number of results
4. Clear browser cache
5. Check backend resource usage
### WebSocket Disconnects
**Symptoms:** Real-time updates stop
**Solutions:**
1. Check network stability
2. Verify WebSocket URL
3. Check browser console for errors
4. Review backend WebSocket logs
## Error Messages
### 401 Unauthorized
**Cause:** Invalid or missing authentication
**Solution:** Log out and log back in
### 403 Forbidden
**Cause:** Insufficient permissions
**Solution:** Check Discord role permissions
### 404 Not Found
**Cause:** Resource doesn't exist
**Solution:** Verify guild ID, user ID, or endpoint
### 429 Too Many Requests
**Cause:** Rate limit exceeded
**Solution:** Wait and retry, or upgrade tier
### 500 Internal Server Error
**Cause:** Backend error
**Solution:** Check backend logs, report if persistent
## Getting Help
If issues persist:
1. **Check Logs:**
- Backend: `docker-compose logs backend`
- Frontend: Browser developer console
- Bot: `docker-compose logs bot`
2. **GitHub Issues:**
- Search existing issues
- Create new issue with details
- Include logs and error messages
3. **Documentation:**
- Review relevant guides
- Check API documentation
- Read developer docs
## Common Questions
See the [FAQ](./faq) for answers to frequently asked questions.
::: tip Pro Tip
Enable debug logging for more detailed error information:
```bash
DEBUG=* npm run dev
```
:::

106
docs/index.md Normal file
View File

@@ -0,0 +1,106 @@
---
layout: home
hero:
name: Spywatcher
text: Discord Surveillance & Analytics
tagline: Comprehensive monitoring and analytics for Discord servers with powerful detection and visualization tools
actions:
- theme: brand
text: Get Started
link: /guide/
- theme: alt
text: API Reference
link: /api/
- theme: alt
text: View on GitHub
link: https://github.com/subculture-collective/discord-spywatcher
features:
- icon: 🔍
title: Ghost Detection
details: Identify users who are frequently present but rarely participate. Advanced algorithms detect lurkers and potential automated accounts.
- icon: 📊
title: Advanced Analytics
details: Comprehensive analytics with interactive dashboards, heatmaps, and timelines to understand server behavior patterns.
- icon: 🚨
title: Suspicion Scoring
details: Intelligent scoring system identifies unusual behavior patterns and potential security threats automatically.
- icon: 🔐
title: Secure & Private
details: Built with security first. Discord OAuth2 authentication, role-based access control, and privacy-focused analytics.
- icon: ⚡
title: Real-time Updates
details: WebSocket-powered real-time updates keep your dashboard synchronized with live Discord activity.
- icon: 🛠️
title: Extensible
details: Plugin system allows custom features and integrations. REST API and SDK for third-party applications.
- icon: 📈
title: Tier-based Quotas
details: Flexible subscription tiers (FREE, PRO, ENTERPRISE) with rate limiting and daily usage quotas.
- icon: 🌐
title: Public API
details: Comprehensive REST API with OpenAPI documentation, TypeScript/JavaScript SDK, and multi-language code examples.
- icon: 🐳
title: Docker Support
details: Easy deployment with Docker Compose for development and production environments.
---
## Quick Start
Get up and running in minutes:
```bash
# Clone the repository
git clone https://github.com/subculture-collective/discord-spywatcher.git
cd discord-spywatcher
# Copy environment configuration
cp .env.example .env
# Start with Docker
docker-compose -f docker-compose.dev.yml up
```
Visit [http://localhost:5173](http://localhost:5173) to access the dashboard.
## Tech Stack
- **Backend**: Node.js, Express, TypeScript, Prisma, PostgreSQL
- **Bot**: discord.js (presence + message tracking)
- **Frontend**: React + Vite + Tailwind CSS
- **Authentication**: Discord OAuth2 with JWT sessions
- **Caching**: Redis
- **Monitoring**: Prometheus, Grafana, Loki
## Documentation Sections
### 👥 [User Guide](/guide/)
Learn how to use Spywatcher's features, from basic setup to advanced analytics.
### 🔧 [Admin Guide](/admin/)
Administration, configuration, and operations for server administrators.
### 💻 [Developer Guide](/developer/)
Development setup, architecture, and contribution guidelines for developers.
### 📚 [API Reference](/api/)
Complete API documentation with examples in multiple languages.
## Community & Support
- **GitHub**: [subculture-collective/discord-spywatcher](https://github.com/subculture-collective/discord-spywatcher)
- **Issues**: [Report bugs or request features](https://github.com/subculture-collective/discord-spywatcher/issues)
- **Contributing**: [Read our contributing guide](/developer/contributing)
## License
Spywatcher is released under the [MIT License](https://github.com/subculture-collective/discord-spywatcher/blob/main/LICENSE).

26
docs/public/logo.svg Normal file
View File

@@ -0,0 +1,26 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
<!-- Background circle -->
<circle cx="50" cy="50" r="48" fill="#5865f2" stroke="#4752c4" stroke-width="2"/>
<!-- Eye shape (spy theme) -->
<ellipse cx="50" cy="50" rx="30" ry="20" fill="white"/>
<!-- Pupil -->
<circle cx="50" cy="50" r="12" fill="#1e1f22"/>
<!-- Inner pupil -->
<circle cx="50" cy="50" r="6" fill="#4752c4"/>
<!-- Light reflection -->
<circle cx="54" cy="46" r="3" fill="white" opacity="0.8"/>
<!-- Scanning lines (radar theme) -->
<line x1="50" y1="15" x2="50" y2="85" stroke="#4752c4" stroke-width="1" opacity="0.3"/>
<line x1="15" y1="50" x2="85" y2="50" stroke="#4752c4" stroke-width="1" opacity="0.3"/>
<!-- Corner accents -->
<path d="M 20,25 L 20,15 L 30,15" fill="none" stroke="#4752c4" stroke-width="2"/>
<path d="M 80,25 L 80,15 L 70,15" fill="none" stroke="#4752c4" stroke-width="2"/>
<path d="M 20,75 L 20,85 L 30,85" fill="none" stroke="#4752c4" stroke-width="2"/>
<path d="M 80,75 L 80,85 L 70,85" fill="none" stroke="#4752c4" stroke-width="2"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

8328
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

9
package.json
View File

@@ -12,7 +12,10 @@
"lint:fix": "npm run lint:fix --prefix backend && npm run lint:fix --prefix frontend",
"format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"",
"type-check": "npm run type-check --prefix backend && npm run type-check --prefix frontend"
"type-check": "npm run type-check --prefix backend && npm run type-check --prefix frontend",
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
"devDependencies": {
"@commitlint/cli": "^19.0.0",
@@ -20,7 +23,9 @@
"eslint": "^9.38.0",
"husky": "^9.0.0",
"lint-staged": "^15.0.0",
"prettier": "^3.6.2"
"prettier": "^3.6.2",
"vitepress": "^1.6.4",
"vue": "^3.5.22"
},
"lint-staged": {
"backend/**/*.ts": [