Arkie-Library-Backend/README.md

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

For local Docker/OrbStack development, see **[docs/LOCAL_ORBSTACK.md](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

```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

### Option A: OrbStack / Docker Compose

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

Then check:

```bash
curl http://localhost:8080/healthz
```

See **[docs/LOCAL_ORBSTACK.md](docs/LOCAL_ORBSTACK.md)** for details.

### Option B: Manual PostgreSQL + Go

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