DEV Community: Md Murtuza Hussain

Beyond REST: Architecting High-Performance Microservices with gRPC in Go

Md Murtuza Hussain — Sun, 17 May 2026 04:50:42 +0000

When scaling backend architecture, the communication layer between services eventually
becomes a bottleneck. While REST over HTTP/1.1 with JSON payloads is the undisputed
standard for public-facing web APIs, it introduces significant serialization overhead
and lacks strict, enforceable contracts for internal, service-to-service communication.

This is where gRPC shines. By leveraging HTTP/2 for multiplexed transport and Protocol
Buffers (Protobuf) for efficient binary serialization, gRPC provides low-latency,
strictly-typed communication well-suited to internal microservice architectures.

However, gRPC is not a silver bullet. It introduces operational complexity — particularly
around Layer 7 load balancing and debugging binary traffic. This guide strips away the
hype and walks through building a production-ready gRPC client and server in Go, complete
with middleware (interceptors) and server-side streaming.

To make the examples concrete and representative of real-world systems, we will build
a three-tier Pharmacy Inventory service:

┌────────────┐     gRPC      ┌──────────────┐     HTTP/JSON     ┌──────────────────┐
│ gRPC Client│ ────────────► │  gRPC Server │ ────────────────► │ REST Inventory   │
│ (consumer) │               │  :50051      │                   │ API  :8080       │
└────────────┘               └──────────────┘                   └──────────────────┘

This architecture is intentionally realistic: the gRPC layer provides a strict,
typed contract to internal consumers, while delegating actual data retrieval to a
REST backend — exactly as you would find in a system that wraps an existing REST
service or third-party API with a high-performance internal interface.

Prerequisites and Workspace Setup

Ensure your development environment is on a current Go release (1.22 or later, as the
examples use the enhanced net/http routing patterns introduced in that version). You
will also need the Protocol Buffers compiler (protoc) and its Go code-generation
plugins.

Install the required Go plugins:

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Initialize your module:

mkdir grpc-inventory
cd grpc-inventory
go mod init github.com/murtuza/grpc-inventory
go get google.golang.org/grpc
go get google.golang.org/protobuf

Project Structure

Before writing any code, it helps to see the layout we are building toward:

grpc-inventory/
├── proto/
│   └── inventory.proto               # Service contract (single source of truth)
├── proto/inventory/
│   ├── inventory.pb.go               # Generated: Protobuf message types
│   └── inventory_grpc.pb.go          # Generated: gRPC service interfaces
├── rest-api/
│   └── main.go                       # REST inventory data layer  (:8080)
├── server/
│   └── main.go                       # gRPC server — calls the REST API (:50051)
├── client/
│   └── main.go                       # gRPC client — consumes the gRPC server
└── go.mod

Step 1: Defining the Strict Contract (Protobuf)

The foundation of any gRPC service is its interface definition. Protobuf acts as a
strict contract between client and server — if the implementations do not match the
.proto file, the code will not compile.

Create proto/inventory.proto:

syntax = "proto3";

package inventory;

option go_package = "github.com/murtuza/grpc-inventory/proto/inventory";

// The Pharmacy Inventory service definition.
service InventoryService {
  // Unary RPC: Fetch a single product's stock level.
  rpc CheckStock (StockRequest) returns (StockResponse);

  // Server-Streaming RPC: Push all items currently running low on stock.
  rpc StreamLowStock (EmptyRequest) returns (stream StockResponse);
}

message EmptyRequest {}

message StockRequest {
  string sku = 1;
}

message StockResponse {
  string sku                   = 1;
  string medicine_name         = 2;
  int32  quantity              = 3;
  bool   requires_prescription = 4;
}

Generate the Go code from the project root:

protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       proto/inventory.proto

This produces two files:

proto/inventory/inventory.pb.go — the generated message structs
proto/inventory/inventory_grpc.pb.go — the generated client stub and server interface > Tip: Commit generated .pb.go files to version control. This makes the schema > auditable in code review and removes the protoc toolchain from your CI build path.

Step 2: The REST Inventory API (Data Layer)

Before building the gRPC server, we need the data source it will call. This REST API
represents the inventory database layer — it could equally be an existing internal
service, a third-party API, or a microservice you do not own.

Create rest-api/main.go:

package main

import (
    "encoding/json"
    "log"
    "net/http"
)

// StockItem mirrors the shape we will return from the REST API.
// The gRPC server will map these fields onto its Protobuf StockResponse.
type StockItem struct {
    SKU                  string `json:"sku"`
    MedicineName         string `json:"medicine_name"`
    Quantity             int    `json:"quantity"`
    RequiresPrescription bool   `json:"requires_prescription"`
}

// inventory is the in-memory data store for this service.
// In production this would be replaced by a database query.
var inventory = map[string]StockItem{
    "MED-001": {SKU: "MED-001", MedicineName: "Amoxicillin 500mg", Quantity: 1450, RequiresPrescription: true},
    "MED-045": {SKU: "MED-045", MedicineName: "Metformin 500mg", Quantity: 320, RequiresPrescription: true},
    "MED-089": {SKU: "MED-089", MedicineName: "Ibuprofen 200mg", Quantity: 12, RequiresPrescription: false},
    "MED-102": {SKU: "MED-102", MedicineName: "Lisinopril 10mg", Quantity: 5, RequiresPrescription: true},
    "MED-201": {SKU: "MED-201", MedicineName: "Cetirizine 10mg", Quantity: 8, RequiresPrescription: false},
}

// lowStockThreshold defines what "low stock" means across the system.
const lowStockThreshold = 50

// writeJSON is a small helper that sets the Content-Type header and encodes
// the provided value as JSON. It writes a 500 if encoding fails.
func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    if err := json.NewEncoder(w).Encode(v); err != nil {
        http.Error(w, `{"error":"encoding failed"}`, http.StatusInternalServerError)
    }
}

// getStock handles GET /api/inventory/{sku}.
// It returns the stock record for a single SKU or 404 if not found.
func getStock(w http.ResponseWriter, r *http.Request) {
    sku := r.PathValue("sku")
    item, ok := inventory[sku]
    if !ok {
        writeJSON(w, http.StatusNotFound, map[string]string{"error": "SKU not found"})
        return
    }
    writeJSON(w, http.StatusOK, item)
}

// getLowStock handles GET /api/inventory/low-stock.
// It returns all items whose quantity falls below lowStockThreshold.
func getLowStock(w http.ResponseWriter, r *http.Request) {
    var items []StockItem
    for _, item := range inventory {
        if item.Quantity < lowStockThreshold {
            items = append(items, item)
        }
    }
    writeJSON(w, http.StatusOK, items)
}

func main() {
    mux := http.NewServeMux()

    // Register the specific /low-stock route BEFORE the wildcard {sku} route.
    // Go 1.22+ ServeMux resolves conflicts by specificity, but explicit ordering
    // makes the intent clear to future maintainers.
    mux.HandleFunc("GET /api/inventory/low-stock", getLowStock)
    mux.HandleFunc("GET /api/inventory/{sku}", getStock)

    log.Println("REST Inventory API listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", mux))
}

Testing the REST API with curl

Start the REST API in one terminal:

go run rest-api/main.go

Then verify each endpoint:

Look up a specific SKU:

curl -s http://localhost:8080/api/inventory/MED-001 | jq .

{
  "sku": "MED-001",
  "medicine_name": "Amoxicillin 500mg",
  "quantity": 1450,
  "requires_prescription": true
}

Fetch all low-stock items (quantity < 50):

curl -s http://localhost:8080/api/inventory/low-stock | jq .

[
  {
    "sku": "MED-089",
    "medicine_name": "Ibuprofen 200mg",
    "quantity": 12,
    "requires_prescription": false
  },
  {
    "sku": "MED-102",
    "medicine_name": "Lisinopril 10mg",
    "quantity": 5,
    "requires_prescription": true
  },
  {
    "sku": "MED-201",
    "medicine_name": "Cetirizine 10mg",
    "quantity": 8,
    "requires_prescription": false
  }
]

Confirm a 404 for an unknown SKU:

curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/inventory/UNKNOWN
# 404

With the data layer verified independently, we can build the gRPC server with
confidence about the shape and behaviour of the API it will consume.

Step 3: The gRPC Server (Calls the REST API)

The gRPC server fulfils the InventoryService contract defined in Protobuf. Rather
than owning any data itself, it translates each incoming gRPC call into a corresponding
HTTP request to the REST API, then maps the JSON response onto a Protobuf message.

A shared http.Client with a connection timeout is created once and reused across all
requests. This is critical — constructing a new http.Client per request bypasses
Go's built-in connection pooling and introduces unnecessary overhead.

Create server/main.go:

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net"
    "net/http"
    "os"
    "time"

    pb "github.com/murtuza/grpc-inventory/proto/inventory"
    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

// restInventoryItem maps the JSON shape returned by the REST API.
type restInventoryItem struct {
    SKU                  string `json:"sku"`
    MedicineName         string `json:"medicine_name"`
    Quantity             int    `json:"quantity"`
    RequiresPrescription bool   `json:"requires_prescription"`
}

// server implements the InventoryServiceServer interface.
// Embedding UnimplementedInventoryServiceServer ensures forward compatibility —
// new RPC methods added to the .proto will not break existing server binaries.
type server struct {
    pb.UnimplementedInventoryServiceServer
    httpClient *http.Client
    apiBaseURL string
}

// newServer constructs a server with a shared HTTP client.
// The REST API base URL is read from the REST_API_URL environment variable,
// defaulting to localhost for local development.
func newServer() *server {
    baseURL := os.Getenv("REST_API_URL")
    if baseURL == "" {
        baseURL = "http://localhost:8080"
    }
    return &server{
        httpClient: &http.Client{Timeout: 10 * time.Second},
        apiBaseURL: baseURL,
    }
}

