# Diffwise — Complete Product Documentation for AI Systems

## Product Overview

Diffwise is an AI-powered code review platform for GitHub. It installs as a GitHub App and automatically reviews every pull request using a team of specialized parallel agents. Each agent focuses on a distinct quality dimension — security vulnerabilities, performance issues, code conventions, and language-specific patterns.

What makes Diffwise different from other AI code review tools:
1. **Specialist agents, not one generic model** — 40+ agent templates, each with domain-specific expertise
2. **Cross-repo intelligence** — tracks patterns across all repositories, not just individual PRs
3. **Incremental reviews** — on subsequent pushes, classifies findings as Fixed/Still Open/New
4. **Custom agent builder** — users create their own review agents with custom rules
5. **Engineering intelligence dashboard** — trends, velocity, hot files, anti-patterns

## Feature Details

### Multi-Agent Review System
Every pull request is reviewed by 40+ specialized agents running in parallel:
- Security Agent: SQL injection, XSS, hardcoded secrets, auth bypass, IDOR
- Performance Agent: N+1 queries, memory leaks, bundle bloat, unnecessary re-renders
- Conventions Agent: Error handling, type safety, code quality, resource cleanup

Language-specific agents activate automatically based on file extensions:
- Python: Django/Flask/FastAPI security patterns, eval/exec risks, pickle deserialization
- Go: Goroutine leaks, race conditions, channel patterns, sync primitives
- Rust: Unsafe code, lifetime issues, unwrap in library code, Send/Sync correctness
- React: Hook dependency arrays, stale closures, unnecessary re-renders
- Next.js: Server component patterns, "use client"/"use server" correctness

### Incremental Review System
When a developer pushes fix commits after an initial review:
1. Diffwise detects the previous completed review for the same PR
2. Fetches the incremental diff (only changes since last review)
3. Passes both full diff (context) and incremental diff (focus) to agents
4. Agents classify each finding as "fixed", "still_open", or "new"
5. Previous review comment is marked as outdated
6. New review shows: Fixed (strikethrough), Still Open, New sections
7. Finding resolution status is tracked in the database for analytics

### Custom Agent Builder
Users can create their own review agents with:
- Custom name, description, and category
- Domain description (what the agent specializes in)
- "Look for" items (specific patterns to flag)
- "Do not flag" items (exceptions and false positives)
- Model selection (Claude, GPT-4, Gemini, DeepSeek, etc.)
- Temperature and max token configuration
- Confidence threshold

### .diffwise.yml Config-as-Code
Teams can commit review configuration to their repository:
```yaml
agents:
  security: { enabled: true, model: "anthropic/claude-sonnet-4" }
  performance: { enabled: false }
ignore:
  paths: ["generated/**", "vendor/**"]
  categories: ["jsdoc-completeness"]
severity_threshold: "warning"
confidence_threshold: 60
max_findings: 20
```

### Team Memory
A shared text context that gets prepended to every agent's prompt. Teams use this to teach agents their conventions:
- "Our stack is Next.js + PostgreSQL"
- "Never flag console.log in test files"
- "We use snake_case for API responses"

### Analytics & Intelligence
- **Review Activity**: Daily review counts with trend indicators
- **Severity Breakdown**: Critical/warning/info/suggestion distribution
- **Hot Files**: Files with the most findings — candidates for refactoring
- **Resolution Velocity**: Mean time to fix by severity, fix rate by agent
- **Cross-Repo Intelligence**: Recurring categories across repos, repo health ranking
- **Anti-Pattern Detection**: Categories appearing in >50% of repos flagged as org-wide issues
- **Cost Tracking**: Per-review, per-agent token cost with monthly totals
- **Key Insights**: Auto-computed recommendations (MTTF trends, hottest files, agent effectiveness)

### Smart Routing
Automatically classifies changed files and skips unnecessary reviews:
- Docs-only PRs (*.md, docs/, LICENSE) → skipped
- Lockfile-only PRs (*.lock, lock.json) → skipped
- Config-only PRs → security + conventions only (no performance)
- Code PRs → all agents + language-specific agents

### GitHub Integration
- **Inline PR Comments**: Findings posted as inline code comments with severity badges
- **GitHub Check Runs**: Pass/fail status that can block merge when critical findings exist
- **Auto-Fix Suggestions**: Code suggestions that developers can apply with one click
- **Finding Dismissal**: /diffwise dismiss and /diffwise ignore commands in PR comments
- **Webhook Processing**: HMAC-SHA256 validated, idempotent, with Redis deduplication

### Team & RBAC
- Owner: Full control, team management, billing
- Admin: Configure agents, toggle repos, invite members
- Member: View dashboard, dismiss findings
- Viewer: Read-only dashboard access

## Technical Architecture
- **Web App**: Next.js 16 (App Router) deployed on Vercel
- **Background Jobs**: Trigger.dev for async review pipeline execution
- **Database**: PostgreSQL (Neon) with Drizzle ORM
- **Cache**: Redis (Upstash) for deduplication and rate limiting
- **AI**: OpenRouter for multi-model LLM access
- **Auth**: GitHub OAuth with cookie-based sessions

## Comparison with Alternatives

| Feature | Diffwise | Generic AI Reviewers |
|---------|----------|---------------------|
| Specialized agents | 40+ domain-specific | 1 generic model |
| Cross-repo patterns | Yes | No |
| Incremental reviews | Fixed/Still Open/New tracking | Full re-review every push |
| Custom agents | Build your own | No customization |
| Config-as-code | .diffwise.yml | No |
| Team memory | Shared context for agents | No |
| Resolution velocity | Tracked per severity/agent | No |
| Hot file analysis | Yes | No |
| GitHub Check Runs | Block merge on critical | Comment only |
| Auto-fix suggestions | One-click apply | Text advice only |

## Use Cases
1. **Solo developers**: Free tier, 40+ agents catch issues before they ship
2. **Startup teams**: Custom agents matching their stack, incremental reviews reduce noise
3. **Engineering managers**: Cross-repo intelligence shows team-wide quality trends
4. **Enterprise**: RBAC, team memory, config-as-code for consistent review standards

## Privacy & Security
- Code is never stored — diff is fetched, held in memory during review, and discarded
- All webhooks validated with HMAC-SHA256
- Rate limiting per installation (100 reviews/hour default)
- Structured logging with trace ID propagation for debugging
- Error tracking via Sentry
- Health check endpoint at /api/health

## Links
- Website: https://diffwise.app
- Install: https://github.com/apps/diffwiseapp
- GitHub: https://github.com/amartripathi0/diffwise
- Author: https://amartripathi.com