---
## What is Rereflect?
Rereflect ingests customer feedback from CSV, email, webhooks, Slack, Intercom and
Zendesk, syncs with issue trackers like Linear, Jira and Asana, then uses NLP and
(optionally) an LLM to classify sentiment, surface pain points and feature requests,
flag urgent churn risks, and route everything through a team workflow — all behind a
multi-tenant dashboard you host yourself.
- 🔓 **100% open source (MIT).** No "open core", no locked features.
- 🏠 **Self-hosted — your data never leaves your box.** Ships with Docker Compose.
- 🛰️ **Zero telemetry.** No usage analytics, no crash reporting, no phone-home. A default
install makes no outbound calls of its own — only the LLM/integration endpoints you
configure yourself. See [Telemetry](docs/SELF_HOSTING.md#telemetry-there-isnt-any).
- 🔑 **Bring your own LLM key.** OpenAI, Anthropic or Google, encrypted at rest. There is no vendor key and nothing is proxied.
- 💸 **Free by default.** Runs end-to-end on a local VADER + keyword pipeline with **no API key and zero cost**. Add a key only when you want LLM-grade analysis.
- ✅ **Everything unlocked.** No tiers, seat caps, or feedback quotas — advanced churn, cohorts, analytics, integrations and the API are all included.
## Highlights
| | |
|---|---|
| 🧠 **AI feedback analysis** | Sentiment, pain points, feature requests, urgency and topic clustering — local (VADER default) or LLM-powered (BYOK). Optional **opt-in local transformer sentiment model** (CPU, offline, per-org) with a built-in accuracy card that compares it against VADER on a labeled set — honest numbers, off by default. **Per-org self-improving classifiers** — separate sentiment, category and urgency heads train on your own corrections and auto-promote only when measurably better (≥ +0.02 macro-F1), fully reversible. The urgency head is add-only in auto (it can escalate to urgent, never silently clears the flag). |
| 💬 **AI Copilot (Cmd+K)** | Ask questions in natural language, generate reports and draft responses — including **recurring scheduled reports with optional email delivery** (BYO-key Resend). When an answer returns a customer list, the copilot can also propose **one concrete action** — tagging those customers — and execute it on your confirmation (admins/owners only; the cohort is the result set you saw, capped at 200; proposals are derived server-side from the result shape, so they work identically on a keyless local model). Runs **fully offline on a local model** (Ollama or any OpenAI-compatible endpoint) — including the template-matching embeddings — or on your BYOK cloud key. |
| 📉 **Churn risk scoring** | Per-item churn risk with suggested actions, plus cohort analytics and playbooks. **Churn-triggered playbooks can now reach the customer**: `send_email` playbook steps and bulk outreach campaigns on `/customers` (template or AI-drafted content, sent via your own Resend key), with a per-customer opt-out + tokenized unsubscribe honored on every send path and a shared per-recipient cooldown so no one gets emailed twice. An **automation rule** can send the same emails (`send_customer_email`) when churn risk, health score or usage crosses a line — shadow mode first, and every send is audited per rule. Optional **CRM-sourced churn label suggestions** — if you've connected HubSpot or Salesforce, Rereflect can read lost renewals and propose them as churn labels. **Off by default and default-deny** (nothing is suggested until you name your renewal pipelines), and every suggestion is **confirmed by a human** in a review queue before it becomes a label — a lost renewal is not always a churn. Includes an optional on-demand backfill over your closed-lost history. A second, **CRM-free** source does the same from **sustained product-usage decline** (opt-in, shadow mode first) — same review queue, same human-confirm rule; a usage drop is not always churn either. |
| 🧑💼 **Customer 360 + timeline** | Per-customer health profile with a unified, paginated activity timeline (feedback, product usage, churn and health-score events); CRM enrichment (HubSpot, Salesforce) with optional health-score writeback to both HubSpot and Salesforce — also readable over the public API. |
| 🗂️ **Team workflow** | Kanban board, statuses, auto-assignment rules and round-robin routing. |
| 🔌 **Sources & integrations** | **Inbound:** CSV import, email, webhooks and Slack, plus support desks (Intercom, Zendesk). **Issue trackers:** Jira, Linear and Asana. **CRM:** HubSpot and Salesforce. **Outbound:** alerts and digests via Slack, Discord and Teams, and customer outreach via email (BYO-key Resend, opt-out honored). |
| 📊 **Trends over time & sharing** | Not just a snapshot: `/analytics` plots **average sentiment, volume, urgent count, pain points and feature requests over 7/30/90 days** (daily or weekly buckets), and each top pain point and feature request carries an ↑/↓/→ arrow so you can see which themes are actually **accelerating** rather than just loud. Plus source breakdown, saved views, CSV export, PDF export and read-only share links. |
| 👥 **Multi-tenant + RBAC** | Organization isolation with Owner / Admin / Member roles. |
## 🚀 Quick Start
The fastest path is Docker Compose — it brings up Postgres, Redis, the backend, the
Celery worker and the frontend together.
```bash
git clone https://github.com/haqaliz/rereflect.git
cd rereflect
# 1. Copy the env template and fill in the required secrets
cp .env.prod.example .env
# 2. Generate the two required secrets and paste them into .env
python -c "import secrets; print('JWT_SECRET=' + secrets.token_urlsafe(48))"
python -c "from cryptography.fernet import Fernet; print('LLM_ENCRYPTION_KEY=' + Fernet.generate_key().decode())"
# 3. Build and start everything
docker compose -f docker-compose.prod.yml up -d --build
```
Open **http://localhost:3000** and sign in with the `ADMIN_EMAIL` / `ADMIN_PASSWORD`
you set in `.env` (the first admin is seeded on startup). The API and interactive
docs live at **http://localhost:8000/docs**.
> Out of the box (`ai_analysis_enabled=false`, no LLM key) Rereflect runs the **free
> local pipeline** — sentiment, pain points, feature requests and heuristic churn all
> work with no external API and no cost. Point **Settings → AI** at a local model
> (Ollama or any OpenAI-compatible endpoint) and even the **AI Copilot runs fully
> offline** — its template-matching embeddings and answer generation both use your
> local provider, no OpenAI key required. Add a cloud BYOK key instead whenever you
> want a stronger hosted model.
👉 Full deployment guide, env reference and BYOK setup: **[docs/SELF_HOSTING.md](docs/SELF_HOSTING.md)**.
Developing locally instead of via Docker? See **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.
## Screenshots
### Dashboard & analytics
Real-time KPIs, NPS, sentiment distribution and trend analytics — with exportable,
shareable views.
### AI analysis: pain points, feature requests & urgent flags
Every feedback item is automatically categorized, tagged and prioritized.
More screenshots — workflow, sources, integrations & settings
| Workflow board | Feedback sources |
|---|---|
|  |  |
| **Integrations** | **AI (bring your own key)** |
|  |  |
| **Auto-assignment rules** | **Notifications & digests** |
|  |  |
| **Team & roles** | **Shared links** |
|  |  |
## Architecture
```
┌─────────────────┐
│ frontend-web │ Next.js 16 + TypeScript + TailwindCSS
└────────┬────────┘
│ REST API
▼
┌─────────────────┐
│ backend-api │ FastAPI + PostgreSQL + SQLAlchemy
└────────┬────────┘
│
┌────┴────┐
▼ ▼
┌────────┐ ┌────────────┐
│analysis│ │ worker- │ Celery + Redis
│-engine │ │ service │
└────────┘ └────────────┘
```
A Next.js frontend talks to a FastAPI backend; long-running analysis runs on a Celery
worker (Redis broker) using the analysis engine (VADER / scikit-learn / BERTopic, or an
LLM when a key is configured). Full breakdown, tech stack, project layout and the RBAC
model are in **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
## Documentation
| Guide | What's inside |
|-------|---------------|
| **[Self-Hosting](docs/SELF_HOSTING.md)** | Docker Compose deployment, full env reference, BYOK, TLS and the $0 local mode |
| **[Development](docs/DEVELOPMENT.md)** | Local setup, the pnpm + Python toolchain, package management, common commands, troubleshooting |
| **[API Reference](docs/API.md)** | REST endpoints, auth, pagination and filtering (live Swagger at `/docs`) |
| **[Architecture](docs/ARCHITECTURE.md)** | Services, tech stack, project structure and RBAC |
| **[Contributing](CONTRIBUTING.md)** | Dev workflow, testing and PR conventions |
## Tech stack
- **Frontend** — Next.js 16 · TypeScript 5.9 · TailwindCSS 3.4 · shadcn/ui · Recharts
- **Backend** — FastAPI 0.115 · SQLAlchemy 2.0 · Alembic · PostgreSQL · JWT
- **Async** — Celery 5.3 · Redis
- **AI/ML** — VADER · scikit-learn · BERTopic · OpenAI / Anthropic / Google (BYOK)
## Contributing
Contributions are welcome — bug reports, features, docs and tests. See
**[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup, testing and PR conventions.
## Support the project
Rereflect is free and open source. If it's useful to you, you can chip in with a crypto donation:
## License
Released under the **[MIT License](LICENSE)**. Third-party attributions are in
**[NOTICE](NOTICE)**.
Rereflect is free and open source. Self-host it, hack on it, make it yours.
If it's useful to you, consider leaving a ⭐ — it helps others find the project.