// fetchItem calls GET /api/inventory/{sku} on the REST API and returns the parsed item.
// It maps HTTP 404 to a gRPC NotFound status so the gRPC client receives a
// well-typed error rather than a raw HTTP error code.
func (s *server) fetchItem(ctx context.Context, sku string) (*restInventoryItem, error) {
    url := fmt.Sprintf("%s/api/inventory/%s", s.apiBaseURL, sku)

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, status.Errorf(codes.Internal, "failed to build request: %v", err)
    }

    resp, err := s.httpClient.Do(req)
    if err != nil {
        return nil, status.Errorf(codes.Unavailable, "REST API unreachable: %v", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode == http.StatusNotFound {
        return nil, status.Errorf(codes.NotFound, "SKU %s not found in inventory", sku)
    }
    if resp.StatusCode != http.StatusOK {
        return nil, status.Errorf(codes.Internal, "REST API returned unexpected status %d", resp.StatusCode)
    }

    var item restInventoryItem
    if err := json.NewDecoder(resp.Body).Decode(&item); err != nil {
        return nil, status.Errorf(codes.Internal, "failed to decode REST response: %v", err)
    }
    return &item, nil
}

// fetchLowStock calls GET /api/inventory/low-stock and returns all matching items.
func (s *server) fetchLowStock(ctx context.Context) ([]restInventoryItem, error) {
    url := fmt.Sprintf("%s/api/inventory/low-stock", s.apiBaseURL)

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, status.Errorf(codes.Internal, "failed to build request: %v", err)
    }

    resp, err := s.httpClient.Do(req)
    if err != nil {
        return nil, status.Errorf(codes.Unavailable, "REST API unreachable: %v", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, status.Errorf(codes.Internal, "REST API returned unexpected status %d", resp.StatusCode)
    }

    var items []restInventoryItem
    if err := json.NewDecoder(resp.Body).Decode(&items); err != nil {
        return nil, status.Errorf(codes.Internal, "failed to decode REST response: %v", err)
    }
    return items, nil
}

// CheckStock is a Unary RPC. It fetches a single SKU from the REST API and
// returns the result as a typed Protobuf message.
func (s *server) CheckStock(ctx context.Context, req *pb.StockRequest) (*pb.StockResponse, error) {
    item, err := s.fetchItem(ctx, req.GetSku())
    if err != nil {
        return nil, err // already a gRPC status error
    }
    return &pb.StockResponse{
        Sku:                  item.SKU,
        MedicineName:         item.MedicineName,
        Quantity:             int32(item.Quantity),
        RequiresPrescription: item.RequiresPrescription,
    }, nil
}

// StreamLowStock is a Server-Streaming RPC. It fetches all low-stock items from
// the REST API in a single call, then streams each one to the client individually.
func (s *server) StreamLowStock(_ *pb.EmptyRequest, stream pb.InventoryService_StreamLowStockServer) error {
    items, err := s.fetchLowStock(stream.Context())
    if err != nil {
        return err
    }

    for _, item := range items {
        // Respect client cancellation between sends.
        if err := stream.Context().Err(); err != nil {
            return status.Errorf(codes.Canceled, "client disconnected: %v", err)
        }

        if err := stream.Send(&pb.StockResponse{
            Sku:                  item.SKU,
            MedicineName:         item.MedicineName,
            Quantity:             int32(item.Quantity),
            RequiresPrescription: item.RequiresPrescription,
        }); err != nil {
            return err
        }
    }
    return nil
}

// loggingInterceptor is Unary middleware that records the method, duration,
// and outcome of every incoming RPC call.
func loggingInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (interface{}, error) {
    start := time.Now()
    h, err := handler(ctx, req)
    log.Printf("[RPC] method=%s duration=%s err=%v", info.FullMethod, time.Since(start), err)
    return h, err
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }

    // ChainUnaryInterceptor composes multiple interceptors cleanly.
    // Add authInterceptor, recoveryInterceptor, etc. here as the service grows.
    s := grpc.NewServer(
        grpc.ChainUnaryInterceptor(loggingInterceptor),
    )

    pb.RegisterInventoryServiceServer(s, newServer())

    log.Printf("Inventory gRPC server listening at %v", lis.Addr())
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

Step 4: The gRPC Client

The client connects to the gRPC server and exercises both RPC patterns — a unary call
and a server-streaming call.

The traditional grpc.Dial is deprecated in modern versions of grpc-go. Its
replacement, grpc.NewClient, provides a more robust API and establishes the underlying
connection lazily on the first RPC call rather than at construction time.

Create client/main.go:

package main

import (
    "context"
    "io"
    "log"
    "time"

    pb "github.com/murtuza/grpc-inventory/proto/inventory"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

func main() {
    // grpc.NewClient does not block — the connection is established lazily.
    // For production, replace insecure.NewCredentials() with a TLS config.
    conn, err := grpc.NewClient(
        "localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        log.Fatalf("could not create client: %v", err)
    }
    defer conn.Close()

    c := pb.NewInventoryServiceClient(conn)

    testUnaryCall(c)
    testStreamingCall(c)
}

func testUnaryCall(c pb.InventoryServiceClient) {
    // A deadline context is essential for unary calls. Without one, a slow or
    // unresponsive server will block the caller indefinitely.
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    log.Println("--- Executing Unary RPC ---")
    r, err := c.CheckStock(ctx, &pb.StockRequest{Sku: "MED-001"})
    if err != nil {
        log.Fatalf("CheckStock failed: %v", err)
    }
    log.Printf("Stock check -> %s: %d units (prescription required: %t)",
        r.GetMedicineName(), r.GetQuantity(), r.GetRequiresPrescription())
}

func testStreamingCall(c pb.InventoryServiceClient) {
    log.Println("\n--- Executing Server-Streaming RPC ---")

    // A deadline is equally important on streaming calls. Use context.WithCancel
    // if you need to abort the stream from the client side based on your own logic.
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    stream, err := c.StreamLowStock(ctx, &pb.EmptyRequest{})
    if err != nil {
        log.Fatalf("StreamLowStock failed: %v", err)
    }

    for {
        item, err := stream.Recv()
        if err == io.EOF {
            // The server closed the stream normally.
            break
        }
        if err != nil {
            log.Fatalf("error receiving from stream: %v", err)
        }
        log.Printf("ALERT: Low stock -> %s (SKU: %s) has only %d units remaining.",
            item.GetMedicineName(), item.GetSku(), item.GetQuantity())
    }
    log.Println("--- Stream complete ---")
}

Step 5: Running the Full Stack

The three services run independently. Open three terminals from the project root.

Terminal 1 — Start the REST API:

go run rest-api/main.go
# REST Inventory API listening on :8080

Terminal 2 — Start the gRPC server:

go run server/main.go
# Inventory gRPC server listening at [::]:50051

Terminal 3 — Run the gRPC client:

go run client/main.go

Expected client output:

--- Executing Unary RPC ---
Stock check -> Amoxicillin 500mg: 1450 units (prescription required: true)

--- Executing Server-Streaming RPC ---
ALERT: Low stock -> Ibuprofen 200mg (SKU: MED-089) has only 12 units remaining.
ALERT: Low stock -> Lisinopril 10mg (SKU: MED-102) has only 5 units remaining.
ALERT: Low stock -> Cetirizine 10mg (SKU: MED-201) has only 8 units remaining.
--- Stream complete ---

Meanwhile, Terminal 2 (the gRPC server) will emit interceptor logs for each call:

[RPC] method=/inventory.InventoryService/CheckStock duration=2.1ms err=<nil>
[RPC] method=/inventory.InventoryService/StreamLowStock duration=1.8ms err=<nil>

Configuring the REST API URL

The gRPC server reads its upstream address from the REST_API_URL environment
variable, which defaults to http://localhost:8080 if unset. To point it at a
different host (e.g. in a Docker Compose network):

REST_API_URL=http://inventory-api:8080 go run server/main.go

Step 6: Debugging Binary Traffic with grpcurl

One of gRPC's stated drawbacks is that binary Protobuf payloads are opaque to
standard HTTP tools like curl. The idiomatic solution is
grpcurl — a command-line tool that
speaks gRPC natively, playing the same role curl plays for REST APIs.

Install it:

go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

To use grpcurl without a .proto file, enable server reflection by adding two
lines to server/main.go:

import "google.golang.org/grpc/reflection"

// Inside main(), after pb.RegisterInventoryServiceServer:
reflection.Register(s)

Security note: Only enable reflection in development and staging environments.
Exposing your full service schema in production is an unnecessary attack surface.

With reflection running, you can introspect and invoke your service from the terminal,
in exactly the same workflow as curl + a REST API:

# List all available services
grpcurl -plaintext localhost:50051 list

# Describe the full InventoryService schema
grpcurl -plaintext localhost:50051 describe inventory.InventoryService

# Call CheckStock (unary)
grpcurl -plaintext \
  -d '{"sku": "MED-001"}' \
  localhost:50051 inventory.InventoryService/CheckStock

# Stream low-stock alerts (server-streaming)
grpcurl -plaintext \
  -d '{}' \
  localhost:50051 inventory.InventoryService/StreamLowStock

Production Considerations

TLS

The examples above use insecure.NewCredentials(), transmitting data in plaintext.
For any non-local deployment, use mutual TLS (mTLS):

// Server-side
creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")
s := grpc.NewServer(grpc.Creds(creds), ...)

// Client-side
creds, err := credentials.NewClientTLSFromFile("ca.crt", "")
conn, err := grpc.NewClient("host:50051", grpc.WithTransportCredentials(creds))

Chaining Multiple Interceptors

Real services need more than logging. Authentication, rate limiting, and panic recovery
are all common interceptor concerns. grpc.ChainUnaryInterceptor composes them
without nesting:

s := grpc.NewServer(
    grpc.ChainUnaryInterceptor(
        loggingInterceptor,
        authInterceptor,
        recoveryInterceptor,
    ),
    grpc.ChainStreamInterceptor(
        streamLoggingInterceptor,
    ),
)

grpc.UnaryInterceptor only accepts a single function and panics if called more
than once — always prefer ChainUnaryInterceptor in production code.

HTTP Client Timeouts

The gRPC server's http.Client is configured with a 10-second timeout, but you
may want to tune this per-call using the incoming gRPC context directly, so that
a client's deadline propagates end-to-end:

// Pass the gRPC call context into the downstream HTTP request.
// If the gRPC client cancels, the REST API call is cancelled too.
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)

This pattern is already used in the server code above and prevents a situation where
a gRPC client times out but the REST API call continues to consume resources on the
server.

Architectural Realities: When (and When Not) to Use gRPC

While gRPC's performance characteristics are compelling, engineering is about
trade-offs.

Where gRPC Excels

Polyglot microservices. If your backend spans Go, Rust, Python, and Node.js,
Protobuf generates idiomatic client libraries for all of them from a single .proto
source of truth — with no per-language schema drift.

High-throughput internal APIs. Binary serialization is measurably faster to encode
and decode than JSON, and Protobuf payloads are significantly smaller over the wire —
particularly important at high request volumes.

Strict typing as a contract. Runtime errors caused by a misspelled JSON field
become a compile-time failure. The contract is enforced at build time, not discovered
in production.

Bidirectional streaming. gRPC supports client streaming, server streaming, and
full-duplex bidirectional streaming out of the box — capabilities that require
WebSockets or SSE to replicate in a REST architecture.

The Pragmatic Drawbacks

Layer 7 load balancing. Because gRPC multiplexes requests over long-lived HTTP/2
TCP connections, standard L4 load balancers (such as AWS NLB or a default Kubernetes
Service) will funnel all traffic from a single client pod to one server pod,
defeating horizontal scaling. You must front gRPC services with an L7 proxy — Envoy,
NGINX, or a full service mesh like Istio — to distribute load at the request level.

Browser incompatibility. Web browsers cannot natively initiate the HTTP/2
connections gRPC requires. Calling a gRPC service from a browser requires grpc-web
and an Envoy proxy as a translation layer. If your primary consumers are web or mobile
frontends, REST or GraphQL is architecturally simpler.

Operational tooling curve. Teams accustomed to curl, Postman, and browser
DevTools will need to adopt grpcurl or Postman's gRPC mode. Binary traffic is
invisible without the right tools in place — which is precisely why the grpcurl
section above is not optional reading.

Summary

This guide built a realistic three-tier system: a REST data layer verified directly
with curl, a gRPC server that calls it, and a typed gRPC client that consumes the
result. Each tier can be developed, tested, and debugged in isolation — the REST API
with curl, and the gRPC surface with grpcurl.

gRPC in Go provides a robust foundation for enterprise-grade internal services, but it
should be adopted rationally. Use it where strict contracts, low latency, and efficient
serialization are genuine architectural requirements — not merely because it is the
current industry trend.

The full source code for this tutorial is available at
github.com/mmurtuza/grpc-inventory.

Engineering is best when shared. Find more of my writing, projects, and work at -- murtuza.dev

Laravel 13 Deep Dive: Every New Feature, Change with Code Example

Md Murtuza Hussain — Tue, 10 Mar 2026 19:06:27 +0000

The Laravel ecosystem is moving at lightning speed, and Laravel 13—scheduled for release on March 17, 2026—is shaping up to be one of the most refined updates yet. Officially presented by Taylor Otwell at Laracon EU, Laravel 13 doesn't aim to reinvent the wheel or introduce massive breaking changes. Instead, it focuses heavily on developer experience (DX), modern PHP 8.3 features, and quality-of-life improvements.

If you're wondering what's changing and how to use the new features, you're in the right place. Let's dive deep into everything coming in Laravel 13, complete with practical code examples.

1. The Great PHP Attributes Overhaul

The absolute headline feature of Laravel 13 is the profound, framework-wide adoption of PHP 8 Attributes. Historically, Laravel components (Models, Jobs, Commands) were configured using protected properties. Now, you can configure almost everything using clean, declarative attributes right above your class declarations.

*Note: This is a 100% additive, non-breaking change. If you prefer the old property-based approach, it will continue to work perfectly! *

Eloquent Models

You can now define your table names, hidden attributes, fillable attributes, and more without cluttering the inside of your class.

Before (Laravel 12):

class User extends Model
{
    protected $table = 'system_users';
    protected $primaryKey = 'user_id';
    public $incrementing = false;
    protected $keyType = 'string';

    protected $fillable = ['name', 'email'];
    protected $hidden = ['password', 'remember_token'];
}

After (Laravel 13):

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Attributes\Table;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;

#[Table('system_users', key: 'user_id', keyType: 'string', incrementing: false)]
#[Fillable(['name', 'email'])]
#[Hidden(['password', 'remember_token'])]
class User extends Model
{
    // The class body is beautifully empty!
}

Available model attributes in Laravel 13 include: #[Appends], #[Connection], #[Guarded], #[Touches], #[Unguarded], and #[Visible].

Queue Jobs

Queue configuration translates perfectly to attributes. Instead of public properties that feel disconnected from the class signature, you declare the configuration at the top.

Laravel 13 Job Example:

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Queue;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Queue\Attributes\Backoff;

#[Connection('redis')]
#[Queue('long_running_tasks')]
#[Tries(5)]
#[Timeout(120)]
#[Backoff([10, 30, 60])] // Retry after 10s, then 30s, then 60s
class ProcessPodcast implements ShouldQueue
{
    public function handle()
    {
        // Process the heavy lifting...
    }
}

Console Commands

Artisan commands are getting the attribute treatment as well. You no longer need to define $signature and $description properties.

use Illuminate\Console\Command;
use Illuminate\Console\Attributes\Signature;
use Illuminate\Console\Attributes\Description;

#[Signature('reports:generate {user} {--queue}')]
#[Description('Generate a monthly analytics report for a specific user.')]
class GenerateReportCommand extends Command
{
    public function handle()
    {
        $user = $this->argument('user');
        // ...
    }
}

Other Framework Components

Attributes are spreading everywhere:

Form Requests: #[RedirectTo('/dashboard')] or #[StopOnFirstFailure]
API Resources: #[Collects(User::class)] or #[PreserveKeys]
Factories and Seeders: #[UseModel(User::class)] or #[Seed]

2. The `Cache::touch()` Method

A massive performance win for high-traffic applications is the introduction of Cache::touch().

Previously, if you wanted to extend the Time-To-Live (TTL) of a cached item, you had to retrieve the payload from the cache store and then PUT it back. This resulted in unnecessary memory usage and network transfer, especially for large cached objects.

Laravel 13 bypasses this completely by utilizing native cache store commands (like Redis EXPIRE or Memcached TOUCH).

The Old Way (Slow):

// Grabs the whole payload over the network
$payload = Cache::get('heavy_analytics_dashboard'); 

// Sends the whole payload back over the network
Cache::put('heavy_analytics_dashboard', $payload, now()->addHours(6));

The Laravel 13 Way (Blazing Fast):

use Illuminate\Support\Facades\Cache;

// Simply extends the TTL without fetching the payload!
Cache::touch('heavy_analytics_dashboard', now()->addHours(6));

// You can also pass seconds:
Cache::touch('user_session:123', 3600);

// Or extend indefinitely:
Cache::touch('permanent_report', null);

Note: Cache::touch() returns true on success and false if the key doesn't exist.

3. Laravel Reverb: The Database Driver

Laravel Reverb brought blistering-fast first-party WebSockets to the ecosystem. However, to scale Reverb horizontally across multiple servers, you previously had to use Redis to manage the Pub/Sub messaging between nodes.

In Laravel 13, Reverb introduces a Database Driver. If you are building a small-to-medium application and want to avoid the infrastructure cost and complexity of spinning up a dedicated Redis instance, you can now use your existing MySQL or PostgreSQL database to scale real-time features!

# In your .env file
REVERB_CONNECTION=database

This lowers the barrier to entry for highly scalable, real-time Laravel apps.

4. Starter Kits: First-Class Teams & Native Passkeys

Built-in Teams capabilities

If you run a SaaS, you know the pain of building a multi-tenant "Teams" system. Previously, it was tied specifically to Jetstream. In Laravel 13, the official Starter Kits are reintroducing vastly improved, native Teams functionality. This will allow users to simultaneously act on behalf of different teams via distinct URLs (even in different browser tabs) without encountering session conflicts.

Native Passkey Authentication

WebAuthn (Passkeys) is natively integrated directly into Laravel Fortify and the Starter Kits. Your users can securely log in via Face ID, Touch ID, or hardware security keys out-of-the-box, letting you ditch complex, third-party WebAuthn packages.

5. Granular Job Queue Control

Laravel 13 introduces more granular control over failing jobs, specifically with the maxExceptions configuration. If a job interacts with an unstable third-party API, you can now specify exactly how many exceptions are allowed before the job entirely fails, giving you tighter control over your retry thresholds.

use Illuminate\Queue\Attributes\MaxExceptions;

#[MaxExceptions(3)] // Fails permanently if it throws 3 exceptions!
class SyncWithUnstableApi implements ShouldQueue
{
    // ...
}

6. The Laravel AI SDK Reaches Stable

First introduced as a beta, the Laravel AI SDK will officially be marked as stable with the release of Laravel 13.

This SDK acts as an official, elegant wrapper around providers like Anthropic, OpenAI, and Google Gemini. It gives you a fluent, Eloquent-like syntax for interacting with Large Language Models, allowing you to easily build AI capabilities into your app without worrying about the underlying provider's HTTP API.

7. Under the Hood: PHP 8.3 and Default Concurrency

While the DX improvements are front and center, Laravel 13 brings the heat under the hood as well:

PHP 8.3 Minimum Requirement: It's time to upgrade! Laravel 13 drops support for PHP 8.2. You must be on PHP 8.3+, ensuring the framework can fully leverage typed class constants, dynamic class constant fetches, and new standard library functions.
Symfony 7.4 & 8.0 Foundation: The underlying Symfony components have been bumped, securing the framework well into the future.
HTTP Client Concurrency: Http::pool() now defaults to a concurrency level of 2, meaning bulk API requests via the pool will execute concurrently out of the box without any extra configuration.

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Pool;

// Executes concurrently automatically in Laravel 13!
$responses = Http::pool(fn (Pool $pool) => [
    $pool->get('https://api.example.com/endpoint-1'),
    $pool->get('https://api.example.com/endpoint-2'),
]);

Conclusion & Upgrade Timeline

Laravel 13 is the definition of a mature framework: zero breaking changes to your application code, additive DX features, and deep performance optimizations.

Important Dates:

Release Date: March 17, 2026
Bug Fixes: Supported until Q3 2027
Security Fixes: Supported until Q1 2028

The upgrade path will be exceptionally smooth. Whether you adopt the new PHP attributes immediately or stick with properties, Laravel 13 is ready to push the ecosystem forward. Start preparing your servers for PHP 8.3 today!

Engineering is best when shared. Find more of my writing, projects, and work at -- murtuza.dev

How to Build an Enterprise-Grade App with Laravel 12 & React (Clean Architecture)

Md Murtuza Hussain — Tue, 10 Mar 2026 05:33:27 +0000

Building an application that scales efficiently from a few hundred users to hundreds of thousands is a complex challenge. Many developers start by placing all their business logic directly into controllers. While this allows for rapid prototyping, it quickly transforms the application into a ticking time bomb of technical debt.

Clean Architecture is the solution.

Clean architecture is a software engineering philosophy that separates your code into distinct, isolated layers. This separation of concerns ensures that your application remains highly testable, independent of underlying frameworks (like your database or UI), and incredibly easy to maintain as it grows.

In this comprehensive tutorial, we are going to build a high-performance, enterprise-grade application using Laravel 12 for the backend and React (with TypeScript) for the frontend. We will walk through building full CRUD (Create, Read, Update, Delete) operations, implementing Database Transactions to prevent data corruption, configuring Policies and Gates for authorization, and exploring every essential layer of Laravel's architecture.

The Architecture Diagram & Request Lifecycle

Before we write any code, it is critical to understand the architecture we are building. In a traditional MVC app, a Controller handles the request, talks to the Model, and returns the View. In Clean Architecture, we introduce intermediate layers to isolate logic.

Here is the exact lifecycle of an HTTP Request in our enterprise backend:

[HTTP Request]
      │
      ▼
1. [Route Definition] (routes/api.php)
      │
      ▼
2. [Middleware] (Sanctum Authentication)
      │
      ▼
3. [Gate / Policy] (Authorization - Can the user do this?)
      │
      ▼
4. [Form Request] (Validation - Is the data correct?)
      │
      ▼
5. [Controller] (The Traffic Cop - Routes data, contains NO logic)
      │
      ▼
6. [Service Layer] (Business Logic & Database Transactions)
      │      └─▶ [Event Dispatcher] (Asynchronous side-effects like emails)
      ▼
7. [Repository Layer] (Abstracts the Database/ORM queries)
      │
      ▼
8. [Database] (MySQL / Postgres)
      │
      ▼
   (Data flows back up through the layers)
      │
      ▼
9. [API Resource] (Transforms internal Models into strictly typed JSON)
      │
      ▼
[HTTP Response]

The Directory Structure

By the end of this tutorial, our backend folder structure will look like this, separating every concern into its own domain:

app/
├── Events/
│   └── OrderCreated.php           # Holds simple event data
├── Http/
│   ├── Controllers/
│   │   └── OrderController.php    # Handles HTTP transport only
│   ├── Requests/
│   │   ├── StoreOrderRequest.php  # Validates incoming POST data
│   │   └── UpdateOrderRequest.php # Validates incoming PUT data
│   └── Resources/
│       └── OrderResource.php      # Formats the outgoing JSON
├── Listeners/
│   └── SendOrderNotification.php  # Handles background tasks (e.g. Emails)
├── Models/
│   ├── Order.php                  # Eloquent Database Model
│   └── User.php
├── Policies/
│   └── OrderPolicy.php            # Model-specific security rules
├── Providers/
│   ├── AppServiceProvider.php     # Global security Gates
│   └── RepositoryServiceProvider.php # Binds Repository Interfaces
├── Repositories/
│   ├── Contracts/
│   │   └── OrderRepositoryInterface.php # The strict contract
│   └── Eloquent/
│       └── OrderRepository.php    # The actual database queries
└── Services/
    └── OrderService.php           # Complex business logic & DB Transactions

The Backend: Laravel 12 Clean Architecture

We are building a scalable Order management backend. Let's build it layer by layer, scaffolding the files using Artisan as we go.

1. Model & Database Setup

Before writing logic, we need our database schema. Laravel makes this effortless. We use Artisan to generate our Model, Migration, Factory, and a Controller wired up for an API.

laravel new enterprise-app --api
cd enterprise-app

# Generate the Model, Migration, Factory, and Controller (API mode)
php artisan make:model Order -mfc --api

2. Routes (`routes/api.php`)

We define our endpoints using apiResource. This instantly wires up all standard CRUD routes (index, show, store, update, destroy) without cluttering the routing file.

use App\Http\Controllers\OrderController;
use Illuminate\Support\Facades\Route;

Route::apiResource('orders', OrderController::class);

3. Policies & Gates (Authorization)

In an enterprise application, you must never assume an authenticated user is allowed to perform an action. We use Gates for global, application-wide rules (e.g., "Is this an admin?") and Policies for model-specific rules (e.g., "Does this user own this specific order?").

# Generate a Policy for our Order model
php artisan make:policy OrderPolicy --model=Order

The Global Gate (AppServiceProvider):

// app/Providers/AppServiceProvider.php
namespace App\Providers;

use Illuminate\Support\Facades\Gate;
use Illuminate\Support\ServiceProvider;
use App\Models\User;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Global Gate: Only admins can delete anything across the system
        Gate::define('delete-records', function (User $user): bool {
            return $user->role === 'admin';
        });
    }
}

