117 lines
3.7 KiB
Markdown
117 lines
3.7 KiB
Markdown
# 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
|
|
```
|