# 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 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_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; one folder per page, e.g. Home/index.tsx
  pages/admin/             # admin pages; one folder per page, e.g. Resources/index.tsx
  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.