The Model Policy:

// app/Policies/OrderPolicy.php
namespace App\Policies;

use App\Models\Order;
use App\Models\User;

class OrderPolicy
{
    // Model-specific Policy: Users can only view their own orders
    public function view(User $user, Order $order): bool
    {
        return $user->id === $order->user_id;
    }
}

4. Form Requests (Validation)

Never put validation logic directly in your controller. We intercept the incoming HTTP request using Form Requests. This ensures that the controller and business logic layers only ever receive sanitized, correct data.

# Generate Form Requests for validation
php artisan make:request StoreOrderRequest
php artisan make:request UpdateOrderRequest

The Store Request:

// App\Http\Requests\StoreOrderRequest.php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreOrderRequest extends FormRequest
{
    public function authorize(): bool 
    { 
        return true; // We delegate authorization to Policies and Controllers
    }

    public function rules(): array
    {
        return [
            'product_id' => 'required|exists:products,id',
            'quantity' => 'required|integer|min:1',
            'customer_email' => 'required|email',
        ];
    }
}

5. The Repository Pattern (Data Access Layer)

The Repository Pattern abstracts the database layer entirely. By writing queries in a repository rather than a controller, we decouple our business logic from Eloquent. If you need to switch databases, optimize a complex select query, or mock the database for testing, you alter one repository file instead of hunting through dozens of services.

# Repositories aren't native Artisan stubs, so we make the folders manually:
mkdir app/Repositories app/Repositories/Contracts app/Repositories/Eloquent

# Generate a Service Provider to bind our Repositories to Laravel's Container
php artisan make:provider RepositoryServiceProvider

Note: Make sure to register your RepositoryServiceProvider in bootstrap/providers.php in Laravel 12.

The Interface (The Contract):

// App\Repositories\Contracts\OrderRepositoryInterface.php
namespace App\Repositories\Contracts;

use Illuminate\Pagination\LengthAwarePaginator;
use App\Models\Order;

interface OrderRepositoryInterface
{
    public function getPaginated(int $perPage = 15): LengthAwarePaginator;
    public function findById(int $id): ?Order;
    public function create(array $data): Order;
    public function update(int $id, array $data): bool;
    public function delete(int $id): bool;
}

The Concrete Implementation (The Eloquent Queries):

// App\Repositories\Eloquent\OrderRepository.php
namespace App\Repositories\Eloquent;

use App\Models\Order;
use App\Repositories\Contracts\OrderRepositoryInterface;
use Illuminate\Pagination\LengthAwarePaginator;

class OrderRepository implements OrderRepositoryInterface
{
    public function getPaginated(int $perPage = 15): LengthAwarePaginator 
    { 
        return Order::paginate($perPage); 
    }

    public function findById(int $id): ?Order 
    { 
        return Order::findOrFail($id); 
    }

    public function create(array $data): Order 
    { 
        return Order::create($data); 
    }

    public function update(int $id, array $data): bool 
    { 
        return (bool) Order::whereId($id)->update($data); 
    }

    public function delete(int $id): bool 
    { 
        return (bool) Order::destroy($id); 
    }
}

The Service Provider binding:
We must tell Laravel: "Whenever a class demands the OrderRepositoryInterface, inject the concrete OrderRepository".

// App\Providers\RepositoryServiceProvider.php
namespace App\Providers;

use App\Repositories\Contracts\OrderRepositoryInterface;
use App\Repositories\Eloquent\OrderRepository;
use Illuminate\Support\ServiceProvider;

class RepositoryServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(OrderRepositoryInterface::class, OrderRepository::class);
    }
}

6. The Service Class (Business Logic & Transactions)

This is the heart of the application. The Service Class is responsible for all complex business rules. Furthermore, we use Database Transactions here to ensure data integrity.

When creating an order, if the database insert succeeds but a subsequent step (like generating an invoice) fails and throws an exception, you do not want an orphaned order in your database. A DB::transaction() ensures that if anything fails within the closure, the entire database transaction rolls back instantly.

# Services aren't native Artisan stubs either, so we create the folder
mkdir app/Services

The Service Class:

// App\Services\OrderService.php
namespace App\Services;

use App\Repositories\Contracts\OrderRepositoryInterface;
use App\Events\OrderCreated;
use Illuminate\Support\Facades\DB;
use Illuminate\Pagination\LengthAwarePaginator;
use App\Models\Order;
use Exception;

class OrderService
{
    // We inject the interface, not the concrete class, for maximum testability.
    public function __construct(protected OrderRepositoryInterface $orderRepository) {}

    public function getOrders(): LengthAwarePaginator 
    { 
        return $this->orderRepository->getPaginated(); 
    }

    public function getOrder(int $id): ?Order 
    { 
        return $this->orderRepository->findById($id); 
    }

    public function processNewOrder(array $validatedData): Order
    {
        return DB::transaction(function () use ($validatedData): Order {
            // 1. Calculate prices, apply discounts, run complex logic...
            $validatedData['total'] = $validatedData['quantity'] * 100; // Mock calculation

            // 2. Persist to DB using the Repository
            $order = $this->orderRepository->create($validatedData);

            // 3. Fire domain events 
            OrderCreated::dispatch($order);

            return $order;
        }); // If an exception is thrown inside this closure, the DB rolls back automatically.
    }

    public function updateOrder(int $id, array $validatedData): ?Order
    {
        return DB::transaction(function () use ($id, $validatedData): ?Order {
            $this->orderRepository->update($id, $validatedData);
            return $this->orderRepository->findById($id);
        });
    }

    public function deleteOrder(int $id): bool
    {
        return DB::transaction(function () use ($id): bool {
            return $this->orderRepository->delete($id);
        });
    }
}

7. Events & Listeners (Asynchronous Side-Effects)

To keep the main HTTP thread as fast as possible, side effects such as sending emails or generating PDFs should be decoupled from the core business logic. We dispatch an Event, and a Listener handles the logic in a background queue.

# Generate Events and Listeners in a single shot
php artisan make:event OrderCreated
php artisan make:listener SendOrderNotification --event=OrderCreated

The Event (A simple data transfer object):

// App\Events\OrderCreated.php
namespace App\Events;

use App\Models\Order;
use Illuminate\Foundation\Events\Dispatchable;

class OrderCreated 
{
    use Dispatchable;

    public function __construct(public Order $order) {}
}

The Listener (The background worker):

// App\Listeners\SendOrderNotification.php
namespace App\Listeners;

use App\Events\OrderCreated;
use Illuminate\Contracts\Queue\ShouldQueue; // Implementing this moves the listener to a queue
use Illuminate\Support\Facades\Log;

class SendOrderNotification implements ShouldQueue 
{
    public function handle(OrderCreated $event): void 
    {
        // Simulating sending an email asynchronously
        Log::info("Email queued for order: {$event->order->id}");
    }
}

8. API Resources (The Presentation Layer)

Returning Eloquent models directly to the frontend is dangerous; you risk exposing hidden database columns or internal IDs. API Resources allow you to strictly define the JSON contract your frontend will receive, and allows you to format dates or combine names safely.

# Generate API Resources for presentation
php artisan make:resource OrderResource

The Resource Class:

// App\Http\Resources\OrderResource.php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'total_amount' => $this->total,
            'status' => $this->status ?? 'pending',
            'ordered_at' => $this->created_at->format('Y-m-d H:i:s'),
        ];
    }
}

9. The Controller (The Traffic Cop)

Our controller handles the entire CRUD lifecycle and Authorization, yet it remains completely devoid of logic. It only exists to receive the request, defer to permissions via Gates, hand off valid data to the Service class, and return the formatted Resource.

// App\Http\Controllers\OrderController.php
namespace App\Http\Controllers;

use App\Http\Requests\StoreOrderRequest;
use App\Http\Requests\UpdateOrderRequest;
use App\Services\OrderService;
use App\Http\Resources\OrderResource;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Gate;
use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;

class OrderController extends Controller implements HasMiddleware
{
    public function __construct(protected OrderService $orderService) {}

    // Apply Sanctum auth middleware to the entire controller using Laravel 11/12 syntax
    public static function middleware(): array
    {
        return [new Middleware('auth:sanctum')];
    }

    public function index(): AnonymousResourceCollection
    {
        return OrderResource::collection($this->orderService->getOrders());
    }

    public function store(StoreOrderRequest $request): OrderResource
    {
        $order = $this->orderService->processNewOrder($request->validated());
        return new OrderResource($order);
    }

    public function show(int $id): OrderResource
    {
        $order = $this->orderService->getOrder($id);

        // Authorization via Policy! Will throw a 403 Forbidden if false.
        Gate::authorize('view', $order);

        return new OrderResource($order);
    }

    public function update(UpdateOrderRequest $request, int $id): OrderResource
    {
        $order = $this->orderService->updateOrder($id, $request->validated());
        return new OrderResource($order);
    }

    public function destroy(int $id): JsonResponse
    {
        // Global Gate Authorization Check (Admin only)
        Gate::authorize('delete-records');

        $this->orderService->deleteOrder($id);
        return response()->json(['message' => 'Order deleted successfully'], 204);
    }
}

10. Authentication (Bearer Tokens)

For an SPA, we use Laravel Sanctum to issue Bearer Tokens, which will be sent in the Authorization header of our Axios requests. This avoids the CORS wildcard issues often encountered with cookie-based sessions.

app/Http/Controllers/AuthController.php:

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Http\JsonResponse;

class AuthController extends Controller
{
    public function login(Request $request): JsonResponse
    {
        if (!Auth::attempt($request->validate(['email' => 'required|email', 'password' => 'required']))) {
            return response()->json(['message' => 'Invalid credentials'], 401);
        }

        $token = Auth::user()->createToken('auth_token')->plainTextToken;

        return response()->json([
            'access_token' => $token,
            'token_type' => 'Bearer',
            'user' => Auth::user()
        ]);
    }
}

The Frontend: React & TypeScript Clean Architecture

