feat: add tests, health probes, PVCs, and project docs

- Add K8sBackend interface to decouple handlers from concrete k8s client
- Add unit tests: 12 backend handler tests + 10 CLI tests (no cluster needed)
- Add liveness/readiness health probes to all 6 deployment templates
- Add PVC templates for MongoDB (mern) and PostgreSQL (go-api) with volume mounts
- Add ApplyPVC to k8s client; wire into manifest apply order (pvc→quota→cm→svc→deploy→ingress)
- Rewrite README with architecture diagram, problem statement, deployment guide, folder structure
- Add docs/STRUCTURE.md: full annotated file tree + design decisions
- Add docs/DEPLOYMENT.md: 3 deployment options, troubleshooting, CI/CD docs
- Improve docs/demo.html: spinner animation, auto-loop, replay button, status bar
- Remove stale empty top-level templates/ directory

Author: abhay1999

README.md

@@ -1,6 +1,7 @@
 package handlers
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -11,14 +12,26 @@ import (
 
 	"github.com/go-chi/chi/v5"
 
-	k8sclient "github.com/abhaychaurasiya/devctl-backend/internal/k8s"
 	"github.com/abhaychaurasiya/devctl-backend/internal/models"
 	"github.com/abhaychaurasiya/devctl-backend/internal/templates"
 )
 
+// K8sBackend abstracts the Kubernetes operations used by handlers.
+type K8sBackend interface {
+	CreateNamespace(ctx context.Context, name, username, template string, expiresAt time.Time) error
+	DeleteNamespace(ctx context.Context, name string) error
+	GetEnvironmentStatus(ctx context.Context, namespace string) (*models.EnvironmentStatusResponse, error)
+	ApplyResourceQuota(ctx context.Context, namespace string, manifest []byte) error
+	ApplyConfigMap(ctx context.Context, namespace string, manifest []byte) error
+	ApplyService(ctx context.Context, namespace string, manifest []byte) error
+	ApplyDeployment(ctx context.Context, namespace string, manifest []byte) error
+	ApplyIngress(ctx context.Context, namespace string, manifest []byte) error
+	ApplyPVC(ctx context.Context, namespace string, manifest []byte) error
+}
+
 // Handler holds shared dependencies for all HTTP handlers.
 type Handler struct {
-	K8s      *k8sclient.Client
+	K8s      K8sBackend
 	Loader   *templates.Loader
 	Renderer *templates.Renderer
 }
@@ -75,11 +88,16 @@ func (h *Handler) CreateEnvironment(w http.ResponseWriter, r *http.Request) {
 	}
 
 	// Apply rendered manifests in dependency order:
-	// resourcequota -> configmaps -> services -> deployments -> ingress
+	// pvc -> resourcequota -> configmaps -> services -> deployments -> ingress
 	for _, path := range orderedKeys(rendered) {
 		manifest := rendered[path]
 		base := filepath.Base(path)
 		switch {
+		case strings.Contains(base, "pvc"):
+			if err := h.K8s.ApplyPVC(ctx, vars.Namespace, manifest); err != nil {
+				http.Error(w, "failed to apply pvc: "+err.Error(), http.StatusInternalServerError)
+				return
+			}
 		case strings.Contains(base, "resourcequota"):
 			if err := h.K8s.ApplyResourceQuota(ctx, vars.Namespace, manifest); err != nil {
 				http.Error(w, "failed to apply resourcequota: "+err.Error(), http.StatusInternalServerError)
@@ -176,10 +194,10 @@ func parseExpiry(ttl string) (time.Time, error) {
 	return time.Now().Add(dur), nil
 }
 
-// orderedKeys returns manifest paths sorted so resourcequotas and configmaps
-// are applied before services, deployments, and ingresses.
+// orderedKeys returns manifest paths sorted so pvcs and resourcequotas are
+// applied before configmaps, services, deployments, and ingresses.
 func orderedKeys(m map[string][]byte) []string {
-	order := []string{"resourcequota", "configmap", "service", "deployment", "ingress"}
+	order := []string{"pvc", "resourcequota", "configmap", "service", "deployment", "ingress"}
 	var sorted []string
 	for _, kind := range order {
 		for k := range m {

backend/internal/api/handlers/environments.go

@@ -0,0 +1,247 @@
+package handlers
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/abhaychaurasiya/devctl-backend/internal/models"
+	"github.com/abhaychaurasiya/devctl-backend/internal/templates"
+)
+
+func newTestHandler(k8s K8sBackend) *Handler {
+	loader := templates.NewLoader()
+	return &Handler{
+		K8s:      k8s,
+		Loader:   loader,
+		Renderer: templates.NewRenderer(loader),
+	}
+}
+
+func TestCreateEnvironment_Success(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	body, _ := json.Marshal(map[string]string{
+		"template": "react",
+		"username": "alice",
+		"ttl":      "30m",
+	})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/environments", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	h.CreateEnvironment(w, req)
+
+	if w.Code != http.StatusAccepted {
+		t.Errorf("expected 202, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp models.CreateEnvResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+	if resp.Namespace != "dev-alice" {
+		t.Errorf("expected namespace dev-alice, got %s", resp.Namespace)
+	}
+	if resp.URL != "http://alice-react.dev.local" {
+		t.Errorf("expected URL http://alice-react.dev.local, got %s", resp.URL)
+	}
+	if resp.Status != string(models.StatusProvisioning) {
+		t.Errorf("expected status Provisioning, got %s", resp.Status)
+	}
+}
+
+func TestCreateEnvironment_InvalidUsername(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	body, _ := json.Marshal(map[string]string{
+		"template": "react",
+		"username": "Alice_INVALID!",
+		"ttl":      "30m",
+	})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/environments", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	h.CreateEnvironment(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestCreateEnvironment_UnknownTemplate(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	body, _ := json.Marshal(map[string]string{
+		"template": "nonexistent",
+		"username": "bob",
+		"ttl":      "30m",
+	})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/environments", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	h.CreateEnvironment(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("expected 404, got %d", w.Code)
+	}
+}
+
+func TestCreateEnvironment_InvalidTTL(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	body, _ := json.Marshal(map[string]string{
+		"template": "react",
+		"username": "alice",
+		"ttl":      "notaduration",
+	})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/environments", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	h.CreateEnvironment(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestCreateEnvironment_DefaultTTL(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	// No TTL field — should default to "30m" without error
+	body, _ := json.Marshal(map[string]string{
+		"template": "react",
+		"username": "alice",
+	})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/environments", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	h.CreateEnvironment(w, req)
+
+	if w.Code != http.StatusAccepted {
+		t.Errorf("expected 202 with default TTL, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestCreateEnvironment_InvalidBody(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/environments", bytes.NewReader([]byte("notjson{")))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	h.CreateEnvironment(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d", w.Code)
+	}
+}
+
+func TestDeleteEnvironment_Success(t *testing.T) {
+	h := newTestHandler(&mockK8s{})
+
+	r := chi.NewRouter()
+	r.Delete("/api/v1/environments/{name}", h.DeleteEnvironment)
+
+	req := httptest.NewRequest(http.MethodDelete, "/api/v1/environments/dev-alice", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusNoContent {
+		t.Errorf("expected 204, got %d", w.Code)
+	}
+}
+
+func TestGetEnvironmentStatus_Success(t *testing.T) {
+	now := time.Now()
+	statusResp := &models.EnvironmentStatusResponse{
+		Phase: models.StatusReady,
+		Services: []models.ServiceStatus{
+			{Name: "react", Phase: "Running", Ready: true},
+		},
+		URL:       "http://alice-react.dev.local",
+		CreatedAt: now,
+		ExpiresAt: now.Add(30 * time.Minute),
+	}
+	h := newTestHandler(&mockK8s{statusResp: statusResp})
+
+	r := chi.NewRouter()
+	r.Get("/api/v1/environments/{name}/status", h.GetEnvironmentStatus)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/environments/alice-react/status", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d", w.Code)
+	}
+
+	var resp models.EnvironmentStatusResponse
+	if err := json.NewDecoder(w.Body).Decode(&resp); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+	if resp.Phase != models.StatusReady {
+		t.Errorf("expected phase Ready, got %s", resp.Phase)
+	}
+	if resp.URL != "http://alice-react.dev.local" {
+		t.Errorf("unexpected URL: %s", resp.URL)
+	}
+}
+
+func TestNameToNamespace(t *testing.T) {
+	cases := []struct {
+		input    string
+		expected string
+	}{
+		{"dev-alice", "dev-alice"},
+		{"alice-mern", "dev-alice"},
+		{"bob-go-api", "dev-bob"},
+	}
+	for _, c := range cases {
+		got := nameToNamespace(c.input)
+		if got != c.expected {
+			t.Errorf("nameToNamespace(%q) = %q, want %q", c.input, got, c.expected)
+		}
+	}
+}
+
+func TestOrderedKeys(t *testing.T) {
+	m := map[string][]byte{
+		"templates/mern/ingress.yaml.tmpl":              {},
+		"templates/mern/mongodb/deployment.yaml.tmpl":   {},
+		"templates/mern/mongodb/pvc.yaml.tmpl":          {},
+		"templates/mern/resourcequota.yaml.tmpl":        {},
+		"templates/mern/express/configmap.yaml.tmpl":    {},
+		"templates/mern/express/service.yaml.tmpl":      {},
+	}
+
+	keys := orderedKeys(m)
+
+	// Build an index map for position lookup
+	pos := make(map[string]int, len(keys))
+	for i, k := range keys {
+		pos[k] = i
+	}
+
+	checks := []struct{ before, after string }{
+		{"templates/mern/mongodb/pvc.yaml.tmpl", "templates/mern/resourcequota.yaml.tmpl"},
+		{"templates/mern/resourcequota.yaml.tmpl", "templates/mern/express/configmap.yaml.tmpl"},
+		{"templates/mern/express/configmap.yaml.tmpl", "templates/mern/express/service.yaml.tmpl"},
+		{"templates/mern/express/service.yaml.tmpl", "templates/mern/mongodb/deployment.yaml.tmpl"},
+		{"templates/mern/mongodb/deployment.yaml.tmpl", "templates/mern/ingress.yaml.tmpl"},
+	}
+	for _, c := range checks {
+		if pos[c.before] >= pos[c.after] {
+			t.Errorf("%q should come before %q in ordered keys", c.before, c.after)
+		}
+	}
+}

backend/internal/api/handlers/environments_test.go

@@ -0,0 +1,36 @@
+package handlers
+
+import (
+	"context"
+	"time"
+
+	"github.com/abhaychaurasiya/devctl-backend/internal/models"
+)
+
+// mockK8s is a test double for K8sBackend.
+type mockK8s struct {
+	createNSErr   error
+	deleteNSErr   error
+	statusResp    *models.EnvironmentStatusResponse
+	statusErr     error
+	applyErr      error
+}
+
+func (m *mockK8s) CreateNamespace(_ context.Context, _, _, _ string, _ time.Time) error {
+	return m.createNSErr
+}
+
+func (m *mockK8s) DeleteNamespace(_ context.Context, _ string) error {
+	return m.deleteNSErr
+}
+
+func (m *mockK8s) GetEnvironmentStatus(_ context.Context, _ string) (*models.EnvironmentStatusResponse, error) {
+	return m.statusResp, m.statusErr
+}
+
+func (m *mockK8s) ApplyResourceQuota(_ context.Context, _ string, _ []byte) error { return m.applyErr }
+func (m *mockK8s) ApplyConfigMap(_ context.Context, _ string, _ []byte) error     { return m.applyErr }
+func (m *mockK8s) ApplyService(_ context.Context, _ string, _ []byte) error       { return m.applyErr }
+func (m *mockK8s) ApplyDeployment(_ context.Context, _ string, _ []byte) error    { return m.applyErr }
+func (m *mockK8s) ApplyIngress(_ context.Context, _ string, _ []byte) error       { return m.applyErr }
+func (m *mockK8s) ApplyPVC(_ context.Context, _ string, _ []byte) error           { return m.applyErr }