HyperWhisper Server

A full-stack speech-to-text transcription service built with Go/Echo and Nuxt 4, for real-time audio transcription.

---

Features

• JWT Authentication - Stateless access tokens (5 min) + stateful refresh tokens (7 days)
• API Key Management - Generate and manage API keys for programmatic access
• Trial System - Device fingerprint-based trial keys with configurable limits
• Usage Tracking - Comprehensive transcription logging and analytics
• Admin Dashboard - User management, token management, and system analytics

Tech Stack

Backend:

• Go 1.25+
• Echo v4 (web framework)
• PostgreSQL + sqlc (type-safe SQL)
• JWT authentication (golang-jwt/jwt/v5)

Frontend:

• Nuxt 4 (Vue 3, SPA mode)
• TypeScript
• Tailwind CSS 4
• shadcn-vue components

Project Structure

server/
├── cmd/
│ ├── serve.go # Server startup & routes
│ └── migrate.go # Database migration CLI
├── internal/
│ ├── auth/ # JWT, middleware, password hashing
│ ├── db/
│ │ ├── queries/ # SQL query definitions
│ │ └── sqlc/ # Generated Go code
│ └── handlers/ # HTTP handlers
├── migrations/ # Database migrations
├── web/ # Nuxt frontend
│ ├── app/
│ │ ├── components/ # Vue components
│ │ ├── pages/ # File-based routing
│ │ ├── composables/ # useAuth.ts
│ │ └── middleware/ # Route guards
│ └── dist/ # Built static files
├── server.go # CLI entry point
├── sqlc.yaml # sqlc configuration
├── Dockerfile # Production build
└── docker-compose.yml # Development environment

Getting Started

Prerequisites

• Docker & Docker Compose
• Go 1.25+ (for local development)
• Bun (for frontend development)

Development

# Start the development environment
docker-compose up
# Services:# - API: http://localhost:1323# - Nuxt dev: http://localhost:3000 (proxied through API)# - PostgreSQL: localhost:5432

Database Migrations

# Run pending migrations
go run server.go migrate up
# Revert migrations
go run server.go migrate down
# Check current version
go run server.go migrate version
# Go to specific version
go run server.go migrate goto 3

Production Build

# Build frontendcd web && bun run generate
# Build Go binary
go build -o hweb .# Run
./hweb serve

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgres://localhost:5432/hyperwhisper?sslmode=disable
JWT_SECRET	JWT signing secret	hyperwhisper-dev-secret-change-in-production
ACCESS_TOKEN_EXPIRY	Access token expiry (minutes)	5
REFRESH_TOKEN_EXPIRY	Refresh token expiry (days)	7
APP_ENV	Environment (dev or prod)	dev

Authentication Flow

1. User signs in, receives access token (5 min) + refresh token (7 days)
2. Access token stored in memory, refresh token in HTTP-only cookie
3. On access token expiry, client calls /token_refresh
4. Refresh tokens are single-use and tracked in database

License

AGPLv3