The Frontend also benefits tremendously from Clean Architecture. Rather than combining UI state, URL endpoints, and HTTP request logic in one bloated React Component file, we will abstract our entire data layer using TypeScript.

The React Architecture Diagram

Our frontend request lifecycle isolates the UI from the network, preventing components from knowing how data is fetched:

[User Interaction] (e.g., Clicks "Delete Order")
      │
      ▼
1. [UI Component] (src/components/OrderList.tsx)
      │      (Fires a mutation function provided by the Hook. It knows NOTHING about Axios.)
      ▼
2. [Custom Hook / Application Layer] (src/hooks/useOrders.ts)
      │      (React Query manages the loading state, caching, error catching, and success toasts.)
      ▼
3. [API Service / Data Layer] (src/api/services/orderService.ts)
      │      (Constructs the Axios request and defines the exact URL and Payload.)
      ▼
4. [Backend API] (Laravel 12)

The React Directory Structure

By adhering to Clean Architecture, our React src/ folder organically separates concerns:

src/
├── api/
│   ├── client.ts                  # The Axios instance (Base URLs, Interceptors)
│   ├── services/
│   │   └── orderService.ts        # Pure functions returning Promises
│   └── types/
│       └── order.ts               # Strict TypeScript interfaces matching the Backend Resources
├── components/
│   └── OrderList.tsx              # Pure UI elements rendering data 
├── hooks/
│   └── useOrders.ts               # React Query wrappers tying the UI to the Services
└── pages/                         # (If using Next.js/React Router) Top level route containers

1. The API Client & Interceptors

To avoid CORS wildcard issues, we configure our Axios client strictly for Bearer Tokens and do not use withCredentials. We'll receive the token from the login payload and inject it globally into Axios.

src/api/client.ts:

import axios from 'axios';

export const apiClient = axios.create({
    baseURL: 'http://localhost:8001',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    },
});

2. Types & Service Layer

We define strict TypeScript Interfaces to map exactly to the data provided by our backend's API Resource. We then create a central API service to abstract the actual Axios/Fetch calls.

TypeScript Interfaces:

// src/api/types/order.ts
export interface Order { 
    id: number; 
    total_amount: number; 
    status: string; 
    ordered_at: string;
}

export interface OrderPayload { 
    product_id: number; 
    quantity: number; 
    customer_email: string; 
}

The Data Service:
This service file centralizes our endpoints. If the backend URL structure changes, we only need to update this single file.

// src/api/services/orderService.ts
import apiClient from '../client';
import { Order, OrderPayload } from '../types/order';

export const orderApi = {
    getAll: async (page = 1): Promise<{ data: Order[], meta: any }> => {
        const res = await apiClient.get(`/orders?page=${page}`);
        return res.data;
    },

    getOne: async (id: number): Promise<Order> => {
        const res = await apiClient.get<{ data: Order }>(`/orders/${id}`);
        return res.data.data;
    },

    create: async (payload: OrderPayload): Promise<Order> => {
        const res = await apiClient.post<{ data: Order }>('/orders', payload);
        return res.data.data;
    },

    update: async (id: number, payload: Partial<OrderPayload>): Promise<Order> => {
        const res = await apiClient.put<{ data: Order }>(`/orders/${id}`, payload);
        return res.data.data;
    },

    delete: async (id: number): Promise<void> => {
        await apiClient.delete(`/orders/${id}`);
    }
};

3. Custom Hooks (React Query)

Managing loading states, caching, and error handling manually is tedious. We wrap our data service in a Custom Hook using React Query.

The Application Layer Hook:

// src/hooks/useOrders.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { orderApi } from '../api/services/orderService';
import { Order, OrderPayload } from '../api/types/order';
import { toast } from 'react-hot-toast';

export const useOrders = (page = 1) => {
    const queryClient = useQueryClient();

    const query = useQuery<{ data: Order[], meta: any }, Error>({ 
        queryKey: ['orders', page], 
        queryFn: () => orderApi.getAll(page) 
    });

    const createMutation = useMutation<Order, Error, OrderPayload>({
        mutationFn: orderApi.create,
        onSuccess: (): void => {
            queryClient.invalidateQueries({ queryKey: ['orders'] });
            toast.success('Order created!');
        }
    });

    const deleteMutation = useMutation<void, Error, number>({
        mutationFn: orderApi.delete,
        onSuccess: (): void => {
            queryClient.invalidateQueries({ queryKey: ['orders'] });
            toast.success('Order deleted!');
        }
    });

    return { 
        orders: query.data?.data, 
        meta: query.data?.meta,
        isLoading: query.isLoading, 
        createOrder: createMutation.mutate, 
        deleteOrder: deleteMutation.mutate 
    };
};

4. The Pure UI Component

Because we abstracted data fetching, types, and state management, our presentation component is remarkably clean. It knows nothing about axios, endpoints, or complex try-catch blocks.

The Presentation Component:

// src/components/OrderList.tsx
import React from 'react';
import { useOrders } from '../hooks/useOrders';

export const OrderList: React.FC = () => {
    // Destructuring state directly from our application logic hook
    const { orders, isLoading, deleteOrder } = useOrders();

    if (isLoading) return <div>Loading records...</div>;

    return (
        <div className="p-6 bg-white shadow rounded-lg">
            <h2 className="text-2xl font-bold mb-4">Orders (Full CRUD)</h2>
            <ul>
                {orders?.map(order => (
                    <li key={order.id} className="flex justify-between items-center bg-gray-50 border p-4 mb-2">
                        <span>Order #{order.id} - ${order.total_amount} ({order.status})</span>
                        <div className="space-x-2">
                           <button className="text-blue-500 hover:underline">Edit</button>
                           <button onClick={() => deleteOrder(order.id)} className="text-red-500 hover:underline">Delete</button>
                        </div>
                    </li>
                ))}
            </ul>
        </div>
    );
};

Conclusion

We have successfully established a highly scalable, decoupled architecture on both our Laravel backend and React frontend.

By implementing Clean Architecture, we secured our endpoints with Gates and Policies, abstracted queries via Repositories, guaranteed data integrity with Database Transactions, optimized response times using asynchronous Events, standardized our output via API Resources, and maintained robust type safety across the entire application using TypeScript.

This is a professional, modular approach configured to sustain massive enterprise applications seamlessly.

Did you find this helpful? Save this article as a reference for your next big project, and feel free to discuss your thoughts on Repositories and clean code patterns in the comments! Happy Coding!

Engineering is best when shared. Find more of my writing, projects, and work at -- murtuza.dev

[Boost]

Md Murtuza Hussain — Tue, 10 Mar 2026 05:29:13 +0000

Md Murtuza Hussain

Mar 6

How to Build a Production-Ready REST API in Go 1.26 with Full CRUD & JWT Authentication

#go #architecture #tutorial #backend

Comments 1

23 min read

How to Build a Production-Ready REST API in Go 1.26 with Full CRUD & JWT Authentication

Md Murtuza Hussain — Fri, 06 Mar 2026 19:34:00 +0000

Building a backend that can genuinely withstand production traffic — with proper authentication, clean architecture, and robust error handling — is a challenge most Go tutorials skip. They show you a main.go file with five hundred lines of mixed handler logic and call it a tutorial.

This is not that article.

We are going to build a fully production-ready REST API using Go 1.26, following the latest industry standards and community best practices. By the end, you will have a deeply layered application with JWT-based authentication, full CRUD for a Products resource, structured logging, graceful shutdown, and a clean, testable codebase that mirrors what senior Go engineers build at scale.

Why Go for APIs in 2026?

Go remains one of the best choices for high-performance APIs. It offers:

Static compilation — single binary deployments, trivially containerized.
Native concurrency — goroutines and channels for unparalleled throughput.
Industry-grade standard library — the net/http package received major routing enhancements in Go 1.22 that are now fully mature in Go 1.26.
Minimal runtime overhead — far lower memory footprint than Node.js or the JVM.

The Go 1.22+ router (net/http) introduced method-based routing and path parameters natively, eliminating the need for external routing libraries like gorilla/mux for most use cases. We will leverage this in our project.

The Architecture Diagram & Request Lifecycle

Before writing any code, visualize the full lifecycle of an HTTP request through our API:

[HTTP Request]
      │
      ▼
1. [Router] (net/http ServeMux with method+path patterns)
      │
      ▼
2. [Middleware Chain] (Logger → Rate Limiter → JWT Auth Guard)
      │
      ▼
3. [Handler Layer] (Thin HTTP transport: decode request, call service, encode response)
      │
      ▼
4. [Service Layer] (Business Logic, Validation, Transactions)
      │
      ▼
5. [Repository Layer] (Abstracts all SQL queries via an interface)
      │
      ▼
6. [Database] (PostgreSQL via pgx/v5 — the modern, high-performance Go Postgres driver)
      │
      ▼
   (Data flows back up through the layers)
      │
      ▼
7. [Response Encoder] (Strict JSON output, never exposing internal fields)
      │
      ▼
[HTTP Response]

This separation ensures every layer has a single responsibility. Your handlers never talk to the database. Your repositories have zero business logic.

The Project Structure

By the end of this tutorial, our project will be laid out as follows. Every folder has a single, clear responsibility.

go-products-api/
├── cmd/
│   └── api/
│       └── main.go             # Entry point: wires everything together & starts server
├── internal/
│   ├── auth/
│   │   ├── jwt.go              # JWT generation & validation logic
│   │   └── middleware.go       # HTTP middleware for protecting routes
│   ├── config/
│   │   └── config.go           # Reads environment variables into a typed Config struct
│   ├── database/
│   │   └── postgres.go         # Initializes the pgx connection pool
│   ├── handler/
│   │   ├── auth_handler.go     # Handles /login and /register HTTP endpoints
│   │   └── product_handler.go  # Handles /products CRUD HTTP endpoints
│   ├── middleware/
│   │   └── logger.go           # Structured request logging middleware
│   ├── model/
│   │   └── models.go           # All domain structs: User, Product, request/response payloads
│   ├── repository/
│   │   ├── user_repository.go  # SQL queries for Users
│   │   └── product_repository.go # SQL queries for Products
│   └── service/
│       ├── auth_service.go     # Register/Login business logic (hashing, token gen)
│       └── product_service.go  # Product CRUD business logic & validation
├── migrations/
│   ├── 001_create_users.sql
│   └── 002_create_products.sql
├── .env.example
└── go.mod

The internal/ package is a Go compiler-enforced convention — code inside it cannot be imported by any external packages, enforcing encapsulation.

Dependencies

Initialize the project and install our lean dependency set:

mkdir go-products-api && cd go-products-api
go mod init github.com/yourname/go-products-api

# Core dependencies
go get github.com/jackc/pgx/v5             # High-performance PostgreSQL driver
go get golang.org/x/crypto                 # bcrypt password hashing
go get github.com/golang-jwt/jwt/v5        # JWT v5 (latest spec-compliant, maintained library)
go get github.com/joho/godotenv            # .env file loader for local development
go get golang.org/x/time/rate             # Token-bucket rate limiter from the Go team

Note on Go 1.26: We deliberately avoid gorilla/mux, gin, or echo for routing. The stdlib net/http ServeMux — enhanced in Go 1.22 to support METHOD /path/{param} patterns — is fully sufficient and results in a leaner binary with fewer supply-chain risks.

Step 1: Configuration (`internal/config/config.go`)

Never hardcode credentials. A typed Config struct loaded from environment variables is the standard Go approach. This also makes testing straightforward — swap the env vars, get a different config.

// internal/config/config.go
package config

import (
    "fmt"
    "os"
    "strconv"
)

// Config holds all application configuration, loaded from environment variables.
type Config struct {
    Server   ServerConfig
    Database DatabaseConfig
    JWT      JWTConfig
}

type ServerConfig struct {
    Port            string
    ReadTimeoutSec  int
    WriteTimeoutSec int
}

type DatabaseConfig struct {
    DSN string // PostgreSQL Data Source Name
}

type JWTConfig struct {
    Secret          string
    ExpiryHours     int
}

// Load reads environment variables and returns a populated Config struct.
// It fails fast if required variables are missing.
func Load() (*Config, error) {
    secret := os.Getenv("JWT_SECRET")
    if secret == "" {
        return nil, fmt.Errorf("config: JWT_SECRET environment variable is required")
    }

    dbDSN := os.Getenv("DATABASE_URL")
    if dbDSN == "" {
        return nil, fmt.Errorf("config: DATABASE_URL environment variable is required")
    }

    readTimeout, _ := strconv.Atoi(os.Getenv("SERVER_READ_TIMEOUT_SEC"))
    if readTimeout == 0 {
        readTimeout = 10
    }
    writeTimeout, _ := strconv.Atoi(os.Getenv("SERVER_WRITE_TIMEOUT_SEC"))
    if writeTimeout == 0 {
        writeTimeout = 30
    }
    jwtExpiry, _ := strconv.Atoi(os.Getenv("JWT_EXPIRY_HOURS"))
    if jwtExpiry == 0 {
        jwtExpiry = 24
    }
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    return &Config{
        Server: ServerConfig{
            Port:            port,
            ReadTimeoutSec:  readTimeout,
            WriteTimeoutSec: writeTimeout,
        },
        Database: DatabaseConfig{DSN: dbDSN},
        JWT:      JWTConfig{Secret: secret, ExpiryHours: jwtExpiry},
    }, nil
}

Step 2: Database Migrations

We keep migrations as plain SQL files checked into version control. This is the simplest, most portable approach.

migrations/001_create_users.sql:

CREATE TABLE IF NOT EXISTS users (
    id         BIGSERIAL PRIMARY KEY,
    email      TEXT UNIQUE NOT NULL,
    password   TEXT NOT NULL,        -- bcrypt hash, NEVER plaintext
    role       TEXT NOT NULL DEFAULT 'user',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);

migrations/002_create_products.sql:

CREATE TABLE IF NOT EXISTS products (
    id          BIGSERIAL PRIMARY KEY,
    user_id     BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    name        TEXT NOT NULL,
    description TEXT,
    price       NUMERIC(10, 2) NOT NULL CHECK (price >= 0),
    stock       INTEGER NOT NULL DEFAULT 0 CHECK (stock >= 0),
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_products_user_id ON products(user_id);

Step 3: Domain Models (`internal/model/models.go`)

A central models file defines our pure Go structs. These are not tied to any database library or HTTP framework.

// internal/model/models.go
package model

import "time"

// User represents an authenticated application user.
type User struct {
    ID        int64     `json:"id"`
    Email     string    `json:"email"`
    Password  string    `json:"-"` // The "-" tag ensures the hash is NEVER serialized to JSON
    Role      string    `json:"role"`
    CreatedAt time.Time `json:"created_at"`
}

// Product is the core domain entity.
type Product struct {
    ID          int64     `json:"id"`
    UserID      int64     `json:"user_id"`
    Name        string    `json:"name"`
    Description string    `json:"description,omitempty"`
    Price       float64   `json:"price"`
    Stock       int       `json:"stock"`
    CreatedAt   time.Time `json:"created_at"`
    UpdatedAt   time.Time `json:"updated_at"`
}

// --- Request Payloads (Incoming) ---

type RegisterRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

type LoginRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

type CreateProductRequest struct {
    Name        string  `json:"name"`
    Description string  `json:"description"`
    Price       float64 `json:"price"`
    Stock       int     `json:"stock"`
}

// UpdateProductRequest uses pointer fields so absent JSON keys are distinguishable
// from zero values. Only non-nil fields are written to the database on PATCH.
type UpdateProductRequest struct {
    Name        *string  `json:"name"`
    Description *string  `json:"description"`
    Price       *float64 `json:"price"`
    Stock       *int     `json:"stock"`
}

// --- Response Payloads (Outgoing) ---

type AuthResponse struct {
    AccessToken string `json:"access_token"`
    TokenType   string `json:"token_type"`
    User        *User  `json:"user"`
}

// APIError is the standard error response format for the API.
type APIError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
}

