Go + SvelteKit Starter Kit

A production-ready full-stack starter kit pairing a Go API backend with a SvelteKit CSR frontend — batteries included for auth, RBAC, notifications, AI chat, and a public API.

Features

• Auth — Email/password + Google OAuth, JWT (access + refresh rotation), 2FA (TOTP)
• RBAC — Role-based access control (superadmin, admin, user) with permission guards
• Notifications — Real-time push via WebSocket + persistent notification history
• AI Chat — Streaming chat completions via Anthropic Claude
• Public API — API key management (sk_* prefix), per-key scopes, rate limiting, audit logs
• Webhooks — Register URLs to receive event callbacks
• Admin Panel — User management, role assignment, system stats
• Email — Transactional email (SMTP or SendGrid) for verification, password reset

Tech Stack

Quick Start

# 1. Copy env files and install dependencies
make setup

# 2. Start Postgres + Redis
make infra

# 3. Apply database migrations
make migrate

# 4. Start backend + frontend with hot-reload
make dev

• Dev (frontend + Vite proxy): http://localhost:5173
• Dev (backend direct): http://localhost:8080
• Production (via nginx): http://localhost — API at /api, frontend at /
• API Docs (Swagger UI): http://localhost/api/docs (prod) or http://localhost:8080/api/docs (dev)

Architecture

.
├── backend/                  Go API server + background worker
│   ├── cmd/api/              Entrypoint (HTTP server)
│   ├── cmd/worker/           Entrypoint (background jobs)
│   ├── internal/             Feature domains (auth, user, notification, …)
│   │   ├── <domain>/
│   │   │   ├── handler.go    HTTP handlers (Chi)
│   │   │   ├── service.go    Business logic
│   │   │   ├── repository.go Database queries (pgx)
│   │   │   └── model.go      Types + request/response structs
│   │   ├── middleware/       Auth, RBAC, rate-limit, logging
│   │   └── server/           Router wiring + embedded OpenAPI spec
│   ├── migrations/           Sequential SQL migrations (NNNNNN_name.up/down.sql)
│   └── pkg/                  Shared infrastructure (config, db, redis, token, …)
├── frontend/                 SvelteKit app (CSR-only, adapter-node)
│   ├── src/lib/
│   │   ├── api/              Typed fetch wrappers ($api alias)
│   │   ├── components/       Reusable UI components ($components alias)
│   │   ├── stores/           Svelte stores — auth, toast, notifications ($stores alias)
│   │   └── types/            Shared TypeScript interfaces ($types alias)
│   ├── src/routes/
│   │   ├── (auth)/           Public pages: login, register, forgot-password
│   │   └── (app)/            Authenticated pages with sidebar layout
│   └── e2e/                  Playwright end-to-end tests
├── docker-compose.yml        Production compose
├── docker-compose.dev.yml    Dev infrastructure (Postgres + Redis only)
└── Makefile                  Unified dev commands

Environment Variables

Copy backend/.env.example → backend/.env (done automatically by make setup).

Available Commands

Tests

Backend unit tests (no database required):

make test
# or run a single test:
cd backend && go test ./pkg/token/... -run TestGeneratePair -v

Frontend unit tests (Vitest):

make test-fe

End-to-end tests (Playwright — requires running dev stack):

make dev          # in one terminal
cd frontend && npm run test:e2e   # in another

For E2E tests that require a real user account, set TEST_EMAIL and TEST_PASSWORD in your environment.

Deployment

A docker-compose.yml is provided for production use:

docker compose up -d

The compose file expects the same environment variables as .env.example. Mount secrets via Docker secrets or an external env file.

License

MIT