hanzo-coursework-fullstack-go-cloud

This coursework trains engineering teams migrating from slow, interpreted, memory-heavy environments (Python, Next.js, Node.js, Ruby on Rails) to Hanzo's high-performance native stack (Go, Rust, C++).

Coursework: Fullstack Cloud Engineering with Go & Hanzo Base

Category: Hanzo Ecosystem & Engineering Curriculum Level: Intermediate to Advanced Prerequisites: Familiarity with web services, basic understanding of concurrency. Related Skills: hanzo/hanzo-migrate-backend-to-go.md, hanzo/hanzo-base.md, hanzo/hanzo-cloud.md, hanzo/hanzo-tutorial-realtime-sse-backend.md, hanzo/hanzo-examples-native-cloud.md

---

Curriculum Overview

This coursework trains engineering teams migrating from slow, interpreted, memory-heavy environments (Python, Next.js, Node.js, Ruby on Rails) to Hanzo's high-performance native stack (Go, Rust, C++).

┌─────────────────────────────────────────────────────────────────────────────┐
│               CURRICULUM: FULLSTACK CLOUD ENGINEERING WITH GO               │
│                                                                             │
│   [MODULE 1] Architectural Foundations & Runtime Shift                     │
│              - Why native compiled code wins: Go, Rust & C++                │
│              - Benchmarking: 15ms cold starts vs 6s Next.js SSR             │
│                                                                             │
│   [MODULE 2] Running Your Own Cloud Locally                                 │
│              - Base and the open-source cloud, from a checkout              │
│              - start commands: skill.md, On your own machine                │
│                                                                             │
│   [MODULE 3] Realtime SSE Streaming & State Synchronization                 │
│              - Native Server-Sent Events (SSE) in Go                        │
│              - Zero-overhead streaming without Pusher / external SaaS       │
│                                                                             │
│   [MODULE 4] Extending Hanzo Cloud with `/v1/*` Subsystems                  │
│              - Plugin host architecture & ZAP binary transport (HIP-0114)   │
│              - Wiring routes in `manifest/apps.go`                          │
│                                                                             │
│   [MODULE 5] Production Observability, Storage & Deployment                 │
│              - Embedded SQLite + ClickHouse datastore hybrid                │
│              - Zero-dependency static binary deployments (`CGO_ENABLED=0`)  │
└─────────────────────────────────────────────────────────────────────────────┘

---

Module 1: The Runtime Shift (Python/Next.js to Native Go)

1.1 The Cost of Interpreted Runtimes

Interpreted runtimes impose hidden taxes in enterprise environments:

• Python: The Global Interpreter Lock (GIL) serializes threads; async runtimes (asyncio) suffer from event-loop starvation and heavy memory fragmentation.
• Node.js / Next.js: Gigabytes of node_modules, cold start latencies (1.5s - 8s), high idle footprint (250MB+ per SSR container), and fragile build tooling.
• Java / Spring: High JVM memory overhead and slow warmup periods.

1.2 The Hanzo Triad

1. Go (github.com/hanzoai/base, github.com/hanzoai/cloud):

• Compiles to a single static binary (CGO_ENABLED=0).
• Memory footprint: ~15MB idle.
• Concurrency: Goroutines scheduled on M:N runtime with non-blocking network pollers.

1. Rust (hanzoai/engine, hanzoai/reth):

• Zero-cost abstractions, deterministic memory safety without GC pauses.
• Inference execution and cryptographic settlement.

1. C++ (Metal, CUDA, ANE):

• Bare-metal hardware kernels for Apple Silicon and NVIDIA tensor cores.

1.3 Lab 1: Profiling Memory & Cold Starts

Compare a basic Next.js / FastAPI endpoint against a Go Hanzo Base endpoint:

# Build Go binary statically
CGO_ENABLED=0 go build -ldflags="-s -w" -o ./bin/server ./main.go

# Inspect size and launch time
ls -lh ./bin/server
time ./bin/server --healthcheck

Expected Result: Binary size < 25MB, startup time < 15 milliseconds.

---

Module 2: Run It Locally

Base and the open-source cloud start from a checkout, with no account.

The Philosophy

Never mock third-party cloud APIs. Run the actual Hanzo services in-process.

Lab 2: Launch & Healthcheck

# Base, in a checkout of github.com/hanzoai/base
go run ./examples/base serve
curl -i http://127.0.0.1:8090/v1/health           # from a second terminal

# the cloud, in a checkout of github.com/hanzoai/cloud
make build && CLOUD_DEV_UNENCRYPTED=1 CLOUD_LISTEN=127.0.0.1:8080 CLOUD_DATA_DIR=.dev/data ./cloud
curl -s http://127.0.0.1:8080/v1/openapi.json     # from a second terminal

The cloud runs unencrypted this way, for local development only. Every part that runs locally, and what needs the hosted cloud, is in skill.md under On your own machine.

---

Module 3: Realtime Native SSE (Server-Sent Events)

3.1 Why Native SSE Over WebSockets?

