OpenFlare/README.md

Refreshing

🚀 A modern, production-ready full-stack boilerplate for building scalable web applications

中文

📖 Introduction

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

1. Build the frontend:

   cd frontend && pnpm build
   

2. Compile the backend:

   go build -o refreshing main.go
   

3. Configure config.yaml for production.

4. 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:

• Contributing Guidelines
• Code of Conduct
• Contributor License Agreement

Workflow

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

📄 License

This project is licensed under the Apache 2.0 License.