PandaGuide

PandaGuide is a restaurant discovery and review platform: a Go (Fiber) REST API, a Next.js web app (App Router) with Adobe React Spectrum and React Aria, PostgreSQL, and Meilisearch. Local backing services run via Compose under infra/ (same layout convention as the sibling Kurator project one directory up).

---

Prerequisites

• Go (see api/go.mod go directive)
• Node.js 22+ for the web app (engines in web/package.json; CI uses Node 22)
• Podman or Docker with Compose v2 (podman compose / docker compose)

---

Repository layout

Path	Role
api/	Go API (cmd/api, optional cmd/migrate), internal packages, SQL in api/migrations/, Dockerfile, Makefile
web/	Next.js app (app/ including app/api/v1/... proxy, components/, lib/, content/), Dockerfile
.cursor/rules/	web-app-stack-standard.mdc — Kurator-derived stack rules with PandaGuide overrides (Spectrum/Aria, not Tailwind)
.github/workflows/	ci-release.yml (unit tests), snyk.yml (when SNYK_TOKEN is configured)
infra/nginx/	Optional sample load balancer config (not wired into Compose by default)
docker-compose.yml	Includes infra/docker-compose.yml so compose up from the repo root works
infra/docker-compose.yml	Local dependencies: Postgres, Meilisearch, Meilisearch UI
Makefile	Shortcuts: dev-db, dev-api, dev-web, api-build, api-test, etc.

---

Local development

1. Start backing services

From the repository root:

podman compose -f infra/docker-compose.yml up -d
# or: make dev-db

2. API

cd api
cp .env.example .env   # configure DATABASE_URL, Meilisearch, JWT, etc.
go run ./cmd/api

Migrations in api/migrations/*.sql are applied automatically when the API starts (unless MIGRATIONS_PATH points at a directory override).

3. Web

cd web
npm ci
cp .env.local.example .env.local   # set API_INTERNAL_URL (proxy target); see file comments
npm run dev

Browser → API: the UI calls same-origin /api/v1/.... Next.js web/app/api/v1/[[...path]]/route.ts proxies to the Go API so cookies stay on the web origin. Set API_INTERNAL_URL (and optionally API_PROXY_TARGET) to the API base URL (e.g. http://127.0.0.1:8080). Server-side data fetching uses web/lib/apiUrl.ts.

---

Makefile (repo root)

Command	Description
make help	Lists shortcuts
make dev-db	Postgres + Meilisearch (+ UI) via Compose
make dev-api / make dev-web	Run API or Next dev server
make dev	dev-db then API and web in parallel
make api-build	Build API → api/bin/pandaguide-api
make api-test	go test ./... in api/
make web-test	Vitest in web/
make lint	golangci-lint + next lint

See make -C api help for API-only targets.

---

Health

• GET /health on the API returns a simple JSON status payload.

PandaGuide