wysi-server

This is the database and REST API meant to serve the wysi-client

It is mostly just a proxy for the osu! API, although it also stores additional data for use on wysi.

Prerequisites

• Go 1.24.3+
• sqlc
• Docker
• Docker Compose

If you have Nix installed, you can use the dev shell with:

nix develop

Getting Started

1. Copy the environment file:

cp .example.env .env

2. Edit the .env file with your preferred editor and set the required values:

   • OSU_ID and OSU_SECRET from your osu! OAuth application
   • JWT_SECRET - generate a secure random string
   • Database credentials

3. Install dependencies:

go mod download

4. Generate SQL code:

sqlc generate

5. Start the database and cache:

docker compose up -d

6. Run database migrations:

goose up

7. Start the server:

# Development with hot reload
air

# Or run directly
go run .

The server will start on port 1323.

Development

Project Structure

.
├── api/          # External API clients (osu! API)
├── cache/        # Redis cache initialization
├── db/           # Database connection
├── handlers/     # HTTP request handlers
├── migrations/   # Database migrations (goose)
├── queries/      # SQL queries for sqlc
├── schemas/      # Data structures and types
├── services/     # Business logic
├── sql/          # Generated SQL code (sqlc)
└── utils/        # Helper functions

Database Migrations

Migrations are managed with goose. The environment variables are already configured in .env.

# Create a new migration
goose create migration_name sql

# Apply migrations
goose up

# Rollback last migration
goose down

# Check migration status
goose status

Regenerating SQL Code

After modifying files in queries/, regenerate the Go code:

sqlc generate

API Endpoints

Public Endpoints

• GET / - Health check
• GET /search?query={term} - Search users/beatmaps
• POST /login - Authenticate with osu! OAuth code
• GET /users/:userId - Get user profile
• GET /users/:userId/scores/:scoreCategory - Get user scores
• GET /users/:userId/beatmaps/:beatmapsetCategory - Get user beatmaps
• GET /users/:userId/most - Get most played beatmaps
• GET /users/:userId/setup - Get user setup
• GET /users/:userId/collections - Get user collections
• GET /beatmap/:mapId/scores - Get beatmap scores
• GET /rankings/:mode/:category/:page - Get rankings
• GET /scores/:scoreId - Get score details
• GET /medals - Get medals list

Protected Endpoints (requires JWT)

• PUT /users/:userId/setup - Update user setup
• PUT /users/:userId/collections - Create collection
• DELETE /users/:userId/collections/:collectionId - Delete collection

Environment Variables

Variable	Description	Required
WEB_ORIGIN	Allowed CORS origin	Yes
APP_ENV	Environment (dev/prod)	Yes
JWT_SECRET	Secret for signing JWTs	Yes
OSU_ID	osu! OAuth client ID	Yes
OSU_SECRET	osu! OAuth client secret	Yes
OSU_REDIRECT	osu! OAuth redirect URL	Yes
DB_USER	Database username	Yes
DB_PASS	Database password	Yes
DB_NAME	Database name	Yes
DB_HOST	Database host	Yes

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test your changes locally
5. Submit a pull request

License

See LICENSE file for details.