Refreshing is a generic, production-ready full-stack boilerplate built with Go (Gin + GORM) on the backend and Next.js (App Router + Shadcn UI) on the frontend. It ships with everything you need to bootstrap a modern SaaS, internal tool, or developer platform — without the boilerplate headaches.

The project was designed from the ground up to be framework-first and business-agnostic: plug in your own domain logic while reusing the battle-tested infrastructure that comes out of the box.

✨ Key Features

🔐 Multi-auth System — Local password login/registration + pluggable OIDC/OAuth2 providers (supports multiple auth sources simultaneously)
🗝️ Personal Access Tokens — API key management for programmatic access; supports Authorization: Bearer and X-Access-Token headers
👤 User Management — Admin panel for listing, searching, filtering, enabling/disabling user accounts
⚙️ Dynamic System Config — Key-value system configuration management with live reload, controllable from the admin UI
📋 Async Task Queue — Background job processing with Asynq (Redis-backed), including a scheduling dashboard
📁 S3 File Storage — Unified file upload/download via S3-compatible APIs with local disk cache
📊 Observability — Structured logging (Zap) + distributed tracing (OpenTelemetry)
🎨 Modern UI — Responsive, dark-mode-ready design system built with Tailwind CSS 4 and Shadcn UI
📖 Built-in Documentation — Integrated docs portal with usage guides, API reference, privacy policy, and terms of service

🏗️ Architecture Overview

┌─────────────────┐    ┌─────────────────────────────┐    ┌─────────────────┐
│   Frontend      │    │          Backend             │    │   Database      │
│   (Next.js)     │◄──►│           (Go)               │◄──►│  (PostgreSQL)   │
│                 │    │                              │    │                 │
│ • React 19      │    │ • Gin HTTP Framework         │    │ • PostgreSQL    │
│ • TypeScript    │    │ • GORM ORM                   │    │ • Redis Cache   │
│ • Tailwind 4    │    │ • Multi-provider Auth        │    │                 │
│ • Shadcn UI     │    │ • AccessToken Middleware     │    │                 │
│                 │    │ • Asynq Task Queue           │    │                 │
│                 │    │ • OpenTelemetry Tracing      │    │                 │
│                 │    │ • Swagger API Docs           │    │                 │
└─────────────────┘    └─────────────────────────────┘    └─────────────────┘
                                      │
                           ┌──────────┴──────────┐
                           │   Multi-Process CLI  │
                           │  (Cobra + Viper)     │
                           │ • api      (HTTP)    │
                           │ • worker   (Queue)   │
                           │ • scheduler(Cron)    │
                           └─────────────────────┘

🛠️ Tech Stack

Backend

Go 1.25+ — Primary language
Gin — HTTP web framework
GORM — ORM with PostgreSQL & ClickHouse support
Redis — Cache, session store, and task queue backend
Asynq — Distributed task queue (Redis-backed)
Cobra + Viper — CLI entrypoint and configuration management
OpenTelemetry — Distributed tracing and observability
Zap — Structured, high-performance logging
Swagger (Swaggo) — Auto-generated API documentation
AWS SDK v2 — S3-compatible file storage
Snowflake — Distributed ID generation

Frontend

Next.js 16 — React framework with App Router
React 19 — UI library
TypeScript — Type safety
Tailwind CSS 4 — Utility-first styling
Shadcn UI — Accessible, composable component library
Lucide Icons — Icon library

📋 Requirements

Go >= 1.25
Node.js >= 18.0
PostgreSQL >= 14
Redis >= 6.0
pnpm >= 8.0 (recommended)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/linux-do/credit.git refreshing
cd refreshing

2. Configure Environment

cp config.example.yaml config.yaml

Edit config.yaml to configure your database, Redis, and at least one auth source (OIDC or password-based).

3. Initialize Database

# Create the database
createdb -h <host> -p 5432 -U postgres refreshing

