ThesisBase

ThesisBase is a local-first research paper library for thesis work. It stores PDFs, extracted text, and reusable AI-generated Markdown analyses so later comparison and chat workflows can use compact saved context instead of re-uploading papers.

What It Is

ThesisBase is a personal research workspace for managing thesis-related papers.

Instead of treating each PDF as something you have to repeatedly upload into an AI tool, ThesisBase processes papers once and saves reusable outputs alongside them:

• the source PDF
• extracted text
• normalized metadata such as title, authors, DOI, and venue
• AI-generated Markdown analysis
• per-run scores such as novelty, reproducibility, methodological rigor, and relevance to your thesis

The goal is to make literature review work easier:

• collect papers in one place
• preserve AI analysis history when models improve
• compare papers against a saved thesis profile
• organize reading sets with collections and tags
• export citations and compact chat-ready context

Current Feature Set

• PDF import with optional DOI or arXiv enrichment
• local storage using SQLite plus filesystem artifacts
• saved Markdown analysis runs per paper
• provider configuration for OpenAI-compatible APIs and Ollama
• thesis profile storage for relevance comparisons
• collections and tags
• citation export to BibTeX-friendly format
• chat sessions scoped to papers or collections
• manual notes per paper

How Storage Works

ThesisBase is local-first.

• Repo code stays in this project folder.
• Application data is stored outside the repo in your local app data directory.
• Provider credentials are intended to be stored in the OS keychain when available.
• If keychain storage is unavailable, the backend falls back to a local secrets file in the app data directory, not inside this repo.

That means API keys and paper data should not be committed as long as you keep using the default storage locations.

Stack

• Frontend: React + TypeScript + Vite
• Backend: FastAPI + SQLite
• Local storage: filesystem under the app data directory
• Credentials: OS keychain when available, local fallback file when not

Repo layout

• backend/ FastAPI app, storage services, queue worker, and tests
• frontend/ React app source and Vite config

Requirements

• Python 3.11+
• Node.js and npm
• Windows, macOS, or Linux with local filesystem access

On this machine, Node was installed under:

• C:\Program Files\nodejs

If npm is not recognized in cmd, open a fresh terminal after installation. If it still is not recognized, use npm.cmd.

Install And Run

Start the backend first, then the frontend in a second terminal.

Backend

Using PowerShell:

cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .[dev]
python -m uvicorn app.main:app --reload

Using cmd:

cd /d D:\github\ThesisLib\backend
python -m venv .venv
.venv\Scripts\activate.bat
python -m pip install -e .[dev]
python -m uvicorn app.main:app --reload

Backend default URL:

• http://127.0.0.1:8000

Frontend

Using PowerShell:

cd frontend
npm install
npm run dev

Using cmd:

cd /d D:\github\ThesisLib\frontend
npm install
npm run dev

If npm is blocked or not recognized, use:

cd /d D:\github\ThesisLib\frontend
npm.cmd install
npm.cmd run dev

Frontend default URL:

• http://127.0.0.1:5173

The Vite frontend proxies API requests to the backend automatically.

First-Time Setup Checklist

1. Start the backend.
2. Start the frontend.
3. Open the frontend in your browser.
4. Go to Providers and add an AI provider.
5. Go to Thesis Profile and save your thesis description, research questions, and keywords.
6. Import a PDF from the Import view.
7. Wait for the paper to move from queued/processing to ready.
8. Open the paper in Library to review the saved AI analysis.

Running Tests

Backend tests:

cd /d D:\github\ThesisLib\backend
python -m pytest -q

Notes About Secrets

• Do not put API keys into repo files.
• Do not create committed .env files with secrets.
• .gitignore excludes common local env files and fallback secret files.
• Provider credentials should be entered through the app UI so they are stored locally rather than in source control.