Arkie-Library-Frontend/AGENTS.md

AI Agent Instructions

This file is the first-stop context for AI coding agents working in this repo.

Repository identity

• Project: Arkie Library Frontend / ARK database web UI.
• Package name: ark-database-web.
• Stack: React 18, TypeScript, Vite, Tailwind CSS, React Router, RainbowKit/Wagmi.
• Backend API is expected at /api; uploaded assets under /uploads.

Branch rules

• Current deploy branch: main.
• Work/staging branch available: terry-staging.
• Do not commit or push unless Terry explicitly asks.
• Pushing to main triggers production frontend deploy via Gitea Actions.
• Before branch-changing or pulling, run git status --short --branch and preserve local work.

Required checks

Before proposing a push or deploy, run:

npx tsc --noEmit
npm run format:check
npm test

If code formatting is needed, run:

npm run format

Notes:

• tsconfig.json has strict, noUnusedLocals, and noUnusedParameters; unused imports fail CI.
• dist/ is build output and should not be edited manually.

App structure quick map

• src/main.tsx chooses normal app vs admin-only build using VITE_ADMIN_ONLY.
• src/App.tsx contains public routes and conditionally exposes admin routes unless VITE_DISABLE_ADMIN === "true".
• src/api.ts defines apiBase, fetch helpers, and shared resource/category types.
• src/i18n.tsx contains all UI copy for zh-TW, zh-CN, and en.
• src/pages/admin/ contains admin UI screens.
• src/adminPaths.ts handles admin path prefix logic. Keep it in sync with backend/nginx admin host config if changed.

Environment variables

See .env.example and README.md for details. Do not commit real secrets or private deployment keys.

Common production public build env:

VITE_API_URL=https://api.ark-library.com
VITE_DISABLE_ADMIN=true

Deployment context

.gitea/workflows/deploy.yml deploys on push to main:

1. npm ci
2. npx tsc --noEmit
3. npm run format:check
4. npm test
5. npm run build with production public env
6. rsync dist/ to both frontend servers
7. compare remote index.html checksums

Agent behavior preferences

• Answer Terry in concise Chinese unless the task requires code/docs in English.
• Prefer small, direct fixes over broad refactors.
• Update README/docs/memory when learning non-obvious project facts.
• Search existing project memory before making decisions about workflow, deploy, or conventions.