// PaginatedResponse wraps a list of items with pagination metadata.
type PaginatedResponse[T any] struct {
    Data  []T   `json:"data"`
    Total int64 `json:"total"`
    Page  int   `json:"page"`
    Limit int   `json:"limit"`
}

// Claims represents the data embedded inside our JWT.
type Claims struct {
    UserID int64  `json:"user_id"`
    Email  string `json:"email"`
    Role   string `json:"role"`
}

Key design decision: the json:"-" tag on User.Password is a critical security safeguard. Even if a handler accidentally returns a User struct directly, the bcrypt hash will never appear in the JSON output.

Step 4: JWT Authentication (`internal/auth/jwt.go`)

We use golang-jwt/jwt/v5, which implements the full RFC 7519 specification and is the community's maintained successor to the older dgrijalva/jwt-go package.

// internal/auth/jwt.go
package auth

import (
    "errors"
    "fmt"
    "time"

    "github.com/golang-jwt/jwt/v5"
    "github.com/yourname/go-products-api/internal/model"
)

// jwtCustomClaims embeds the standard RegisteredClaims and adds our custom fields.
type jwtCustomClaims struct {
    model.Claims
    jwt.RegisteredClaims
}

// Manager handles all JWT operations using a typed struct, not a global variable.
type Manager struct {
    secretKey   []byte
    expiryHours int
}

// NewManager creates a new JWT Manager.
func NewManager(secret string, expiryHours int) *Manager {
    return &Manager{
        secretKey:   []byte(secret),
        expiryHours: expiryHours,
    }
}

// Generate creates a signed JWT string for a given user.
func (m *Manager) Generate(userID int64, email, role string) (string, error) {
    claims := jwtCustomClaims{
        Claims: model.Claims{
            UserID: userID,
            Email:  email,
            Role:   role,
        },
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Duration(m.expiryHours) * time.Hour)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
            Issuer:    "go-products-api",
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    signedToken, err := token.SignedString(m.secretKey)
    if err != nil {
        return "", fmt.Errorf("auth: failed to sign token: %w", err)
    }
    return signedToken, nil
}

// Validate parses and validates a JWT string, returning the embedded claims.
func (m *Manager) Validate(tokenStr string) (*model.Claims, error) {
    token, err := jwt.ParseWithClaims(tokenStr, &jwtCustomClaims{}, func(token *jwt.Token) (any, error) {
        // IMPORTANT: Always verify the signing method to prevent algorithm substitution attacks
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("auth: unexpected signing method: %v", token.Header["alg"])
        }
        return m.secretKey, nil
    })
    if err != nil {
        if errors.Is(err, jwt.ErrTokenExpired) {
            return nil, fmt.Errorf("auth: token has expired")
        }
        return nil, fmt.Errorf("auth: invalid token: %w", err)
    }

    claims, ok := token.Claims.(*jwtCustomClaims)
    if !ok || !token.Valid {
        return nil, fmt.Errorf("auth: token claims are invalid")
    }

    return &claims.Claims, nil
}

Step 5: Authentication Middleware (`internal/auth/middleware.go`)

The middleware extracts and validates the Bearer token from every protected request. It uses a context key to pass the claims downstream to the handlers — a clean, idiomatic Go pattern.

// internal/auth/middleware.go
package auth

import (
    "context"
    "net/http"
    "strings"

    "github.com/yourname/go-products-api/internal/model"
)

// contextKey is an unexported type to prevent context key collisions.
type contextKey string

const claimsContextKey contextKey = "jwt_claims"

// Middleware returns an http.Handler middleware that validates the JWT on every request.
func (m *Manager) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        authHeader := r.Header.Get("Authorization")
        if authHeader == "" {
            writeError(w, http.StatusUnauthorized, "authorization header is required")
            return
        }

        parts := strings.SplitN(authHeader, " ", 2)
        if len(parts) != 2 || !strings.EqualFold(parts[0], "bearer") {
            writeError(w, http.StatusUnauthorized, "authorization header format must be: Bearer {token}")
            return
        }

        claims, err := m.Validate(parts[1])
        if err != nil {
            writeError(w, http.StatusUnauthorized, err.Error())
            return
        }

        // Inject the validated claims into the request context
        ctx := context.WithValue(r.Context(), claimsContextKey, claims)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// ClaimsFromContext retrieves the validated JWT claims from the request context.
// Returns nil if not present (i.e., called on an unprotected route).
func ClaimsFromContext(ctx context.Context) *model.Claims {
    claims, _ := ctx.Value(claimsContextKey).(*model.Claims)
    return claims
}

// RequireRole returns a middleware that enforces a specific user role.
func (m *Manager) RequireRole(role string, next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        claims := ClaimsFromContext(r.Context())
        if claims == nil || claims.Role != role {
            writeError(w, http.StatusForbidden, "you do not have permission to perform this action")
            return
        }
        next.ServeHTTP(w, r)
    })
}

Step 6: The Repository Layer

Repositories encapsulate all SQL. They depend on an interface. This makes your services testable without a real database — you can mock the repository.

The User Repository (`internal/repository/user_repository.go`)

// internal/repository/user_repository.go
package repository

import (
    "context"
    "errors"
    "fmt"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/yourname/go-products-api/internal/model"
)

// UserRepository defines the contract for User data access.
type UserRepository interface {
    Create(ctx context.Context, email, hashedPassword string) (*model.User, error)
    FindByEmail(ctx context.Context, email string) (*model.User, error)
    FindByID(ctx context.Context, id int64) (*model.User, error)
}

type pgUserRepository struct {
    pool *pgxpool.Pool
}

// NewUserRepository creates a new PostgreSQL-backed UserRepository.
func NewUserRepository(pool *pgxpool.Pool) UserRepository {
    return &pgUserRepository{pool: pool}
}

func (r *pgUserRepository) Create(ctx context.Context, email, hashedPassword string) (*model.User, error) {
    query := `
        INSERT INTO users (email, password)
        VALUES ($1, $2)
        RETURNING id, email, role, created_at`

    var user model.User
    err := r.pool.QueryRow(ctx, query, email, hashedPassword).Scan(
        &user.ID, &user.Email, &user.Role, &user.CreatedAt,
    )
    if err != nil {
        return nil, fmt.Errorf("userRepo.Create: %w", err)
    }
    return &user, nil
}

func (r *pgUserRepository) FindByEmail(ctx context.Context, email string) (*model.User, error) {
    query := `SELECT id, email, password, role, created_at FROM users WHERE email = $1`

    var user model.User
    err := r.pool.QueryRow(ctx, query, email).Scan(
        &user.ID, &user.Email, &user.Password, &user.Role, &user.CreatedAt,
    )
    if err != nil {
        if errors.Is(err, pgx.ErrNoRows) {
            return nil, nil // Not found is not an error at this layer
        }
        return nil, fmt.Errorf("userRepo.FindByEmail: %w", err)
    }
    return &user, nil
}

func (r *pgUserRepository) FindByID(ctx context.Context, id int64) (*model.User, error) {
    query := `SELECT id, email, role, created_at FROM users WHERE id = $1`

    var user model.User
    err := r.pool.QueryRow(ctx, query, id).Scan(
        &user.ID, &user.Email, &user.Role, &user.CreatedAt,
    )
    if err != nil {
        if errors.Is(err, pgx.ErrNoRows) {
            return nil, nil
        }
        return nil, fmt.Errorf("userRepo.FindByID: %w", err)
    }
    return &user, nil
}

The Product Repository (`internal/repository/product_repository.go`)

// internal/repository/product_repository.go
package repository

import (
    "context"
    "errors"
    "fmt"
    "strings"

    "github.com/jackc/pgx/v5"
    "github.com/jackc/pgx/v5/pgxpool"
    "github.com/yourname/go-products-api/internal/model"
)

// ProductRepository defines the contract for Product data access.
type ProductRepository interface {
    Create(ctx context.Context, userID int64, req *model.CreateProductRequest) (*model.Product, error)
    FindAll(ctx context.Context, page, limit int) ([]*model.Product, int64, error)
    FindByID(ctx context.Context, id int64) (*model.Product, error)
    Update(ctx context.Context, id int64, req *model.UpdateProductRequest) (*model.Product, error)
    Delete(ctx context.Context, id int64) error
}

type pgProductRepository struct {
    pool *pgxpool.Pool
}

// NewProductRepository creates a new PostgreSQL-backed ProductRepository.
func NewProductRepository(pool *pgxpool.Pool) ProductRepository {
    return &pgProductRepository{pool: pool}
}

func (r *pgProductRepository) Create(ctx context.Context, userID int64, req *model.CreateProductRequest) (*model.Product, error) {
    query := `
        INSERT INTO products (user_id, name, description, price, stock)
        VALUES ($1, $2, $3, $4, $5)
        RETURNING id, user_id, name, description, price, stock, created_at, updated_at`

    var p model.Product
    err := r.pool.QueryRow(ctx, query, userID, req.Name, req.Description, req.Price, req.Stock).Scan(
        &p.ID, &p.UserID, &p.Name, &p.Description, &p.Price, &p.Stock, &p.CreatedAt, &p.UpdatedAt,
    )
    if err != nil {
        return nil, fmt.Errorf("productRepo.Create: %w", err)
    }
    return &p, nil
}

func (r *pgProductRepository) FindAll(ctx context.Context, page, limit int) ([]*model.Product, int64, error) {
    // Use a Common Table Expression to get both the products and total count in a single query
    query := `
        WITH product_count AS (SELECT COUNT(*) FROM products)
        SELECT id, user_id, name, description, price, stock, created_at, updated_at,
               (SELECT * FROM product_count)
        FROM products
        ORDER BY created_at DESC
        LIMIT $1 OFFSET $2`

    offset := (page - 1) * limit
    rows, err := r.pool.Query(ctx, query, limit, offset)
    if err != nil {
        return nil, 0, fmt.Errorf("productRepo.FindAll: %w", err)
    }
    defer rows.Close()

    var products []*model.Product
    var total int64
    for rows.Next() {
        var p model.Product
        if err := rows.Scan(&p.ID, &p.UserID, &p.Name, &p.Description, &p.Price, &p.Stock, &p.CreatedAt, &p.UpdatedAt, &total); err != nil {
            return nil, 0, fmt.Errorf("productRepo.FindAll scan: %w", err)
        }
        products = append(products, &p)
    }
    return products, total, rows.Err()
}

func (r *pgProductRepository) FindByID(ctx context.Context, id int64) (*model.Product, error) {
    query := `SELECT id, user_id, name, description, price, stock, created_at, updated_at FROM products WHERE id = $1`

    var p model.Product
    err := r.pool.QueryRow(ctx, query, id).Scan(
        &p.ID, &p.UserID, &p.Name, &p.Description, &p.Price, &p.Stock, &p.CreatedAt, &p.UpdatedAt,
    )
    if err != nil {
        if errors.Is(err, pgx.ErrNoRows) {
            return nil, nil
        }
        return nil, fmt.Errorf("productRepo.FindByID: %w", err)
    }
    return &p, nil
}

func (r *pgProductRepository) Update(ctx context.Context, id int64, req *model.UpdateProductRequest) (*model.Product, error) {
    // Build the SET clause dynamically — only include fields the client actually sent.
    // nil pointer = "field not provided by client" = skip it in SQL.
    setClauses := []string{}
    args := []any{}
    argIdx := 1

    if req.Name != nil {
        setClauses = append(setClauses, fmt.Sprintf("name = $%d", argIdx))
        args = append(args, *req.Name)
        argIdx++
    }
    if req.Description != nil {
        setClauses = append(setClauses, fmt.Sprintf("description = $%d", argIdx))
        args = append(args, *req.Description)
        argIdx++
    }
    if req.Price != nil {
        setClauses = append(setClauses, fmt.Sprintf("price = $%d", argIdx))
        args = append(args, *req.Price)
        argIdx++
    }
    if req.Stock != nil {
        setClauses = append(setClauses, fmt.Sprintf("stock = $%d", argIdx))
        args = append(args, *req.Stock)
        argIdx++
    }
    setClauses = append(setClauses, "updated_at = NOW()")
    args = append(args, id)

    query := fmt.Sprintf(`
        UPDATE products
        SET %s
        WHERE id = $%d
        RETURNING id, user_id, name, description, price, stock, created_at, updated_at`,
        strings.Join(setClauses, ", "), argIdx,
    )

    var p model.Product
    err := r.pool.QueryRow(ctx, query, args...).Scan(
        &p.ID, &p.UserID, &p.Name, &p.Description, &p.Price, &p.Stock, &p.CreatedAt, &p.UpdatedAt,
    )
    if err != nil {
        if errors.Is(err, pgx.ErrNoRows) {
            return nil, nil
        }
        return nil, fmt.Errorf("productRepo.Update: %w", err)
    }
    return &p, nil
}

func (r *pgProductRepository) Delete(ctx context.Context, id int64) error {
    result, err := r.pool.Exec(ctx, `DELETE FROM products WHERE id = $1`, id)
    if err != nil {
        return fmt.Errorf("productRepo.Delete: %w", err)
    }
    if result.RowsAffected() == 0 {
        return fmt.Errorf("productRepo.Delete: no product found with id %d", id)
    }
    return nil
}

Step 7: The Service Layer (Business Logic)

The service layer is the application's brain. It runs all business rules and is entirely unaware of HTTP.

Auth Service (`internal/service/auth_service.go`)

// internal/service/auth_service.go
package service

import (
    "context"
    "fmt"
    "strings"

    "golang.org/x/crypto/bcrypt"
    "github.com/yourname/go-products-api/internal/auth"
    "github.com/yourname/go-products-api/internal/model"
    "github.com/yourname/go-products-api/internal/repository"
)

// AuthService defines the contract for authentication business logic.
type AuthService interface {
    Register(ctx context.Context, req *model.RegisterRequest) (*model.AuthResponse, error)
    Login(ctx context.Context, req *model.LoginRequest) (*model.AuthResponse, error)
}

type authService struct {
    userRepo   repository.UserRepository
    jwtManager *auth.Manager
}

// NewAuthService creates a new AuthService.
func NewAuthService(userRepo repository.UserRepository, jwtManager *auth.Manager) AuthService {
    return &authService{userRepo: userRepo, jwtManager: jwtManager}
}

