Upload PDFs, Word docs, PowerPoints, spreadsheets, or any webpage — then ask questions in natural language. DocTalk returns AI-generated answers with numbered citations ([1], [2]) that link directly to the source text. Click a citation and the original passage highlights on the page.
Why DocTalk?
- Cited answers with page highlighting — Every answer references exact passages. Click a citation to jump to the page with the text highlighted.
- Multi-format support — PDF, DOCX, PPTX, XLSX, TXT, Markdown, and URL import. Tables, slides, and spreadsheets are all fully supported.
- 2 AI performance modes — Flash for fast cited answers and Pro for deeper analysis, powered by DeepSeek V4.
- 11 languages — Full UI and AI responses in English, Chinese, Spanish, Japanese, German, French, Korean, Portuguese, Italian, Arabic, and Hindi.
- Layout-preserving PDF translation — Translate text-heavy PDFs into a new PDF, preview it beside the original, and optionally add the translated PDF as a new DocTalk document. Free includes 2 trials; Plus/Pro unlock ongoing use.
- Split-view reader — Resizable chat panel alongside a PDF viewer with zoom, search, and drag-to-pan.
- Document collections — Group documents together and ask cross-document questions with source attribution.
- Auto-summary — AI generates a document summary and suggested questions after upload.
- Privacy-first — GDPR data export, cookie consent, encryption at rest, SSRF protection, non-root containers.
Tech Stack
| Layer | Technology |
|---|
| Frontend | Next.js 14 (App Router), Auth.js v5, react-pdf v9, Tailwind CSS, Radix UI, Zustand |
| Backend | FastAPI, Celery, Redis |
| Database | PostgreSQL 17, Qdrant (vector search) |
| Storage | Cloudflare R2 (S3-compatible; MinIO locally) |
| Auth | Auth.js v5 — Google OAuth, Microsoft OAuth, Email Magic Link |
| Payments | Stripe Checkout + Subscriptions |
| AI | DeepSeek V4 Flash/Pro for chat; OpenRouter for embeddings and fallback models |
| Parsing | Azure AI Document Intelligence, PyMuPDF, Tesseract OCR, python-docx, python-pptx, openpyxl, LibreOffice |
| PDF translation | RetainPDF sidecar, DeepSeek translation, Paddle/MinerU/Datalab OCR providers |
| Monitoring | Sentry, Vercel Analytics |
Architecture
Browser ──→ Vercel (Next.js) ──→ Railway (FastAPI) ──→ PostgreSQL
│ │ Qdrant
│ │ Redis
└── API Proxy ──────────┘ Cloudflare R2
(JWT injection)
How it works: The reader is chat-native: users ask in natural language, and
an action planner decides whether the request should use ordinary cited RAG,
whole-document summary context, structured extraction, table scan/export,
template guidance, document comparison clarification, or citation lookup.
Documents are still chunked with bounding-box coordinates and embedded into
Qdrant for local questions, but async work products return as artifact cards in
the same chat instead of separate workspace tabs. Citations map back to exact
page locations for real-time highlighting.
Parsing now also writes canonical document elements for headings, paragraphs,
and detected tables. Chunk RAG remains the citation anchor and local Q&A path,
while summaries, structured extraction, table questions, and semantic diff use
element-aware coverage before falling back to chunk retrieval.
For PDF tables, production can use Azure AI Document Intelligence
prebuilt-layout to extract table cells, headers, merged-cell spans, and layout
regions before falling back to PyMuPDF. This keeps table export and table-aware
RAG grounded in table objects rather than ad hoc chunk reconstruction.
For detailed diagrams see docs/ARCHITECTURE.md.
Quick Start
Prerequisites
Setup
# 1. Clone and configure
git clone https://github.com/Rswcf/DocTalk.git
cd DocTalk
cp .env.example .env # Edit with your keys
# 2. Start infrastructure
docker compose up -d # PostgreSQL, Qdrant, Redis, MinIO
# 3. Backend
cd backend
pip install -r requirements.txt
python3 -m alembic upgrade head
python3 -m uvicorn app.main:app --reload
# 4. Celery worker (separate terminal)
cd backend
OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES python3 -m celery \
-A app.workers.celery_app worker --loglevel=info -Q default,parse
# 5. Frontend (separate terminal)
cd frontend
npm install && npm run dev
Open http://localhost:3000.
OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES is only required on macOS.
Backend (.env)
| Variable | Required | Description |
|---|
DATABASE_URL | Yes | PostgreSQL connection string (postgresql+asyncpg://...) |
OPENROUTER_API_KEY | Yes | OpenRouter API key |
AUTH_SECRET | Yes | Random secret (shared with frontend) |
ADAPTER_SECRET | Yes | Secret for internal auth API |
STRIPE_SECRET_KEY | No | Stripe secret key |
STRIPE_WEBHOOK_SECRET | No | Stripe webhook signing secret |
SENTRY_DSN | No | Sentry DSN for error tracking |
OCR_ENABLED | No | Enable OCR for scanned PDFs (default: true) |
OCR_LANGUAGES | No | Installed Tesseract languages; the parser auto-selects a narrow subset per document by detected script (default: eng+chi_sim+jpn+kor+spa+deu+fra+por+ita+ara+hin+urd) |
FREE_LAYOUT_TRANSLATIONS_LIMIT | No | Free-plan lifetime trial count for layout-preserving PDF translation (default: 2) |
FREE_LAYOUT_TRANSLATION_MAX_PAGES | No | Free-plan page cap per layout-preserving PDF translation (default: 25) |
PLUS_LAYOUT_TRANSLATION_MAX_PAGES | No | Plus-plan page cap per layout-preserving PDF translation (default: 150) |
PRO_LAYOUT_TRANSLATION_MAX_PAGES | No | Pro-plan page cap per layout-preserving PDF translation (default: 300) |
LAYOUT_TRANSLATION_MAX_FILE_SIZE_MB | No | Hard file-size cap for layout-preserving PDF translation (default: 50) |
LAYOUT_TRANSLATION_ENGINE | No | Layout-preserving PDF translation engine. Set to retainpdf to enable the production sidecar flow |
RETAINPDF_API_BASE_URL | If layout translation is enabled |
Frontend (.env.local)
| Variable | Required | Description |
|---|
NEXT_PUBLIC_API_BASE | Yes | Backend URL (default: http://localhost:8000) |
BACKEND_INTERNAL_URL | No | Server-side proxy target (private network). Preferred over NEXT_PUBLIC_API_BASE when set. |
AUTH_SECRET | Yes | Must match backend AUTH_SECRET |
ADAPTER_SECRET | Yes | Must match backend ADAPTER_SECRET. Used to HMAC-sign the X-Proxy-IP claim sent to the backend. |
GOOGLE_CLIENT_ID | Yes | Google OAuth client ID |
GOOGLE_CLIENT_SECRET | Yes | Google OAuth client secret |
MICROSOFT_CLIENT_ID | No | Microsoft OAuth client ID |
MICROSOFT_CLIENT_SECRET | No | Microsoft OAuth client secret |
RESEND_API_KEY | No | Resend API key for magic link emails |
DocTalk/
├── backend/
│ ├── app/
│ │ ├── api/ # Route handlers (documents, chat, search, billing, auth, users)
│ │ ├── core/ # Config, dependencies, SSRF protection, security logging
│ │ ├── models/ # SQLAlchemy ORM models
│ │ ├── schemas/ # Pydantic request/response schemas
│ │ ├── services/ # Business logic (chat, credits, parsing, retrieval, extractors)
│ │ └── workers/ # Celery task definitions
│ ├── alembic/ # Database migrations
│ ├── seed_data/ # Demo PDF files
│ └── tests/
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js pages
│ │ ├── components/ # React components
│ │ ├── lib/ # API client, auth, SSE, utilities
│ │ ├── i18n/ # 11 language locale files
│ │ ├── store/ # Zustand state management
│ │ └── types/
│ └── public/
├── docs/
│ ├── ARCHITECTURE.md
│ ├── layout-translation-retainpdf.md
│ └── PRODUCT_STRATEGY.md
└── docker-compose.yml
Deployment
Branching: main (development) / stable (production).
Backend-first ordering is MANDATORY post-C1 (2026-05-20) — see docs/ARCHITECTURE.md §10 for the HMAC IP trust contract migration that requires backend-first deploys. Because pushing stable triggers Vercel auto-deploy, railway up must run BEFORE the push.
git checkout stable && git merge main # merge but do NOT push yet
railway up --detach # 1. backend deploys FIRST (dual-accepts old + new contracts)
curl -fsS https://backend-production-a62e.up.railway.app/health # 2. wait until new build is healthy
git push origin stable # 3. NOW push — Vercel auto-deploys frontend
# 4. Wait for Vercel deployment to show "Ready" in the dashboard.
# 5. (C1 follow-up) Watch `grep proxy.signed_ip.legacy_path_used` in Railway
# logs for 24h before landing the legacy-removal change.
git checkout main
| Target | Method |
|---|
| Backend (Railway) | git checkout stable && git merge main && railway up --detach (deploy FIRST) |
| Frontend (Vercel) | After Railway is healthy, git push origin stable → auto-deploys. Root directory: frontend/. |
Railway runs the core services: backend, PostgreSQL, Redis, and Qdrant.
Documents are stored in Cloudflare R2.
Layout-preserving PDF translation additionally requires the RetainPDF sidecar.
Versioning
DocTalk uses Semantic Versioning with pre-1.0 release numbers in 0.minor.patch
format. The source of truth is the repository root version.json.
0.2.0 means: major API stability has not been promised yet, but releases still
follow a predictable three-part version.- Use
python3 scripts/bump_version.py patch for bug-fix releases such as
0.2.0 -> 0.2.1.
- Use
python3 scripts/bump_version.py minor for backward-compatible feature
releases such as 0.2.1 -> 0.3.0.
- Use
python3 scripts/check_version_consistency.py to verify that
version.json, frontend/package.json, frontend/package-lock.json, and the
changelog stay in sync.
Runtime release metadata is exposed at backend /version and included in /health.
The frontend footer also shows the current release label.
Testing
cd backend && python3 -m pytest tests/test_smoke.py -v # Smoke tests
cd backend && SKIP_INTEGRATION=0 python3 -m pytest -m integration -v # Integration tests
cd backend && python3 -m ruff check app/ tests/ # Lint
python3 scripts/check_version_consistency.py # Version metadata check
Contributing
Contributions are welcome! Please open an issue first to discuss what you'd like to change.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes
- Push to the branch and open a Pull Request
License
MIT
