Thunder- A Minimalist Backend Framework in Go

A scalable microservices framework powered by Go, gRPC-Gateway, Prisma, and Kubernetes. It exposes REST, gRPC and Graphql

🚀 Features

• ✔️ gRPC + REST (gRPC-Gateway) – Automatically expose RESTful APIs from gRPC services.
• ✔️ Prisma Integration – Efficient database management and migrations.
• ✔️ Kubernetes Ready – Easily deploy and scale with Kubernetes.
• ✔️ TLS Security – Secure gRPC communications with TLS.
• ✔️ Structured Logging – Built-in zap logging.
• ✔️ Rate Limiting & Authentication – Pre-configured middleware.
• ✔️ Modular & Extensible – Easily extend Thunder for custom use cases.
• ✔️ Thunder CLI - Generate, deploy, and create new projects effortlessly.
• ✔️ Graphql support - Transform grpc services into graphql queries

🏗️ Architecture Overview

📌 Use Cases

Thunder is designed for scalable microservices and high-performance API development, particularly suited for:

1. High-Performance API Development

• gRPC-first APIs with RESTful interfaces via gRPC-Gateway
• GraphQL interfaces via grpc-graphql-gateway for strongly-typed, schema-driven queries
• Critical performance and low-latency applications
• Strongly-typed APIs defined in Protobuf

2. Microservices Architecture

• Efficient inter-service communication with gRPC
• Kubernetes deployments with built-in service discovery and scaling
• Sidecar-friendly design for Istio/Linkerd environments

3. Database Management with Prisma

• Type-safe queries and zero-downtime migrations
• Multi-database support (PostgreSQL, MySQL, SQLite)
• Auto-generated client library for Go

4. Lightweight Backend Alternative

• Minimalist, modular core—no unnecessary middleware
• Fast startup and small binary footprint
• Pluggable extensions (auth, metrics, tracing)

5. Kubernetes & Cloud-Native Applications

• Containerized with Docker, optimized for multi-container pods
• Automatic horizontal scaling and load balancing
• Health checks, liveness/readiness probes built in

---

When Not to Use Thunder

• If you need a traditional REST-only API (consider Gin, Fiber, or Echo)
• If you require a feature-heavy, middleware-rich framework
• If you’re deploying a monolithic service outside of Kubernetes

📌 Getting Started

Installation

bash
1git clone https://github.com/Raezil/Thunder.git
2cd Thunder
3chmod +x install.sh
4./install.sh

Remember to install prerequisites, there is tutorial for this https://github.com/Raezil/Thunder/issues/99

Setup

Create a new Thunder application:

bash
1thunder init myapp
2cd myapp

Install Dependencies

bash
1go mod tidy

Define Your gRPC Service

Create a .proto file (e.g., example.proto):

proto
1syntax = "proto3";
2
3package example;
4
5import "google/api/annotations.proto";
6import "graphql.proto";
7
8service Example {
9	rpc SayHello(HelloRequest) returns (HelloResponse) {
10		option (google.api.http) = {
11			get: "/v1/example/sayhello"
12		};
13    		option (graphql.schema) = {
14      			type: QUERY   // declare as Query
15      			name: "sayhello" // query name
16    		};
17	};
18}
19
20message HelloRequest {
21	string name = 1 [(graphql.field) = {required: true}];
22}
23
24message HelloResponse {
25	string message = 1;
26}

🔨 Generate a Service Scaffold

Use the new scaffold command to spin up a full CRUD .proto file—complete with gRPC, REST (gRPC-Gateway) and GraphQL annotations. Pass your fields as a comma-separated list of name:type pairs:

bash
1thunder scaffold   -service UserService   -entity User   -fields "id:string,name:string,email:string,age:int32"

Add your service entry in services.json:

go
1[
2    {
3      "ServiceName": "Example",
4      "ServiceStruct": "ExampleServiceServer",
5      "ServiceRegister": "RegisterExampleServer",
6      "HandlerRegister": "RegisterExampleHandler"
7      "GraphqlHandlerRegister": "RegisterExampleGraphqlHandler"
8
9    }
10]

🛠️ Prisma Integration

Define your schema in schema.prisma:

prisma
1datasource db {
2  provider = "postgresql"
3  url      = env("DATABASE_URL")
4}
5
6model User {
7  id    String @default(cuid()) @id
8  name  String
9  email String @unique
10}

Generate the service implementation:

bash
1thunder generate --proto=example.proto --graphql=true

🚀 Running the Server

Start the server:

bash
1go run ./cmd/app/server/main.go

Server accessible via HTTP at localhost:8080 and gRPC at localhost:50051.

🚀 Running the Tests

Mocking Tests

bash
1cd pkg/services/generated
2mockgen -source=yourservice_grpc.pb.go -destination=./yourservice_mock.go

Run Tests

bash
1go test ./pkg/db ./pkg/middlewares/ ./pkg/services/ ./pkg/services/generated

🔧 Kubernetes Deployment

PgBouncer Configuration

This setup configures PgBouncer to connect to a PostgreSQL database using Kubernetes resources.

Updating the userlist.txt Secret

To regenerate and update the userlist.txt secret, use the following command to encode the credentials:

bash
1echo '"postgres" "postgres"' | base64

Now, update pgbouncer-all.yaml under the Secret section with the new base64-encoded value:

yaml
1apiVersion: v1
2kind: Secret
3metadata:
4  name: pgbouncer-secret
5type: Opaque
6data:
7  userlist.txt: <BASE64_ENCODED_VALUE>  # "postgres" "postgres" in base64

Generate TLS Certificates

bash
1cd cmd
2mkdir certs
3openssl req -x509 -newkey rsa:4096 -keyout certs/server.key -out certs/server.crt -days 365 -nodes \
4  -subj "/CN=localhost" \
5  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

Generate Kubernetes Secrets

bash
1kubectl create secret generic app-secret   --from-literal=DATABASE_URL="postgres://postgres:postgres@pgbouncer-service:6432/thunder?sslmode=disable"   --from-literal=JWT_SECRET="secret"
2
3kubectl create secret generic postgres-secret   --from-literal=POSTGRES_USER=postgres   --from-literal=POSTGRES_PASSWORD=postgres   --from-literal=POSTGRES_DB=thunder

Build & Deploy Docker Image

bash
1thunder build
2thunder deploy

Check pod status:

bash
1kubectl get pods -n default
2kubectl describe pod $NAME -n default

📜 Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature-new
3. Commit changes: git commit -m "Added feature"
4. Push to your branch: git push origin feature-new
5. Submit a pull request.

🔗 References

• Go Documentation
• gRPC
• gRPC-Gateway
• Prisma ORM
• Kubernetes Docs
• Tutorial

📣 Stay Connected

⭐ Star the repository if you find it useful!
📧 For support, use GitHub Issues.

License

Thunder is released under the MIT License.