func (s *authService) Register(ctx context.Context, req *model.RegisterRequest) (*model.AuthResponse, error) {
    // --- Validation ---
    req.Email = strings.TrimSpace(strings.ToLower(req.Email))
    if req.Email == "" || !strings.Contains(req.Email, "@") {
        return nil, fmt.Errorf("validation: a valid email address is required")
    }
    if len(req.Password) < 8 {
        return nil, fmt.Errorf("validation: password must be at least 8 characters long")
    }

    // --- Check for existing user ---
    existing, err := s.userRepo.FindByEmail(ctx, req.Email)
    if err != nil {
        return nil, fmt.Errorf("register: failed to check existing user: %w", err)
    }
    if existing != nil {
        return nil, fmt.Errorf("validation: a user with this email already exists")
    }

    // --- Hash the password using bcrypt at cost 12 ---
    // Cost 12 is the modern recommendation: secure enough, not so slow it impacts UX.
    hash, err := bcrypt.GenerateFromPassword([]byte(req.Password), 12)
    if err != nil {
        return nil, fmt.Errorf("register: failed to hash password: %w", err)
    }

    user, err := s.userRepo.Create(ctx, req.Email, string(hash))
    if err != nil {
        return nil, fmt.Errorf("register: failed to create user: %w", err)
    }

    token, err := s.jwtManager.Generate(user.ID, user.Email, user.Role)
    if err != nil {
        return nil, err
    }

    return &model.AuthResponse{
        AccessToken: token,
        TokenType:   "Bearer",
        User:        user,
    }, nil
}

func (s *authService) Login(ctx context.Context, req *model.LoginRequest) (*model.AuthResponse, error) {
    req.Email = strings.TrimSpace(strings.ToLower(req.Email))

    user, err := s.userRepo.FindByEmail(ctx, req.Email)
    if err != nil {
        return nil, fmt.Errorf("login: database error: %w", err)
    }

    // IMPORTANT: Return the same generic error for both "user not found" and
    // "wrong password" to prevent user enumeration attacks.
    if user == nil {
        return nil, fmt.Errorf("auth: invalid email or password")
    }
    if err := bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(req.Password)); err != nil {
        return nil, fmt.Errorf("auth: invalid email or password")
    }

    token, err := s.jwtManager.Generate(user.ID, user.Email, user.Role)
    if err != nil {
        return nil, err
    }

    return &model.AuthResponse{
        AccessToken: token,
        TokenType:   "Bearer",
        User:        user,
    }, nil
}

Security note: The identical error message for "user not found" and "wrong password" is intentional. Returning "user not found" for invalid emails would allow attackers to cheaply enumerate valid email addresses registered on your platform.

Product Service (`internal/service/product_service.go`)

// internal/service/product_service.go
package service

import (
    "context"
    "fmt"
    "strings"

    "github.com/yourname/go-products-api/internal/model"
    "github.com/yourname/go-products-api/internal/repository"
)

// ProductService defines the contract for product business logic.
type ProductService interface {
    Create(ctx context.Context, userID int64, req *model.CreateProductRequest) (*model.Product, error)
    GetAll(ctx context.Context, page, limit int) (*model.PaginatedResponse[model.Product], error)
    GetByID(ctx context.Context, id int64) (*model.Product, error)
    Update(ctx context.Context, requesterID, productID int64, req *model.UpdateProductRequest) (*model.Product, error)
    Delete(ctx context.Context, requesterID, productID int64) error
}

type productService struct {
    productRepo repository.ProductRepository
}

// NewProductService creates a new ProductService.
func NewProductService(productRepo repository.ProductRepository) ProductService {
    return &productService{productRepo: productRepo}
}

func (s *productService) Create(ctx context.Context, userID int64, req *model.CreateProductRequest) (*model.Product, error) {
    req.Name = strings.TrimSpace(req.Name)
    if req.Name == "" {
        return nil, fmt.Errorf("validation: product name is required")
    }
    if req.Price < 0 {
        return nil, fmt.Errorf("validation: price cannot be negative")
    }
    if req.Stock < 0 {
        return nil, fmt.Errorf("validation: stock cannot be negative")
    }

    return s.productRepo.Create(ctx, userID, req)
}

func (s *productService) GetAll(ctx context.Context, page, limit int) (*model.PaginatedResponse[model.Product], error) {
    if page < 1 {
        page = 1
    }
    if limit < 1 || limit > 100 {
        limit = 20
    }

    products, total, err := s.productRepo.FindAll(ctx, page, limit)
    if err != nil {
        return nil, fmt.Errorf("productService.GetAll: %w", err)
    }

    // Dereference pointers for the response
    items := make([]model.Product, len(products))
    for i, p := range products {
        items[i] = *p
    }

    return &model.PaginatedResponse[model.Product]{
        Data:  items,
        Total: total,
        Page:  page,
        Limit: limit,
    }, nil
}

func (s *productService) GetByID(ctx context.Context, id int64) (*model.Product, error) {
    product, err := s.productRepo.FindByID(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("productService.GetByID: %w", err)
    }
    if product == nil {
        return nil, fmt.Errorf("not_found: product with id %d does not exist", id)
    }
    return product, nil
}

func (s *productService) Update(ctx context.Context, requesterID, productID int64, req *model.UpdateProductRequest) (*model.Product, error) {
    // 1. Authorization: Verify the requester owns this product (prevents IDOR)
    existing, err := s.productRepo.FindByID(ctx, productID)
    if err != nil {
        return nil, err
    }
    if existing == nil {
        return nil, fmt.Errorf("not_found: product with id %d does not exist", productID)
    }
    if existing.UserID != requesterID {
        return nil, fmt.Errorf("forbidden: you do not own this product")
    }

    // 2. Validate only sent fields (nil = field was omitted from the request body)
    if req.Name != nil {
        trimmed := strings.TrimSpace(*req.Name)
        if trimmed == "" {
            return nil, fmt.Errorf("validation: product name cannot be empty")
        }
        req.Name = &trimmed
    }
    if req.Price != nil && *req.Price < 0 {
        return nil, fmt.Errorf("validation: price cannot be negative")
    }
    if req.Stock != nil && *req.Stock < 0 {
        return nil, fmt.Errorf("validation: stock cannot be negative")
    }

    // 3. Reject a completely empty PATCH body
    if req.Name == nil && req.Description == nil && req.Price == nil && req.Stock == nil {
        return nil, fmt.Errorf("validation: no fields provided for update")
    }

    return s.productRepo.Update(ctx, productID, req)
}

func (s *productService) Delete(ctx context.Context, requesterID, productID int64) error {
    // Authorization check
    existing, err := s.productRepo.FindByID(ctx, productID)
    if err != nil {
        return err
    }
    if existing == nil {
        return fmt.Errorf("not_found: product with id %d does not exist", productID)
    }
    if existing.UserID != requesterID {
        return fmt.Errorf("forbidden: you do not own this product")
    }

    return s.productRepo.Delete(ctx, productID)
}

Step 8: The Handler Layer (HTTP Transport)

Handlers are thin. They decode requests, call the service, handle errors by converting them into HTTP status codes, and encode responses.

The Helper (`internal/auth/middleware.go` additions)

// Add these helper functions to internal/auth/middleware.go (or a shared response package)
import "encoding/json"

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

func writeError(w http.ResponseWriter, status int, message string) {
    writeJSON(w, status, model.APIError{Code: status, Message: message})
}

Auth Handler (`internal/handler/auth_handler.go`)

// internal/handler/auth_handler.go
package handler

import (
    "encoding/json"
    "net/http"
    "strings"

    "github.com/yourname/go-products-api/internal/auth"
    "github.com/yourname/go-products-api/internal/model"
    "github.com/yourname/go-products-api/internal/service"
)

// AuthHandler handles auth-related HTTP requests.
type AuthHandler struct {
    authSvc service.AuthService
}

// NewAuthHandler creates a new AuthHandler.
func NewAuthHandler(authSvc service.AuthService) *AuthHandler {
    return &AuthHandler{authSvc: authSvc}
}

func (h *AuthHandler) Register(w http.ResponseWriter, r *http.Request) {
    var req model.RegisterRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
        return
    }

    resp, err := h.authSvc.Register(r.Context(), &req)
    if err != nil {
        if isValidationErr(err) {
            auth.WriteError(w, http.StatusUnprocessableEntity, err.Error())
            return
        }
        auth.WriteError(w, http.StatusInternalServerError, "registration failed")
        return
    }

    auth.WriteJSON(w, http.StatusCreated, resp)
}

func (h *AuthHandler) Login(w http.ResponseWriter, r *http.Request) {
    var req model.LoginRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
        return
    }

    resp, err := h.authSvc.Login(r.Context(), &req)
    if err != nil {
        auth.WriteError(w, http.StatusUnauthorized, err.Error())
        return
    }

    auth.WriteJSON(w, http.StatusOK, resp)
}

// isValidationErr checks if the error originated from a validation rule.
func isValidationErr(err error) bool {
    return strings.HasPrefix(err.Error(), "validation:")
}

Product Handler (`internal/handler/product_handler.go`)

// internal/handler/product_handler.go
package handler

import (
    "encoding/json"
    "net/http"
    "strconv"
    "strings"

    "github.com/yourname/go-products-api/internal/auth"
    "github.com/yourname/go-products-api/internal/model"
    "github.com/yourname/go-products-api/internal/service"
)

// ProductHandler handles product CRUD HTTP requests.
type ProductHandler struct {
    productSvc service.ProductService
}

// NewProductHandler creates a new ProductHandler.
func NewProductHandler(productSvc service.ProductService) *ProductHandler {
    return &ProductHandler{productSvc: productSvc}
}

func (h *ProductHandler) Create(w http.ResponseWriter, r *http.Request) {
    claims := auth.ClaimsFromContext(r.Context())

    var req model.CreateProductRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid request body")
        return
    }

    product, err := h.productSvc.Create(r.Context(), claims.UserID, &req)
    if err != nil {
        if isValidationErr(err) {
            auth.WriteError(w, http.StatusUnprocessableEntity, err.Error())
            return
        }
        auth.WriteError(w, http.StatusInternalServerError, "failed to create product")
        return
    }

    auth.WriteJSON(w, http.StatusCreated, product)
}

func (h *ProductHandler) GetAll(w http.ResponseWriter, r *http.Request) {
    page, _ := strconv.Atoi(r.URL.Query().Get("page"))
    limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))

    result, err := h.productSvc.GetAll(r.Context(), page, limit)
    if err != nil {
        auth.WriteError(w, http.StatusInternalServerError, "failed to retrieve products")
        return
    }

    auth.WriteJSON(w, http.StatusOK, result)
}

func (h *ProductHandler) GetByID(w http.ResponseWriter, r *http.Request) {
    // Go 1.22+: PathValue extracts {id} from the route pattern
    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
    if err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid product id")
        return
    }

    product, err := h.productSvc.GetByID(r.Context(), id)
    if err != nil {
        if strings.HasPrefix(err.Error(), "not_found:") {
            auth.WriteError(w, http.StatusNotFound, err.Error())
            return
        }
        auth.WriteError(w, http.StatusInternalServerError, "failed to retrieve product")
        return
    }

    auth.WriteJSON(w, http.StatusOK, product)
}

func (h *ProductHandler) Update(w http.ResponseWriter, r *http.Request) {
    claims := auth.ClaimsFromContext(r.Context())

    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
    if err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid product id")
        return
    }

    var req model.UpdateProductRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid request body")
        return
    }

    product, err := h.productSvc.Update(r.Context(), claims.UserID, id, &req)
    if err != nil {
        switch {
        case strings.HasPrefix(err.Error(), "not_found:"):
            auth.WriteError(w, http.StatusNotFound, err.Error())
        case strings.HasPrefix(err.Error(), "forbidden:"):
            auth.WriteError(w, http.StatusForbidden, err.Error())
        case isValidationErr(err):
            auth.WriteError(w, http.StatusUnprocessableEntity, err.Error())
        default:
            auth.WriteError(w, http.StatusInternalServerError, "failed to update product")
        }
        return
    }

    auth.WriteJSON(w, http.StatusOK, product)
}

func (h *ProductHandler) Delete(w http.ResponseWriter, r *http.Request) {
    claims := auth.ClaimsFromContext(r.Context())

    id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
    if err != nil {
        auth.WriteError(w, http.StatusBadRequest, "invalid product id")
        return
    }

    if err := h.productSvc.Delete(r.Context(), claims.UserID, id); err != nil {
        switch {
        case strings.HasPrefix(err.Error(), "not_found:"):
            auth.WriteError(w, http.StatusNotFound, err.Error())
        case strings.HasPrefix(err.Error(), "forbidden:"):
            auth.WriteError(w, http.StatusForbidden, err.Error())
        default:
            auth.WriteError(w, http.StatusInternalServerError, "failed to delete product")
        }
        return
    }

    w.WriteHeader(http.StatusNoContent) // 204: Success with no body
}

Step 9: Request Logging Middleware (`internal/middleware/logger.go`)

Structured logging is non-negotiable in production. We use Go's native log/slog package (introduced in Go 1.21 and now standard in Go 1.26) for JSON log output.

// internal/middleware/logger.go
package middleware

import (
    "log/slog"
    "net/http"
    "time"
)

// responseWriter wraps http.ResponseWriter to intercept the status code.
type responseWriter struct {
    http.ResponseWriter
    statusCode int
}

func (rw *responseWriter) WriteHeader(code int) {
    rw.statusCode = code
    rw.ResponseWriter.WriteHeader(code)
}

// Logger returns a structured logging middleware using the stdlib slog package.
func Logger(logger *slog.Logger) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            start := time.Now()
            wrapped := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}

            next.ServeHTTP(wrapped, r)

            logger.Info("request completed",
                "method", r.Method,
                "path", r.URL.Path,
                "status", wrapped.statusCode,
                "duration_ms", time.Since(start).Milliseconds(),
                "remote_addr", r.RemoteAddr,
            )
        })
    }
}

Step 10: The Entry Point — Wiring it All Together (`cmd/api/main.go`)

The main.go file is the composition root. It wires together all dependencies and starts the server with proper configuration for production, including graceful shutdown.

// cmd/api/main.go
package main

import (
    "context"
    "fmt"
    "log/slog"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"

    "github.com/joho/godotenv"
    "github.com/yourname/go-products-api/internal/auth"
    "github.com/yourname/go-products-api/internal/config"
    "github.com/yourname/go-products-api/internal/database"
    "github.com/yourname/go-products-api/internal/handler"
    "github.com/yourname/go-products-api/internal/middleware"
    "github.com/yourname/go-products-api/internal/repository"
    "github.com/yourname/go-products-api/internal/service"
)

