Arkie-Library-Frontend/README.md

# Arkie Library Frontend

React + Vite frontend for the ARK Library / ARK database site. The app serves public resource browsing, search, favorites, and an optional admin UI for resource management.

## Tech stack

- React 18 + TypeScript
- Vite 5
- React Router
- Tailwind CSS
- 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 test              # run Vitest test suite
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
npm test
```

## 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_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`.                                                                                                                                                                        |
| `VITE_USE_MOCK_POSTS`           | Telegram-style resource stream (`/browse`, `/category/:slug`) uses mock posts from `src/mocks/mockPosts.ts` only when set to `"true"`. Leave unset or set to `"false"` to hit the real `/api/posts` API. See `.unipi/docs/specs/2026-05-25-posts-api-contract.md`. |

## 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-CN / en / ja / ko / vi / id / ms 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 test`, `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.