docs: add frontend onboarding docs

2026-05-16 18:14:55 +08:00
parent 9ba50565cb
commit f59d1e8e2a
6 changed files with 405 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,95 @@
+# Arkie Library Frontend
+
+React + Vite frontend for the ARK Library / ARK database site. The app serves public resource browsing, search, favorites, wallet login UI, and an optional admin UI for resource management.
+
+## Tech stack
+
+- React 18 + TypeScript
+- Vite 5
+- React Router
+- Tailwind CSS
+- RainbowKit / Wagmi / Viem for wallet connection
+- Gitea Actions deploy workflow on `main`
+
+## Quick start
+
+```bash
+npm ci
+npm run dev
+```
+
+Local dev server: <http://localhost:5173>
+
+In development, Vite proxies these paths to the backend at `http://127.0.0.1:8080`:
+
+- `/api`
+- `/uploads`
+
+If `VITE_API_URL` is set, API calls use that absolute base URL instead.
+
+## Useful commands
+
+```bash
+npm run dev           # start Vite dev server
+npx tsc --noEmit      # TypeScript check; CI requires this
+npm run format:check  # Prettier check; CI requires this
+npm run format        # format source files
+npm run build         # production build to dist/
+npm run preview       # preview built app locally
+```
+
+Before pushing, run at least:
+
+```bash
+npx tsc --noEmit
+npm run format:check
+```
+
+## Environment variables
+
+Create a local `.env` only when needed. Do not commit secrets. See `.env.example` for a template.
+
+| Variable | Purpose |
+| --- | --- |
+| `VITE_API_URL` | API/upload origin. Empty means same-origin and Vite dev proxy handles local `/api` and `/uploads`. Production deploy currently uses `https://api.ark-library.com`. |
+| `VITE_WALLETCONNECT_PROJECT_ID` | Reown / WalletConnect project id. Needed for QR/mobile wallet connection. |
+| `VITE_DISABLE_ADMIN` | When set to `"true"`, public build redirects admin routes away. Production public deploy sets this to `"true"`. |
+| `VITE_ADMIN_ONLY` | When set to `"true"`, builds the admin-only app entry instead of the public app. |
+| `VITE_ADMIN_UI_PREFIX` | Optional admin UI base path. If absent in admin-only mode, code uses the secret prefix from `src/adminPaths.ts`. |
+
+## Project layout
+
+```text
+src/
+  main.tsx                 # app entry; switches public vs admin-only build
+  App.tsx                  # public app + optional admin routes
+  AppAdminOnly.tsx         # admin-only app entry
+  api.ts                   # fetch helpers and shared API types
+  i18n.tsx                 # zh-TW / zh-CN / en copy dictionary
+  adminPaths.ts            # admin UI prefix logic
+  adminRouteTree.tsx       # admin routes
+  components/              # reusable public components
+  layouts/                 # public/admin layout shells
+  pages/                   # public pages
+  pages/admin/             # admin pages
+  utils/                   # formatting/display helpers
+```
+
+Important config files:
+
+- `vite.config.ts` — Vite build and local backend proxy.
+- `tailwind.config.js` — ARK color palette and font stack.
+- `Dockerfile` / `nginx.conf` — container build and static SPA serving.
+- `.gitea/workflows/deploy.yml` — deploys `main` to both frontend servers.
+
+## Branch and deploy workflow
+
+- `main` is the deploy branch. Pushing to `main` triggers `.gitea/workflows/deploy.yml`.
+- `terry-staging` exists as a staging/work branch for later work.
+- The deploy workflow runs `npm ci`, `npx tsc --noEmit`, `npm run format:check`, `npm run build`, then rsyncs `dist/` to both frontend servers and verifies matching checksums.
+
+See also:
+
+- `AGENTS.md` — instructions for AI coding agents.
+- `docs/workflow.md` — recommended day-to-day workflow.
+- `docs/deploy.md` — deploy details and troubleshooting.