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

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

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:

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.
VITE_WALLETCONNECT_PROJECT_ID	Reown/WalletConnect project ID used by the RainbowKit QR fallback for MetaMask/imToken. TokenPocket QR login does not use this. Required before testing or deploying the fallback scan flow.

Wallet login notes

Wallet login is used to verify address ownership for user favorites. The primary stable paths are injected wallets (window.ethereum) and TokenPocket QR callback login. MetaMask/imToken QR login is a RainbowKit/Reown fallback and may be unstable on some China networks.

The current frontend stores the wallet JWT in localStorage as a simple MVP session mechanism. This keeps the implementation small, but any future XSS vulnerability could expose a 30-day wallet session. A more secure future iteration should move wallet sessions to backend-set httpOnly cookies or shorten the token lifetime with refresh-token support.

Project layout

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.