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 attach a wallet address to user favorites. The frontend connects an injected wallet (window.ethereum), sends the selected address to POST /api/auth/wallet/login, and stores the returned wallet JWT in localStorage as a simple MVP session mechanism. This keeps the implementation small, but any future XSS vulnerability could expose a 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.