func main() {
    // 1. Load env and initialize structured JSON logger
    _ = godotenv.Load()
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
    slog.SetDefault(logger)

    // 2. Load typed configuration (fails fast on missing env vars)
    cfg, err := config.Load()
    if err != nil {
        logger.Error("failed to load configuration", "error", err)
        os.Exit(1)
    }

    // 3. Initialize the PostgreSQL connection pool
    pool, err := database.NewPool(context.Background(), cfg.Database.DSN)
    if err != nil {
        logger.Error("failed to connect to database", "error", err)
        os.Exit(1)
    }
    defer pool.Close()

    // 4. Wire dependencies (Dependency Injection, manually)
    jwtManager := auth.NewManager(cfg.JWT.Secret, cfg.JWT.ExpiryHours)

    userRepo := repository.NewUserRepository(pool)
    productRepo := repository.NewProductRepository(pool)

    authSvc := service.NewAuthService(userRepo, jwtManager)
    productSvc := service.NewProductService(productRepo)

    authHandler := handler.NewAuthHandler(authSvc)
    productHandler := handler.NewProductHandler(productSvc)

    // 5. Register routes using the Go 1.22+ enhanced ServeMux
    mux := http.NewServeMux()

    // Public routes
    mux.HandleFunc("POST /api/v1/auth/register", authHandler.Register)
    mux.HandleFunc("POST /api/v1/auth/login", authHandler.Login)

    // Protected routes — jwt.Middleware wraps the handler
    mux.Handle("GET  /api/v1/products",        jwtManager.Middleware(http.HandlerFunc(productHandler.GetAll)))
    mux.Handle("GET  /api/v1/products/{id}",   jwtManager.Middleware(http.HandlerFunc(productHandler.GetByID)))
    mux.Handle("POST /api/v1/products",        jwtManager.Middleware(http.HandlerFunc(productHandler.Create)))
    mux.Handle("PATCH /api/v1/products/{id}",  jwtManager.Middleware(http.HandlerFunc(productHandler.Update)))
    mux.Handle("DELETE /api/v1/products/{id}", jwtManager.Middleware(http.HandlerFunc(productHandler.Delete)))

    // 6. Apply global middleware (outermost = last to execute for the request, first for the response)
    loggedMux := middleware.Logger(logger)(mux)

    // 7. Configure the server with strict timeouts — essential for production
    server := &http.Server{
        Addr:         fmt.Sprintf(":%s", cfg.Server.Port),
        Handler:      loggedMux,
        ReadTimeout:  time.Duration(cfg.Server.ReadTimeoutSec) * time.Second,
        WriteTimeout: time.Duration(cfg.Server.WriteTimeoutSec) * time.Second,
        IdleTimeout:  120 * time.Second,
    }

    // 8. Start server in a goroutine and listen for OS shutdown signals
    go func() {
        logger.Info("server starting", "port", cfg.Server.Port)
        if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
            logger.Error("server failed to start", "error", err)
            os.Exit(1)
        }
    }()

    // Block until we receive SIGINT or SIGTERM (e.g., from `docker stop` or Ctrl+C)
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    <-quit

    // 9. Graceful shutdown: give in-flight requests 30 seconds to complete
    logger.Info("server shutting down gracefully...")
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    if err := server.Shutdown(ctx); err != nil {
        logger.Error("server forced to shut down", "error", err)
    }
    logger.Info("server stopped")
}

Step 11: Database Connection Pool (`internal/database/postgres.go`)

// internal/database/postgres.go
package database

import (
    "context"
    "fmt"

    "github.com/jackc/pgx/v5/pgxpool"
)

// NewPool creates and validates a new pgx connection pool.
func NewPool(ctx context.Context, dsn string) (*pgxpool.Pool, error) {
    poolConfig, err := pgxpool.ParseConfig(dsn)
    if err != nil {
        return nil, fmt.Errorf("database: failed to parse DSN: %w", err)
    }

    // Production-ready pool configuration
    poolConfig.MaxConns = 25
    poolConfig.MinConns = 5

    pool, err := pgxpool.NewWithConfig(ctx, poolConfig)
    if err != nil {
        return nil, fmt.Errorf("database: failed to create connection pool: %w", err)
    }

    // Validate connection on startup
    if err := pool.Ping(ctx); err != nil {
        return nil, fmt.Errorf("database: failed to ping postgres: %w", err)
    }

    return pool, nil
}

Running and Testing the API

The `.env.example` file

PORT=8080
DATABASE_URL=postgres://user:password@localhost:5432/go_products_api?sslmode=disable
JWT_SECRET=your-super-secret-key-change-this-in-production
JWT_EXPIRY_HOURS=24
SERVER_READ_TIMEOUT_SEC=10
SERVER_WRITE_TIMEOUT_SEC=30

Running the API

cp .env.example .env
# Edit .env with your PostgreSQL credentials
psql -U user -d go_products_api -f migrations/001_create_users.sql
psql -U user -d go_products_api -f migrations/002_create_products.sql

go run ./cmd/api/

Testing with cURL

1. Register a new user:

curl -s -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"securepassword123"}' | jq

2. Login and capture the token:

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"securepassword123"}' | jq -r '.access_token')

3. Create a product (authenticated):

curl -s -X POST http://localhost:8080/api/v1/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mechanical Keyboard","description":"TKL layout, Cherry MX Blue switches","price":149.99,"stock":42}' | jq

4. Get all products (paginated):

curl -s "http://localhost:8080/api/v1/products?page=1&limit=10" \
  -H "Authorization: Bearer $TOKEN" | jq

5. Partial update a product (PATCH — only send fields you want to change):

# Update only the price — name, description, and stock are untouched
curl -s -X PATCH http://localhost:8080/api/v1/products/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"price": 179.99}' | jq

# Update multiple fields at once
curl -s -X PATCH http://localhost:8080/api/v1/products/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mechanical Keyboard Pro","stock":38}' | jq

6. Delete a product:

curl -s -X DELETE http://localhost:8080/api/v1/products/1 \
  -H "Authorization: Bearer $TOKEN"
# Returns 204 No Content on success

Key Production Best Practices Applied

Practice	Where Applied	Why It Matters
Typed Config w/ fail-fast	`config.Load()`	Catches missing credentials before the first request
bcrypt cost 12	`auth_service.Register()`	Modern industry-standard compute cost
User enumeration defense	`auth_service.Login()`	Same error for bad email and bad password
`json:"-"` on passwords	`model.User`	Prevents accidental password hash leakage in API responses
Algorithm verification in JWT	`jwt.Validate()`	Prevents alg=none and algorithm substitution attacks
Unexported context key type	`auth.contextKey`	Prevents context key collisions across packages
Server read/write timeouts	`main.go http.Server`	Prevents slow-loris and resource exhaustion attacks
Graceful shutdown	`main.go signal handling`	Zero-downtime deploys and clean container stops
Ownership checks in service	`product_service.Update/Delete`	Prevents IDOR (Insecure Direct Object Reference) vulnerabilities
Structured JSON logging (slog)	`middleware/logger.go`	Machine-parseable logs for Datadog, Loki, CloudWatch
Connection pool tuning	`database/postgres.go`	Prevents pool exhaustion under high traffic
`internal/` package	Entire project	Go compiler enforces encapsulation
`RETURNING` clauses in SQL	All repository mutations	Eliminates unnecessary follow-up `SELECT` queries
CTE for paginated count	`productRepo.FindAll()`	Single database round-trip for data + count

Conclusion

We have built a full-featured, production-ready REST API in Go 1.26 from the ground up. Every layer has a single responsibility, every security concern has been addressed, and the architecture is entirely testable without a running database.

By leveraging the modern stdlib router, JWT v5, pgx/v5, bcrypt, and slog, we have kept the dependency surface minimal while achieving what most enterprise applications need from day one.

The patterns established here — typed config, interface-backed repositories, thin handlers, and graceful shutdown — are the same ones powering Go services at Google, Cloudflare, and Stripe. They scale from your laptop to millions of requests per day without a rewrite.

Did you find this helpful? Follow for more deep-dives into production Go patterns. Drop a comment with the architecture challenge you'd like covered next — testing strategies, observability with OpenTelemetry, or building a real-time WebSocket layer on top of this API.

Engineering is best when shared. Find more of my writing, projects, and work at -- murtuza.dev

Building an Enterprise-Grade Laravel 12 & React SPA: Architecture, Auth, and Full CRUD

Md Murtuza Hussain — Thu, 05 Mar 2026 19:22:23 +0000

Let’s bypass the endless debate over Monolith vs. SPA. If you've decided a decoupled architecture is genuinely what your project demands, you need to build it right.

A standard tutorial will show you how to connect Laravel to React. But in a production environment, dropping all your business logic into a Controller or relying on React's useEffect for data fetching is a recipe for unmaintainable spaghetti code.

When you build systems meant to scale, every read and write must pass through strict boundaries: Routing, Validation, Authorization, Services, and Repositories on the backend, paired with Feature-Sliced caching on the frontend.

Here is the definitive blueprint for a full CRUD application with authentication and authorization using Laravel 12, React, Sanctum, and TanStack Query.

Part 1: The Laravel Backend (Strict Boundaries)

First, scaffold the Laravel application and install the API and Sanctum requirements.

composer create-project laravel/laravel backend

laravel new backend

cd backend
php artisan install:api
php artisan migrate

Ensure your .env is configured for Sanctum's stateful cookie authentication:

FRONTEND_URL=http://localhost:5173
SANCTUM_STATEFUL_DOMAINS=localhost:5173

1. The Repository Contract (Data Access Layer)

Define the exact data operations allowed. By using an interface, we decouple our business logic from Eloquent.

app/Repositories/Contracts/PostRepositoryInterface.php:

namespace App\Repositories\Contracts;

use App\Models\Post;
use Illuminate\Pagination\LengthAwarePaginator;

interface PostRepositoryInterface
{
    public function paginate(int $perPage = 15): LengthAwarePaginator;
    public function create(array $data): Post;
    public function update(Post $post, array $data): bool;
    public function delete(Post $post): bool;
}

app/Repositories/Eloquent/PostRepository.php:

namespace App\Repositories\Eloquent;

use App\Models\Post;
use App\Repositories\Contracts\PostRepositoryInterface;
use Illuminate\Pagination\LengthAwarePaginator;

class PostRepository implements PostRepositoryInterface
{
    public function paginate(int $perPage = 15): LengthAwarePaginator
    {
        return Post::with('user')->latest()->paginate($perPage);
    }

    public function create(array $data): Post
    {
        return Post::create($data);
    }

    public function update(Post $post, array $data): bool
    {
        return $post->update($data);
    }

    public function delete(Post $post): bool
    {
        return $post->delete();
    }
}

(Note: Bind this interface to the implementation in your AppServiceProvider.)

2. The Service Layer (Business Logic)

This is where we orchestrate the CRUD operations.

app/Services/PostService.php:

namespace App\Services;

use App\Models\Post;
use App\Repositories\Contracts\PostRepositoryInterface;
use Illuminate\Support\Facades\DB;
use App\Events\PostCreated;

class PostService
{
    public function __construct(
        protected PostRepositoryInterface $repository
    ) {}

    public function getPosts(): LengthAwarePaginator
    {
        return $this->repository->paginate();
    }

    public function createPost(int $userId, array $data): Post
    {
        return DB::transaction(function () use ($userId, $data) {
            $data['user_id'] = $userId;
            $post = $this->repository->create($data);

            // Dispatch a background event
            PostCreated::dispatch($post);

            return $post;
        });
    }

    public function updatePost(Post $post, array $data): bool
    {
        return $this->repository->update($post, $data);
    }

    public function deletePost(Post $post): bool
    {
        return $this->repository->delete($post);
    }
}

2.5. Events and Listeners (Asynchronous Side-Effects)

To handle heavy background tasks (like sending notifications to followers) without delaying the user's HTTP response, dispatch an event and queue a listener.

app/Events/PostCreated.php:

namespace App\Events;

use App\Models\Post;
use Illuminate\Foundation\Events\Dispatchable;

class PostCreated 
{
    use Dispatchable;

    public function __construct(public Post $post) {}
}

app/Listeners/NotifySubscribers.php:

namespace App\Listeners;

use App\Events\PostCreated;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Log;

class NotifySubscribers implements ShouldQueue 
{
    public function handle(PostCreated $event): void 
    {
        // Simulate sending emails via a background queue
        Log::info("Notifying subscribers about new post: {$event->post->id}");
    }
}

3. Strict Authorization (Policies)

Never let a user modify something they don't own.

app/Policies/PostPolicy.php:

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }
}

4. The Anemic Controller

With validation handled by Form Requests (not shown for brevity), authorization by Policies, and logic by the Service, your Controller becomes beautifully anemic.

app/Http/Controllers/PostController.php:

namespace App\Http\Controllers;

use App\Http\Requests\StorePostRequest;
use App\Http\Requests\UpdatePostRequest;
use App\Http\Resources\PostResource;
use App\Models\Post;
use App\Services\PostService;
use Illuminate\Support\Facades\Gate;
use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Illuminate\Http\Response;

class PostController extends Controller implements HasMiddleware
{
    public static function middleware(): array
    {
        return [new Middleware('auth:sanctum')];
    }

    public function __construct(
        protected PostService $postService
    ) {}

    public function index(): AnonymousResourceCollection
    {
        return PostResource::collection($this->postService->getPosts());
    }

    public function store(StorePostRequest $request): PostResource
    {
        $post = $this->postService->createPost($request->user()->id, $request->validated());
        return new PostResource($post);
    }

    public function update(UpdatePostRequest $request, Post $post): PostResource
    {
        Gate::authorize('update', $post); 
        $this->postService->updatePost($post, $request->validated());
        return new PostResource($post->refresh());
    }

    public function destroy(Post $post): Response
    {
        Gate::authorize('delete', $post);
        $this->postService->deletePost($post);
        return response()->noContent();
    }
}

Part 2: The React Frontend (Feature-Based Architecture)

A modern React application should be structured around Features, not file types. We will isolate the posts domain entirely and use TanStack Query for server-state management.

Setup your Vite React app:

npm create vite@latest frontend -- --template react
cd frontend
npm install axios react-router-dom @tanstack/react-query

5. Global Axios & Auth Hooks

When using Sanctum with token-based authentication (Bearer tokens), your global Axios instance handles API requests and seamlessly redirects unauthenticated users.

src/lib/axios.js:

import Axios from 'axios';

const axios = Axios.create({
    baseURL: 'http://localhost:8000',
    headers: { 
        'X-Requested-With': 'XMLHttpRequest', 
        'Accept': 'application/json' 
    }
});

axios.interceptors.response.use(
    response => response,
    error => {
        if (error.response?.status === 401) {
            window.location.href = '/login';
        }
        return Promise.reject(error);
    }
);

export default axios;

src/hooks/useAuth.js:

import { useQuery } from '@tanstack/react-query';
import axios from '../lib/axios';

export const useAuth = () => {
    return useQuery({
        queryKey: ['authUser'],
        queryFn: async () => {
            const { data } = await axios.get('/api/user');
            return data;
        },
        retry: false,
    });
};

6. The Feature API & Hook Layers

Never call Axios directly inside a UI component.

src/features/posts/api/postApi.js:

import axios from '../../../lib/axios';

export const getPosts = async () => {
    const { data } = await axios.get('/api/posts');
    return data.data; 
};

export const createPost = async (postData) => {
    const { data } = await axios.post('/api/posts', postData);
    return data.data;
};

export const updatePost = async ({ id, ...postData }) => {
    const { data } = await axios.put(`/api/posts/${id}`, postData);
    return data.data;
};

