docs: add backend onboarding guide

2026-05-18 07:56:27 +08:00
parent 141d92dc15
commit 00540fbb73
6 changed files with 1067 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,131 @@
+# Arkie Library Backend
+
+Go backend for the ARK Library / ARK Database website.
+
+If Go is new for you: start with **[docs/GO_FOR_BEGINNERS.md](docs/GO_FOR_BEGINNERS.md)**, then read **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
+
+## What this service does
+
+- Serves public library data under `/api`.
+- Serves uploaded files under `/uploads`.
+- Provides admin login and admin CRUD APIs for resources.
+- Supports wallet sign-in with Ethereum personal-sign messages.
+- Stores data in PostgreSQL.
+- Stores uploads locally by default, or in S3 when configured.
+
+## Tech stack
+
+- Go module: `github.com/arkie/ark-database`
+- HTTP router: `github.com/go-chi/chi/v5`
+- Database: PostgreSQL via `github.com/jackc/pgx/v5/pgxpool`
+- Auth: JWT via `github.com/golang-jwt/jwt/v5`
+- Password hashing: bcrypt
+- Wallet signature verification: `github.com/ethereum/go-ethereum`
+- Optional uploads: AWS S3 SDK v2
+
+## Folder map
+
+```text
+cmd/server/main.go          # application entry point: config, DB, router, endpoints
+internal/config/config.go   # environment variables and default values
+internal/db/db.go           # PostgreSQL connection pool
+internal/auth/              # JWT signing/parsing for admin and wallet users
+internal/handlers/          # HTTP handlers: public, admin, upload, wallet auth
+internal/seed/seed.go       # optional initial admin user
+migrations/                 # SQL schema files, apply manually
+static/                     # bundled static assets copied into uploads
+```
+
+## Quick local run
+
+### 1) Start PostgreSQL
+
+Example with Docker:
+
+```bash
+docker run --name ark-postgres \
+  -e POSTGRES_USER=ark \
+  -e POSTGRES_PASSWORD=ark \
+  -e POSTGRES_DB=arkdb \
+  -p 5432:5432 \
+  -d postgres:16
+```
+
+### 2) Apply schema once
+
+`migrations/001_init.sql` is for a fresh empty database. Do not run it twice on the same DB unless you reset the DB first.
+
+```bash
+cd Arkie-Library-Backend
+export DATABASE_URL='postgres://ark:ark@localhost:5432/arkdb?sslmode=disable'
+psql "$DATABASE_URL" -f migrations/001_init.sql
+```
+
+Wallet nonce schema is normally auto-created at app startup because `RUN_WALLET_AUTH_SCHEMA` defaults to true. If you want to apply it manually and disable startup DDL:
+
+```bash
+psql "$DATABASE_URL" -f migrations/002_wallet_auth.sql
+export RUN_WALLET_AUTH_SCHEMA=false
+```
+
+### 3) Configure env
+
+Copy the example and edit values as needed:
+
+```bash
+cp .env.example .env
+```
+
+This project does not auto-load `.env`; either export variables in your shell or run with a dotenv helper.
+
+### 4) Run the server
+
+```bash
+go run ./cmd/server
+```
+
+Check health:
+
+```bash
+curl http://localhost:8080/healthz
+```
+
+## Useful commands
+
+```bash
+# Format all Go files
+gofmt -w .
+
+# Compile and run all package tests
+go test ./...
+
+# Run the backend
+go run ./cmd/server
+
+# Build a local binary
+go build -o ./bin/server ./cmd/server
+```
+
+## Environment variables
+
+See `.env.example` for all variables. Important ones:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `HTTP_ADDR` | `:8080` | Listen address |
+| `DATABASE_URL` | `postgres://ark:ark@localhost:5432/arkdb?sslmode=disable` | PostgreSQL connection |
+| `JWT_SECRET` | `dev-insecure-change-me` | JWT signing key; change in production |
+| `UPLOAD_DIR` | `./uploads` | Local upload directory |
+| `CORS_ORIGINS` | empty | Comma-separated allowed browser origins |
+| `SEED_ADMIN` | false | Set `true`/`1` to create first admin if none exists |
+| `ADMIN_EMAIL` | `admin@ark.local` | Seed admin email |
+| `ADMIN_PASSWORD` | `admin123` | Seed admin password |
+| `S3_BUCKET` | empty | Enables S3 uploads when set |
+
+## API docs
+
+See **[docs/API.md](docs/API.md)**.
+
+## Agent notes
+
+AI/coding agent instructions are in **[AGENTS.md](AGENTS.md)**.