• Built directly on HTTP/1.1 and HTTP/2 (RFC 8895).
• Automatic browser reconnection via Last-Event-ID.
• Zero firewall or proxy websocket-upgrade friction.
• Efficient unidirectional event delivery for LLM tokens, notifications, and analytics.

3.2 Implementing the Hub in Go

A lock-free, concurrent SSE multiplexer:

package realtime

import (
	"fmt"
	"net/http"
	"sync"
	"time"
)

type Event struct {
	ID    string
	Event string
	Data  []byte
}

type Hub struct {
	mu      sync.RWMutex
	clients map[chan Event]struct{}
}

func NewHub() *Hub {
	return &Hub{
		clients: make(map[chan Event]struct{}),
	}
}

func (h *Hub) Subscribe() chan Event {
	ch := make(chan Event, 64)
	h.mu.Lock()
	h.clients[ch] = struct{}{}
	h.mu.Unlock()
	return ch
}

func (h *Hub) Unsubscribe(ch chan Event) {
	h.mu.Lock()
	delete(h.clients, ch)
	close(ch)
	h.mu.Unlock()
}

func (h *Hub) Broadcast(e Event) {
	h.mu.RLock()
	defer h.mu.RUnlock()
	for ch := range h.clients {
		select {
		case ch <- e:
		default:
			// Client channel full; drop or handle slow consumer
		}
	}
}

func (h *Hub) Handler() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		flusher, ok := w.(http.Flusher)
		if !ok {
			http.Error(w, "Streaming unsupported", http.StatusInternalServerError)
			return
		}

		w.Header().Set("Content-Type", "text/event-stream")
		w.Header().Set("Cache-Control", "no-cache")
		w.Header().Set("Connection", "keep-alive")
		w.Header().Set("X-Accel-Buffering", "no")

		ch := h.Subscribe()
		defer h.Unsubscribe(ch)

		ticker := time.NewTicker(15 * time.Second)
		defer ticker.Stop()

		for {
			select {
			case <-r.Context().Done():
				return
			case <-ticker.C:
				fmt.Fprintf(w, ": heartbeat\n\n")
				flusher.Flush()
			case e := <-ch:
				if e.ID != "" {
					fmt.Fprintf(w, "id: %s\n", e.ID)
				}
				if e.Event != "" {
					fmt.Fprintf(w, "event: %s\n", e.Event)
				}
				fmt.Fprintf(w, "data: %s\n\n", e.Data)
				flusher.Flush()
			}
		}
	}
}

3.3 Lab 3: Verifying SSE Streams with cURL

# Listen to live stream
curl -N http://localhost:8090/v1/events/stream

---

Module 4: Extending Hanzo Cloud with /v1/* Subsystems

Hanzo Cloud (hanzoai/cloud) uses a host + plugin registry architecture connected via ZAP Transport (HIP-0114).

4.1 Subsystem Interface

Every subsystem implements cloud.Plugin:

package custom

import (
	"net/http"
	"github.com/hanzoai/cloud"
)

func init() {
	cloud.Register("analytics-custom", NewPlugin)
}

type Plugin struct{}

func NewPlugin(cfg *cloud.Config) (cloud.Plugin, error) {
	return &Plugin{}, nil
}

func (p *Plugin) Mount(mux *http.ServeMux) {
	mux.HandleFunc("POST /v1/custom/ingest", p.HandleIngest)
	mux.HandleFunc("GET /v1/custom/stats", p.HandleStats)
}

func (p *Plugin) HandleIngest(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusAccepted)
	w.Write([]byte(`{"status":"queued"}`))
}

func (p *Plugin) HandleStats(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	w.Write([]byte(`{"active_workers":16,"throughput_per_sec":124000}`))
}

---

Module 5: Storage & Observability

5.1 Hybrid Storage

• Transactional State: Embedded SQLite (modernc.org/sqlite) for single-binary zero-dependency nodes or PostgreSQL (pgx/v5).
• Telemetry & Logs: Columnar ClickHouse datastore.

5.2 Test-Driven Development (TDD)

Every module must ship with automated tests proving correctness:

// hub_test.go
package realtime_test

import (
	"context"
	"net/http"
	"net/http/httptest"
	"testing"
	"time"

	"github.com/hanzoai/base/realtime"
)

func TestSSEHub(t *testing.T) {
	hub := realtime.NewHub()
	server := httptest.NewServer(hub.Handler())
	defer server.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()

	req, _ := http.NewRequestWithContext(ctx, "GET", server.URL, nil)
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		t.Fatalf("Failed to connect to SSE stream: %v", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		t.Errorf("Expected status 200, got %d", resp.StatusCode)
	}

	if ct := resp.Header.Get("Content-Type"); ct != "text/event-stream" {
		t.Errorf("Expected Content-Type text/event-stream, got %s", ct)
	}
}

---

Conclusion & Certification

By completing this coursework, your engineering team possesses the patterns, tooling, and architectural foundation to:

1. Eliminate legacy interpreted runtimes in favor of compiled Go and Rust.
2. Build and run offline-ready local cloud environments.
3. Stream realtime data natively via SSE.
4. Scale seamlessly against Hanzo AI Cloud (hanzo.ai and api.hanzo.ai).