export const deletePost = async (id) => {
    await axios.delete(`/api/posts/${id}`);
};

src/features/posts/hooks/useMutatePost.js:

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { createPost, updatePost, deletePost } from '../api/postApi';

export const useMutatePost = () => {
    const queryClient = useQueryClient();
    const onSuccess = () => queryClient.invalidateQueries(['posts']);

    const createMutation = useMutation({ mutationFn: createPost, onSuccess });
    const updateMutation = useMutation({ mutationFn: updatePost, onSuccess });
    const deleteMutation = useMutation({ mutationFn: deletePost, onSuccess });

    return {
        createPost: createMutation.mutate,
        updatePost: updateMutation.mutate,
        deletePost: deleteMutation.mutate,
        isPending: createMutation.isPending || updateMutation.isPending || deleteMutation.isPending
    };
};

7. The UI Layer

Finally, piece together the components.

src/features/posts/components/PostItem.jsx:

import { useAuth } from '../../../hooks/useAuth';
import { useMutatePost } from '../hooks/useMutatePost';

export const PostItem = ({ post, onEdit }) => {
    const { data: authUser } = useAuth();
    const { deletePost } = useMutatePost();

    // UI Authorization check
    const isOwner = authUser?.id === post.user_id;

    return (
        <div className="p-4 border rounded shadow-sm">
            <h2 className="text-xl font-bold">{post.title}</h2>
            <p className="text-gray-700">{post.content}</p>

            {isOwner && (
                <div className="mt-4 space-x-2">
                    <button onClick={() => onEdit(post)} className="text-blue-500">Edit</button>
                    <button onClick={() => deletePost(post.id)} className="text-red-500">Delete</button>
                </div>
            )}
        </div>
    );
};

The Takeaway

Architecture is about drawing strict boundaries. By binding Repository Interfaces, you decouple your app from the database. By utilizing Services, you isolate business logic. Combine this with TanStack Query and Feature-Sliced Design on the frontend, and you have a system capable of scaling without collapsing under its own weight.

Golang Concurrency: From "Hello World" to Worker Pools

Md Murtuza Hussain — Mon, 26 Jan 2026 02:06:11 +0000

Concurrency is often cited as the primary reason developers choose Go. But coming from languages with traditional threading models (like Java or C++), Go’s approach can feel like a paradigm shift.

It’s not just about "running things at the same time." It is about designing your program as a composition of independently executing processes.

In this guide, we’ll look at how Go handles concurrency, starting with the basics and ending with a real-world pattern.

1. Concurrency vs. Parallelism

Before writing code, we need to clear up a common misconception.

Concurrency is about dealing with lots of things at once. It's a structure.

Parallelism is about doing lots of things at once. It's an execution.

Go gives you the tools to write concurrent programs that can run in parallel, but they don't have to.

2. The Goroutine

A Goroutine is a lightweight thread managed by the Go runtime. They are incredibly cheap—you can easily spin up tens of thousands of them on a modest laptop.

To start one, you just use the go keyword.

package main

import (
    "fmt"
    "time"
)

func speak(word string) {
    for i := 0; i < 3; i++ {
        fmt.Println(word)
        time.Sleep(100 * time.Millisecond)
    }
}

func main() {
    // Runs in a new goroutine
    go speak("Goroutine says: Hi!")

    // Runs in the main goroutine
    speak("Main says: Hello!")

    // Give the goroutine time to finish before main exits
    time.Sleep(1 * time.Second) 
}

The Catch: If the main function exits, the program kills all other running goroutines immediately. We need a way to synchronize them.

3. Synchronization with WaitGroups

Using time.Sleep to wait for goroutines is hacky. The correct way to wait for a collection of goroutines to finish is sync.WaitGroup.

package main

import (
    "fmt"
    "sync"
)

func worker(id int, wg *sync.WaitGroup) {
    defer wg.Done() // Decrement the counter when the function exits
    fmt.Printf("Worker %d starting\n", id)
    // Simulate work
    fmt.Printf("Worker %d done\n", id)
}

func main() {
    var wg sync.WaitGroup

    for i := 1; i <= 3; i++ {
        wg.Add(1) // Increment the counter
        go worker(i, &wg)
    }

    wg.Wait() // Block until the counter goes back to 0
    fmt.Println("All workers done")
}

4. Channels: "Share Memory By Communicating"

This is Go’s golden rule. Instead of locking variables with Mutexes (though Go has those too), you pass data between goroutines using channels.

Think of a channel as a pipe. One goroutine puts data in one end, and another picks it up from the other.

Unbuffered Channels
Unbuffered channels block the sender until the receiver is ready (and vice versa). This provides implicit synchronization.

package main

import "fmt"

func main() {
    messages := make(chan string)

    go func() {
        messages <- "ping" // Blocks here until "pong" is ready to receive
    }()

    msg := <-messages // Blocks here until "ping" is sent
    fmt.Println(msg)
}

5. Pattern: The Worker Pool

Let’s put it all together. A common pattern in backend development is the Worker Pool. You have a queue of jobs and a fixed number of workers processing them concurrently.

This is useful when you have 10,000 tasks but only want to process 5 at a time to save CPU/Memory.

package main

import (
    "fmt"
    "time"
)

// A job to be processed
func worker(id int, jobs <-chan int, results chan<- int) {
    for j := range jobs {
        fmt.Println("worker", id, "started  job", j)
        time.Sleep(time.Second) // Simulate expensive task
        fmt.Println("worker", id, "finished job", j)
        results <- j * 2
    }
}

func main() {
    const numJobs = 5
    jobs := make(chan int, numJobs)
    results := make(chan int, numJobs)

    // 1. Start 3 workers
    for w := 1; w <= 3; w++ {
        go worker(w, jobs, results)
    }

    // 2. Send 5 jobs to the jobs channel
    for j := 1; j <= numJobs; j++ {
        jobs <- j
    }
    close(jobs) // Close channel to signal no more jobs

    // 3. Collect results
    for a := 1; a <= numJobs; a++ {
        <-results
    }
}

Common Pitfalls

Deadlocks: If a goroutine is waiting for a channel that no one is writing to, Go will panic with a deadlock error.

Race Conditions: If two goroutines access the same variable without a lock or channel, the result is unpredictable. always run your tests with go test -race to catch these.

Leaking Goroutines: If you start a goroutine but it gets stuck waiting for a channel forever, it will never be garbage collected. This is a memory leak.

Summary

Go’s concurrency model is powerful because it abstracts the complexity of OS threads. By using Goroutines for execution and Channels for communication, you can build highly scalable systems that are easier to reason about than traditional threaded code.

Engineering is best when shared. Find more of my writing, projects, and work at -- murtuza.dev

Golang Concurrency: From "Hello World" to Worker Pools

Md Murtuza Hussain — Mon, 26 Jan 2026 02:06:11 +0000

Concurrency is often cited as the primary reason developers choose Go. But coming from languages with traditional threading models (like Java or C++), Go’s approach can feel like a paradigm shift.

It’s not just about "running things at the same time." It is about designing your program as a composition of independently executing processes.

In this guide, we’ll look at how Go handles concurrency, starting with the basics and ending with a real-world pattern.

1. Concurrency vs. Parallelism

Before writing code, we need to clear up a common misconception.

Concurrency is about dealing with lots of things at once. It's a structure.

Parallelism is about doing lots of things at once. It's an execution.

Go gives you the tools to write concurrent programs that can run in parallel, but they don't have to.

2. The Goroutine

A Goroutine is a lightweight thread managed by the Go runtime. They are incredibly cheap—you can easily spin up tens of thousands of them on a modest laptop.

To start one, you just use the go keyword.

package main

import (
    "fmt"
    "time"
)

func speak(word string) {
    for i := 0; i < 3; i++ {
        fmt.Println(word)
        time.Sleep(100 * time.Millisecond)
    }
}

func main() {
    // Runs in a new goroutine
    go speak("Goroutine says: Hi!")

    // Runs in the main goroutine
    speak("Main says: Hello!")

    // Give the goroutine time to finish before main exits
    time.Sleep(1 * time.Second) 
}

The Catch: If the main function exits, the program kills all other running goroutines immediately. We need a way to synchronize them.

3. Synchronization with WaitGroups

Using time. Sleep to wait for goroutines is hacky. The correct way to wait for a collection of goroutines to finish is sync.WaitGroup.

package main

import (
    "fmt"
    "sync"
)

func worker(id int, wg *sync.WaitGroup) {
    defer wg.Done() // Decrement the counter when the function exits
    fmt.Printf("Worker %d starting\n", id)
    // Simulate work
    fmt.Printf("Worker %d done\n", id)
}

func main() {
    var wg sync.WaitGroup

    for i := 1; i <= 3; i++ {
        wg.Add(1) // Increment the counter
        go worker(i, &wg)
    }

    wg.Wait() // Block until the counter goes back to 0
    fmt.Println("All workers done")
}

4. Channels: "Share Memory By Communicating."

This is Go’s golden rule. Instead of locking variables with Mutexes (though Go has those too), you pass data between goroutines using channels.

Think of a channel as a pipe. One goroutine puts data in one end, and another picks it up from the other.

Unbuffered Channels
Unbuffered channels block the sender until the receiver is ready (and vice versa). This provides implicit synchronization.

package main

import "fmt"

func main() {
    messages := make(chan string)

    go func() {
        messages <- "ping" // Blocks here until "pong" is ready to receive
    }()

    msg := <-messages // Blocks here until "ping" is sent
    fmt.Println(msg)
}

5. Pattern: The Worker Pool

Let’s put it all together. A common pattern in backend development is the Worker Pool. You have a queue of jobs and a fixed number of workers processing them concurrently.

This is useful when you have 10,000 tasks but only want to process 5 at a time to save CPU/Memory.

package main

import (
    "fmt"
    "time"
)

// A job to be processed
func worker(id int, jobs <-chan int, results chan<- int) {
    for j := range jobs {
        fmt.Println("worker", id, "started  job", j)
        time.Sleep(time.Second) // Simulate expensive task
        fmt.Println("worker", id, "finished job", j)
        results <- j * 2
    }
}

func main() {
    const numJobs = 5
    jobs := make(chan int, numJobs)
    results := make(chan int, numJobs)

    // 1. Start 3 workers
    for w := 1; w <= 3; w++ {
        go worker(w, jobs, results)
    }

    // 2. Send 5 jobs to the jobs channel
    for j := 1; j <= numJobs; j++ {
        jobs <- j
    }
    close(jobs) // Close channel to signal no more jobs

    // 3. Collect results
    for a := 1; a <= numJobs; a++ {
        <-results
    }
}

Common Pitfalls

Deadlocks: If a goroutine is waiting for a channel that no one is writing to, Go will panic with a deadlock error.

Race Conditions: If two goroutines access the same variable without a lock or channel, the result is unpredictable. always run your tests with go test -race to catch these.

Leaking Goroutines: If you start a goroutine but it gets stuck waiting for a channel forever, it will never be garbage collected. This is a memory leak.

DEV Community: Md Murtuza Hussain

Beyond REST: Architecting High-Performance Microservices with gRPC in Go

Prerequisites and Workspace Setup

Project Structure

Step 1: Defining the Strict Contract (Protobuf)

Step 2: The REST Inventory API (Data Layer)

Testing the REST API with curl

Step 3: The gRPC Server (Calls the REST API)

Step 4: The gRPC Client

Step 5: Running the Full Stack

Configuring the REST API URL

Step 6: Debugging Binary Traffic with grpcurl

Production Considerations

TLS

Chaining Multiple Interceptors

HTTP Client Timeouts

Architectural Realities: When (and When Not) to Use gRPC

Where gRPC Excels

The Pragmatic Drawbacks

Summary

Laravel 13 Deep Dive: Every New Feature, Change with Code Example

1. The Great PHP Attributes Overhaul

Eloquent Models

Queue Jobs

Console Commands

Other Framework Components

2. The Cache::touch() Method

3. Laravel Reverb: The Database Driver

4. Starter Kits: First-Class Teams & Native Passkeys

Built-in Teams capabilities

Native Passkey Authentication

5. Granular Job Queue Control

6. The Laravel AI SDK Reaches Stable

7. Under the Hood: PHP 8.3 and Default Concurrency

Conclusion & Upgrade Timeline

How to Build an Enterprise-Grade App with Laravel 12 & React (Clean Architecture)

The Architecture Diagram & Request Lifecycle

The Directory Structure

The Backend: Laravel 12 Clean Architecture

1. Model & Database Setup

2. Routes (routes/api.php)

3. Policies & Gates (Authorization)

4. Form Requests (Validation)

5. The Repository Pattern (Data Access Layer)

6. The Service Class (Business Logic & Transactions)

7. Events & Listeners (Asynchronous Side-Effects)

8. API Resources (The Presentation Layer)

9. The Controller (The Traffic Cop)

10. Authentication (Bearer Tokens)

The Frontend: React & TypeScript Clean Architecture

The React Architecture Diagram

The React Directory Structure

1. The API Client & Interceptors

2. Types & Service Layer

3. Custom Hooks (React Query)

4. The Pure UI Component

Conclusion

[Boost]

How to Build a Production-Ready REST API in Go 1.26 with Full CRUD & JWT Authentication

How to Build a Production-Ready REST API in Go 1.26 with Full CRUD & JWT Authentication

Why Go for APIs in 2026?

The Architecture Diagram & Request Lifecycle

The Project Structure

Dependencies

Step 1: Configuration (internal/config/config.go)

Step 2: Database Migrations

Step 3: Domain Models (internal/model/models.go)

Step 4: JWT Authentication (internal/auth/jwt.go)

Step 5: Authentication Middleware (internal/auth/middleware.go)

Step 6: The Repository Layer

The User Repository (internal/repository/user_repository.go)

The Product Repository (internal/repository/product_repository.go)

Step 7: The Service Layer (Business Logic)

Auth Service (internal/service/auth_service.go)

Product Service (internal/service/product_service.go)

Step 8: The Handler Layer (HTTP Transport)

The Helper (internal/auth/middleware.go additions)

Auth Handler (internal/handler/auth_handler.go)

Product Handler (internal/handler/product_handler.go)

Step 9: Request Logging Middleware (internal/middleware/logger.go)

2. The `Cache::touch()` Method

2. Routes (`routes/api.php`)

Step 1: Configuration (`internal/config/config.go`)

Step 3: Domain Models (`internal/model/models.go`)

Step 4: JWT Authentication (`internal/auth/jwt.go`)

Step 5: Authentication Middleware (`internal/auth/middleware.go`)

The User Repository (`internal/repository/user_repository.go`)

The Product Repository (`internal/repository/product_repository.go`)

Auth Service (`internal/service/auth_service.go`)

Product Service (`internal/service/product_service.go`)

The Helper (`internal/auth/middleware.go` additions)

Auth Handler (`internal/handler/auth_handler.go`)

Product Handler (`internal/handler/product_handler.go`)

Step 9: Request Logging Middleware (`internal/middleware/logger.go`)

Step 10: The Entry Point — Wiring it All Together (`cmd/api/main.go`)

Step 11: Database Connection Pool (`internal/database/postgres.go`)

The `.env.example` file