# Database schema is auto-migrated on first startup

4. Start the Backend

# Install Go dependencies
go mod tidy

# Generate Swagger API documentation
make swagger

# Start the HTTP API server
go run main.go api

The backend also supports separate scheduler and worker processes for async task processing:
go run main.go scheduler   # Cron job scheduler
go run main.go worker      # Asynq task worker

5. Start the Frontend

cd frontend

# Install dependencies
pnpm install

# Start dev server (Turbopack)
pnpm dev

6. Access the Application

Service	URL
Frontend	http://localhost:3000
Swagger API Docs	http://localhost:8000/swagger/index.html
Health Check	http://localhost:8000/api/health

⚙️ Configuration

Key configuration options (see config.example.yaml for the full reference):

Option	Description	Example
`app.addr`	Backend listen address	`:8000`
`database.host`	PostgreSQL host	`127.0.0.1`
`database.database`	Database name	`refreshing`
`redis.host`	Redis host	`127.0.0.1`
`storage.endpoint`	S3-compatible endpoint	`s3.amazonaws.com`
`oauth2.client_id`	Default OIDC client ID	`your_client_id`

🔧 Development Guide

Backend

# Run API server
go run main.go api

# Run task scheduler
go run main.go scheduler

# Run async worker
go run main.go worker

# Regenerate Swagger docs (required after controller changes)
make swagger

# Format & vet code
make tidy

Frontend

cd frontend

# Development mode (Turbopack)
pnpm dev

# Production build
pnpm build

# Start production server
pnpm start

# Lint & format
pnpm lint
pnpm format

📁 Project Structure

Refreshing/
├── main.go                  # Entry point (delegates to internal/cmd)
├── config.example.yaml      # Configuration template
├── Makefile                 # Common commands (swagger, tidy, license)
├── Dockerfile               # Container image build
├── docs/                    # Swagger auto-generated docs
├── frontend/                # Next.js frontend application
│   ├── app/                 # App Router pages
│   ├── components/          # React components (ui, common, layout)
│   ├── lib/services/        # API service layer
│   └── types/               # TypeScript type definitions
└── internal/                # Go backend (private)
    ├── cmd/                 # CLI commands (api, scheduler, worker)
    ├── apps/                # Business modules (oauth, user, admin, upload)
    ├── model/               # GORM entities and business methods
    ├── router/              # HTTP route registration
    ├── task/                # Async task definitions and workers
    ├── db/                  # Database and Redis initialization
    ├── storage/             # S3 file storage abstraction
    └── common/              # Shared utilities and response helpers

📚 API Documentation

Swagger API documentation is auto-generated and available once the backend is running:

http://localhost:8000/swagger/index.html

The built-in frontend docs portal at /docs includes:

Usage Guide — Step-by-step walkthrough for getting started
API Reference — Detailed interface documentation
Privacy Policy — Template privacy policy (customize as needed)
Terms of Service — Template terms of service

🧪 Testing

# Backend tests
go test ./...

# Frontend lint
cd frontend && pnpm lint

🚀 Deployment

Docker

# Build image
docker build -t refreshing .

# Run (pass your config as a volume mount)
docker run -d -p 8000:8000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  refreshing api

Production

Build the frontend:
```
cd frontend && pnpm build
```
Compile the backend:
```
go build -o refreshing main.go
```
Configure config.yaml for production.

Start services:

./refreshing api        # HTTP API
./refreshing scheduler  # Cron scheduler (optional)
./refreshing worker     # Task worker (optional)

🤝 Contributing

We welcome contributions! Please read the following before submitting code:

Workflow

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit your changes (git commit -am 'Add your feature')
Push to the branch (git push origin feature/your-feature)
Open a Pull Request

📄 License

This project is licensed under the Apache 2.0 License.

Languages

Go 56.6%

TypeScript 35.1%

CSS 4.7%

Lua 1.5%

HTML 0.8%

Other 1.2%