# paper-doc

A tool that supports the paper-writing process: it manages the materials,
sections, figures, and references that go into a paper. The name reflects the
document-centric core of the workflow — a paper is composed from structured
documents rather than written in one pass.

## Tech Stack

**Backend**

- FastAPI (Python) — REST API
- SQLAlchemy + Alembic — ORM layer and schema migrations
- TiDB v8.5.0 — MySQL-compatible distributed SQL database, deployed in k3s
- Dependencies managed with `venv` + `requirements.txt`

**Frontend**

- Vue 3 + Vite — single-page application
- `axios` — HTTP client
- `vue-router` — client-side routing
- `pinia` + `pinia-plugin-persistedstate` — state management with persistence
- Element Plus — UI component library
- Dependencies managed with `pnpm`

## Architecture

A decoupled SPA + REST API layout:

- The Vue SPA runs in the browser and talks to the backend exclusively over
  HTTP/JSON via `axios`. It holds no direct database access.
- The FastAPI backend owns all persistence. It connects to TiDB through
  SQLAlchemy sessions and owns the schema through Alembic migrations.
- TiDB runs inside the existing k3s cluster. The backend reaches it either
  through the in-cluster Service (`tidb-tidb.tidb:4000`) or, during local
  development, through the NodePort `192.168.1.88:32738`.

Development runs both parts locally: Vite serves the SPA with a dev proxy that
forwards `/api` to the FastAPI process, so the browser sees a single origin and
no CORS configuration is required.

```
Browser ──HTTP/JSON──▶ FastAPI ──SQLAlchemy──▶ TiDB (k3s)
   │                      ▲
   └── Vite dev server ───┘  (proxy /api)
```

## Directory Structure

```
paper-doc/
├── backend/                 # FastAPI application
│   ├── app/
│   │   ├── api/             # route handlers (routers)
│   │   ├── core/            # settings and configuration
│   │   ├── crud/            # data-access helpers
│   │   ├── db/              # engine, session, declarative base
│   │   ├── models/          # SQLAlchemy models (intentionally empty for now)
│   │   └── schemas/         # Pydantic request/response models
│   ├── alembic/             # migration environment and revisions
│   ├── alembic.ini
│   ├── requirements.txt
│   └── .env.example
├── frontend/                # Vue 3 SPA
│   ├── src/
│   │   ├── api/             # axios instance and endpoint modules
│   │   ├── router/          # vue-router configuration
│   │   ├── stores/          # pinia stores (persisted)
│   │   ├── views/           # route-level components
│   │   └── components/      # reusable components
│   ├── package.json
│   └── vite.config.ts
└── docs/                    # project documentation
    └── OVERVIEW.md
```

## Getting Started

**Prerequisites**

- Python 3.10+ with `venv`
- Node.js 18+ with `pnpm`
- Network access to the TiDB instance (local development uses the NodePort)

**Backend**

```bash
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then fill in the database credentials
uvicorn app.main:app --reload --port 8000
```

API docs are then served at <http://127.0.0.1:8000/docs>.

**Frontend**

```bash
cd frontend
pnpm install
pnpm dev
```

The SPA is served at <http://127.0.0.1:5173> and proxies `/api` to the backend
on port 8000.

**Database**

The `paper_doc` database is created once, out of band, against TiDB. Schema
changes are applied through Alembic:

```bash
cd backend
alembic upgrade head
```