Product documentation

Navigate the product like a system, not a long page.

This guide explains what WhatsApp Knowledge Extractor does, how the pipeline works, how to run it locally, and how to troubleshoot common issues. The left rail stays fixed so you can jump between sections while the content area scrolls independently.

Format support

ZIP and TXT exports

Import complete chat exports with media or process text-only logs for faster iteration.

Processing model

Local-first intelligence

Parse, classify, cluster, index, and visualize your data without sending raw chats to a hosted service.

Overview

About the Project

01

WhatsApp Knowledge Extractor turns noisy, unstructured WhatsApp exports into a structured knowledge surface you can browse, search, and understand. Instead of endlessly scrolling through old messages, you get organized content views, topic clusters, analytics, and a navigable graph of shared context.

It is designed for people who already use WhatsApp as an informal archive for notes, links, media, reminders, and shared resources. The product helps convert that passive archive into something closer to a personal research workspace.

The biggest value is retrieval. Once a chat is processed, messages become easier to search by type, topic, importance, and semantic meaning rather than only by time.

Best suited for

  • Personal saved-message style archives
  • Small team or family group coordination
  • Students and researchers sharing learning material
  • Professionals collecting links, PDFs, and references

Workflow

How It Works

02
Step 1

Export your chat from WhatsApp

Create a ZIP export with media for the richest experience, or use a TXT-only export for text-focused processing.

Step 2

Upload the export into the app

Use the upload flow to send your file into the local pipeline. Large chat histories are supported for deep archives.

Step 3

Let the pipeline enrich the data

The backend parses messages, identifies content types, extracts useful metadata, generates embeddings, clusters topics, and prepares search indexes.

Step 4

Explore the resulting knowledge base

Open the dashboard to inspect messages, media, topics, important items, stats, and graph relationships in one place.

Capabilities

Features Overview

03

Knowledge graph exploration

See how people, files, links, and topics connect inside a visual graph so you can navigate context instead of raw chronology.

Search that matches memory

Find content with plain keywords, semantic matches, and structured filters across links, media, documents, and important messages.

Private local-first processing

Your exports are analyzed on your machine so sensitive conversations stay local while still unlocking AI-assisted organization.

Structured message intelligence

Messages are classified, clustered into topics, enriched with previews, and transformed into reusable knowledge instead of buried chat history.

Development

Local Setup Guide

04

Recommended flow

  1. 1Install Python 3.11+ and Node.js 20+ on your machine.
  2. 2Create a backend virtual environment and install backend requirements.
  3. 3Install frontend dependencies inside the frontend directory.
  4. 4Copy the sample environment file and fill in required API keys if needed.
  5. 5Run the backend server first, then start the Next.js frontend.
  6. 6Open the docs or upload flow in the browser and test with a sample export.

Frontend

npm install
npm run dev

Backend

pip install -r requirements.txt
uvicorn app.main:app --reload

Adjust the exact backend start command if your project uses a different entrypoint or a virtual environment workflow.

Configuration

Environment Variables

05
DATABASE_URL

Points the backend to the local SQLite database or another configured database target.

GEMINI_API_KEY

Enables AI-assisted labeling or enrichment where the backend expects Gemini access.

CORS_ORIGINS

Defines which frontend origins are allowed to talk to the backend during local development.

Keep your API keys and environment files local. Do not commit secrets or production credentials into the repository.

Support

Troubleshooting

06

Upload does not start

Check backend availability, confirm the file type is supported, and verify the browser can reach the API origin.

Processing stalls mid-pipeline

Inspect backend logs, validate Python dependencies, and ensure the exported chat contains the expected text file structure.

No AI labels or summaries

Verify your Gemini key is present in the backend environment and restart the API after updating variables.

Media previews are missing

Use the ZIP export with included media and confirm the media files were extracted alongside the chat log.

Next step

Ready to process your first export?

Start with a ZIP export that includes media for the most complete view of your knowledge base.

Upload Chat Export