Arkie-Library-Backend/AGENTS.md

# AI Agent Instructions

This file is first-stop context for AI coding agents working in `Arkie-Library-Backend`.

## Repository identity

- Project: Arkie Library Backend / ARK database API.
- Go module: `github.com/arkie/ark-database`.
- Stack: Go, chi router, PostgreSQL/pgx, JWT, bcrypt, optional AWS S3 uploads, Ethereum wallet signature verification.
- Frontend repo expects backend API at `/api` and uploaded assets under `/uploads`.

## Branch and safety rules

- Current branch observed during initialization: `terry-staging`.
- Do not commit or push unless Terry explicitly asks.
- Before branch-changing, pulling, rebasing, or destructive operations, run:

```bash
git status --short --branch
```

- Do not commit secrets. `.env.example` is safe; real `.env` files should stay local/deployment-only.

## Required checks

Before proposing deploy/push, run:

```bash
gofmt -w .
go test ./...
```

Optional extra check:

```bash
go vet ./...
```

## Architecture quick map

- `cmd/server/main.go`: starts everything. Loads config, connects DB, ensures upload dir, optionally seeds admin, sets up S3, registers routes.
- `internal/config/config.go`: all environment variables and defaults.
- `internal/db/db.go`: creates and pings a `pgxpool.Pool`.
- `internal/auth/`: JWT helpers. Admin tokens use issuer `ark-admin`; wallet user tokens use issuer `ark-user`.
- `internal/handlers/public.go`: public category/resource/search/metric endpoints.
- `internal/handlers/admin.go`: admin login, dashboard, resource CRUD, tags.
- `internal/handlers/wallet_auth.go`: wallet nonce, signature verification, wallet profile.
- `internal/handlers/upload.go`: admin multipart upload to local disk or S3.
- `migrations/`: SQL schema files; there is no Go migration runner yet.
- `compose.yaml`: local OrbStack/Docker Compose setup with PostgreSQL + API.

## Important implementation patterns

- HTTP handlers are plain `net/http` functions using chi route params.
- DB access comes from request context via `handlers.WithPool` and `poolFrom(r)`.
- JSON responses use `writeJSON` in `internal/handlers/util.go`.
- JSON request bodies use `jsonDecode`, limited to 1 MiB.
- Resource IDs are UUIDs (`github.com/google/uuid`).
- Tags are stored in `tags` + `resource_tags`; new tag slugs are deterministic hashes from `tagSlug`.
- Public resource listing only returns `resources.status = 'published'` and `is_public = TRUE`.
- Admin routes require `Authorization: Bearer <admin-jwt>` from `/api/admin/login`.
- Wallet routes produce normal user JWTs, not admin JWTs.

## Database/migration notes

- `migrations/001_init.sql` is designed for a fresh database and is not fully idempotent.
- `migrations/002_wallet_auth.sql` is idempotent.
- `RUN_WALLET_AUTH_SCHEMA` defaults to true and lets startup create the wallet nonce table. In production with read-only/public DB users, apply migration separately and set it to false.

## Deployment/runtime notes

- `compose.yaml` runs local development in OrbStack/Docker: PostgreSQL on host port `5433`, API on host port `8080`.
- Dockerfile builds a static Go binary in a `golang:1.24-alpine` builder and runs it on Alpine.
- `UPLOAD_DIR` defaults to `./uploads`; Docker sets it to `/app/uploads`.
- When `S3_BUCKET` is set and AWS config loads, uploads go to S3. Otherwise uploads stay local.
- `JWT_SECRET` default is insecure and must be changed outside development.

## Agent behavior preferences

- Answer Terry concisely in Chinese unless code/docs require English.
- Prefer small direct changes over broad rewrites.
- Keep this README/AGENTS/docs updated when discovering non-obvious backend behavior.
- Search project memory before making decisions about workflow, deployment, or conventions.