Sherlock

Personal investigative research desktop app for building evidence-based case maps.

Sherlock is a macOS app built with Tauri + React, backed by a local FastAPI + SQLite service. It supports entities/relationships, evidence tracking, timeline analysis, file attachments, and optional Claude-powered synthesis.

Highlights

• Investigation workspace with graph, entities, evidence, timeline, and files tabs.
• Local backend auto-bootstrap on app launch (creates a private virtualenv and installs backend dependencies).
• Local-mode fallback in UI if backend is temporarily unavailable.
• Local SQLite storage by default.
• Optional AI analysis (Claude) when ANTHROPIC_API_KEY is available.

Tech Stack

• Desktop: Tauri 2 (Rust)
• Frontend: React 18 + TypeScript + Tailwind
• Backend: FastAPI + SQLAlchemy + SQLite
• Graph: Cytoscape.js

Repository Layout

sherlock/
├── backend/
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   └── requirements.txt
├── src/
│   ├── api/
│   ├── components/
│   ├── hooks/
│   └── pages/
└── src-tauri/

Prerequisites

• macOS
• Node.js 18+
• Rust toolchain (rustup)
• Python 3.x available as python3 (required for backend bootstrap)

Development

Install frontend dependencies:

npm install

Run desktop app in dev mode:

npm run tauri dev

Optional browser-only loop:

# terminal 1
cd backend
python3 -m pip install -r requirements.txt
python3 -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload

# terminal 2
npm run dev

Build

npm run tauri build

Artifacts:

• src-tauri/target/release/bundle/macos/Sherlock.app
• src-tauri/target/release/bundle/dmg/Sherlock_0.1.0_aarch64.dmg

Backend Startup Model

On app launch, Tauri backend bootstrap does the following:

1. Resolves backend source directory (bundled resources in production, local backend/ in dev).
2. Creates runtime directory under app data.
3. Creates/reuses a local Python virtualenv.
4. Installs backend/requirements.txt (only when requirements hash changes).
5. Starts uvicorn on 127.0.0.1:8000.

If backend startup fails, the UI switches to local mode and continues with local storage fallback for core CRUD.

Data Locations

• SQLite DB: ~/Library/Application Support/sherlock/sherlock.db
• Attachments: ~/Library/Application Support/sherlock/attachments/
• Backend runtime venv: ~/Library/Application Support/com.sherlock.app/backend-runtime/
• UI fallback cache (when backend unavailable): browser localStorage key sherlock:localdb:v1

Environment Variables

• ANTHROPIC_API_KEY (optional): enables AI analysis endpoint usage.

Notes:

• Backend reads environment variables from the process environment.
• For local dev, export in your shell before launching.

Troubleshooting

"Backend on this computer is currently unreachable"

• Wait ~10–30 seconds on first launch (dependency install can take time).
• Ensure python3 is installed and available on PATH.
• Relaunch the app after updates.
• Confirm backend health manually:

  curl http://127.0.0.1:8000/health

Expected response:

{"status":"ok"}

AI tab errors

• Ensure ANTHROPIC_API_KEY is set in the environment used to launch the app.

License

Private/internal use.