From 4438b04ff134bc02555b64e08f6de01c90a2872e Mon Sep 17 00:00:00 2001
From: govin <govin@prepeep.com>
Date: Thu, 17 Sep 2026 12:44:54 +0800
Subject: [PATCH] docs: add docs/OVERVIEW.md and CLAUDE.md (init_project steps
 2-4)

---
 CLAUDE.md        |  10 ++++
 docs/OVERVIEW.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 126 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 docs/OVERVIEW.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..41e448d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,10 @@
+# CLAUDE.md
+
+Project structure and overview: see docs/OVERVIEW.md
+
+## Rules
+
+1. Before any task, search skills via `search_skills` or `get_skills_by_tag`
+   first — use the matched ones; fall back to judgment if none are found.
+2. After each change, self-evaluate whether to commit. For large changes or
+   accumulated edits, commit and push frequently.
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
new file mode 100644
index 0000000..9ce515a
--- /dev/null
+++ b/docs/OVERVIEW.md
@@ -0,0 +1,116 @@
+# 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
+```