feat(storage): add local Postgres runtime and migrations

.github/workflows/ci.yml

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  frontend:
+    name: Frontend
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check Out Repository
+        uses: actions/checkout@v6
+
+      - name: Set Up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set Up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install Frontend Dependencies
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint Frontend
+        working-directory: frontend
+        run: pnpm lint
+
+      - name: Build Frontend
+        working-directory: frontend
+        run: pnpm build
+
+  backend:
+    name: Backend
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      PAPERCHAT_DATABASE_URL: postgresql+psycopg://paperchat:paperchat@127.0.0.1:5433/paperchat
+
+    steps:
+      - name: Check Out Repository
+        uses: actions/checkout@v6
+
+      - name: Set Up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install Backend Dependencies
+        working-directory: backend
+        run: uv sync --locked --group dev
+
+      - name: Validate Compose Configuration
+        run: docker compose -f compose.yaml config
+
+      - name: Start Local Postgres Runtime
+        run: ./scripts/postgres-up.sh
+
+      - name: Apply Backend Migrations
+        working-directory: backend
+        run: uv run alembic upgrade head
+
+      - name: Lint Backend
+        working-directory: backend
+        run: uv run ruff check
+
+      - name: Check Backend Formatting
+        working-directory: backend
+        run: uv run ruff format --check
+
+      - name: Type Check Backend
+        working-directory: backend
+        run: uv run ty check
+
+      - name: Test Backend
+        working-directory: backend
+        run: uv run pytest
+
+      - name: Show Postgres Logs On Failure
+        if: failure()
+        run: docker compose -f compose.yaml logs postgres
+
+      - name: Stop Local Postgres Runtime
+        if: always()
+        run: docker compose -f compose.yaml down -v

.gitignore

@@ -9,15 +9,16 @@ specs
 *.so
 
 # Python files #
-/evaluation/data*
-/evaluation/results*
 .env
 .venv
+backend/.venv
 dist
 build
 *.whl
 *.pytest_cache
 __pycache__
+frontend/dist
+frontend/node_modules
 
 # OS generated files #
 ######################

.pre-commit-config.yaml

@@ -12,10 +12,17 @@ repos:
       - id: check-merge-conflict
       - id: check-executables-have-shebangs
 
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.1"
+  - repo: local
     hooks:
       - id: ruff
-        args: [--exit-non-zero-on-fix, --config=backend/pyproject.toml]
+        name: ruff (legacy alias)
+        entry: /bin/zsh -lc 'cd backend && uv run ruff check'
+        language: system
+        files: ^backend/
+        pass_filenames: false
       - id: ruff-format
-        args: [--config=backend/pyproject.toml]
+        name: ruff format
+        entry: /bin/zsh -lc 'cd backend && uv run ruff format --check'
+        language: system
+        files: ^backend/
+        pass_filenames: false

README.md

@@ -1,55 +1,56 @@
-<p align="center">
-  <img src="docs/assets/logo.png" width="500" alt="PaperChat logo">
-</p>
+# PaperChat
 
----
+PaperChat is a local web app for grounded chat over user-owned PDFs.
 
-Paperchat is an AI-powered assistant that helps you take your research to the next level by enabling you to chat with your research library.
+The live code paths are:
 
-## Installation
+- `frontend/` for the React app
+- `backend/` for the local Python API
+- `compose.yaml` for the local Postgres + `pgvector` runtime
 
-The easiest and fastest way to install PaperChat is using [uv](https://github.com/astral-sh/uv):
+## Local Development
 
-```bash
-uv tool install git+https://github.com/kpeez/paperchat.git
-```
-
-This will install PaperChat and make it available as a command-line tool.
-
-To launch PaperChat, run:
+Start the database:
 
 ```bash
-paperchat
+./scripts/postgres-up.sh
 ```
 
-Alternatively, you can install PaperChat into your Python environment (requires Python 3.12 or newer):
+Start the backend:
 
 ```bash
-pip install git+https://github.com/kpeez/paperchat.git
+cd backend
+uv sync --locked --group dev
+uv run alembic upgrade head
+uv run paperchat-backend
 ```
 
-and then launch PaperChat by running:
+Start the frontend in a second shell:
 
 ```bash
-paperchat
+cd frontend
+pnpm install --frozen-lockfile
+pnpm dev
 ```
 
-## Quick Start
-
-1. Launch PaperChat: `paperchat`
-2. Upload a PDF document using the sidebar
-3. Wait for processing to complete
-4. Start asking questions about your document!
+## Verification
 
-## Settings
+Backend:
 
-PaperChat uses your own model API keys to connect to the AI providers. If you have API keys set as environment variables, they will be automatically detected. Otherwise, you can set them in the settings page. To get API keys, you can sign up for a free account on the providers' websites:
+```bash
+cd backend
+uv run ruff check
+uv run ruff format --check
+uv run ty check
+uv run pytest
+```
 
-- [Gemini](https://aistudio.google.com/apikey) (recommended)
-  - This is the recommend provider since you can access models for free (e.g., `gemini-2.5-pro-exp-03-25` and `gemini-2.0-flash`), and their text-embedding model is currently the best available on the [MTEB leaderboard](https://huggingface.co/spaces/mteb/leaderboard).
-- [OpenAI](https://platform.openai.com/api-keys)
-- [Anthropic](https://console.anthropic.com/settings/keys)
+Frontend:
 
-## Troubleshooting
+```bash
+cd frontend
+pnpm lint
+pnpm build
+```
 
-- Report issues on our [GitHub Issues page](https://github.com/kpeez/paperchat/issues)
+Runtime details are documented in [`docs/local-runtime.md`](docs/local-runtime.md).