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, then read docs/ARCHITECTURE.md.

For local Docker/OrbStack development, see docs/LOCAL_ORBSTACK.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

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

Option A: OrbStack / Docker Compose

cd Arkie-Library-Backend
docker compose up --build

Then check:

curl http://localhost:8080/healthz

See docs/LOCAL_ORBSTACK.md for details.

Option B: Manual PostgreSQL + Go

1) Start PostgreSQL

Example with Docker:

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.

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:

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:

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

go run ./cmd/server

Check health:

curl http://localhost:8080/healthz

Useful commands

# 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.

Agent notes

AI/coding agent instructions are in AGENTS.md.