feat: scaffold go backend foundation

internal/app/server.go

@@ -0,0 +1,19 @@
+package app
+
+import (
+	"net/http"
+
+	"tutor/internal/config"
+	"tutor/internal/httpapi"
+	"tutor/internal/workflows"
+)
+
+func NewServer(cfg config.Config) *http.Server {
+	runner := workflows.NewStubRunner()
+	handler := httpapi.NewHandler(cfg, runner)
+
+	return &http.Server{
+		Addr:    cfg.HTTPAddr,
+		Handler: handler.Routes(),
+	}
+}

internal/config/config.go

@@ -0,0 +1,37 @@
+package config
+
+import "os"
+
+const (
+	defaultHTTPAddr        = ":8080"
+	defaultEnvironment     = "development"
+	defaultModelKey        = "deepseek-v4-flash"
+	defaultThirdOneBin     = "thirdone"
+	defaultWorkflowRuntime = ""
+)
+
+type Config struct {
+	HTTPAddr        string
+	Environment     string
+	WorkflowRuntime string
+	ModelKey        string
+	ThirdOneBin     string
+}
+
+func LoadFromEnv() Config {
+	return Config{
+		HTTPAddr:        envOrDefault("TUTOR_HTTP_ADDR", defaultHTTPAddr),
+		Environment:     envOrDefault("TUTOR_ENV", defaultEnvironment),
+		WorkflowRuntime: envOrDefault("TUTOR_WORKFLOW_RUNTIME", defaultWorkflowRuntime),
+		ModelKey:        envOrDefault("TUTOR_MODEL_KEY", defaultModelKey),
+		ThirdOneBin:     envOrDefault("THIRDONE_BIN", defaultThirdOneBin),
+	}
+}
+
+func envOrDefault(key string, fallback string) string {
+	value := os.Getenv(key)
+	if value == "" {
+		return fallback
+	}
+	return value
+}

internal/config/config_test.go

@@ -0,0 +1,52 @@
+package config
+
+import "testing"
+
+func TestLoadFromEnvDefaults(t *testing.T) {
+	t.Setenv("TUTOR_HTTP_ADDR", "")
+	t.Setenv("TUTOR_ENV", "")
+	t.Setenv("TUTOR_WORKFLOW_RUNTIME", "")
+	t.Setenv("TUTOR_MODEL_KEY", "")
+	t.Setenv("THIRDONE_BIN", "")
+
+	cfg := LoadFromEnv()
+
+	if cfg.HTTPAddr != defaultHTTPAddr {
+		t.Fatalf("HTTPAddr = %q, want %q", cfg.HTTPAddr, defaultHTTPAddr)
+	}
+	if cfg.Environment != defaultEnvironment {
+		t.Fatalf("Environment = %q, want %q", cfg.Environment, defaultEnvironment)
+	}
+	if cfg.ModelKey != defaultModelKey {
+		t.Fatalf("ModelKey = %q, want %q", cfg.ModelKey, defaultModelKey)
+	}
+	if cfg.ThirdOneBin != defaultThirdOneBin {
+		t.Fatalf("ThirdOneBin = %q, want %q", cfg.ThirdOneBin, defaultThirdOneBin)
+	}
+}
+
+func TestLoadFromEnvOverrides(t *testing.T) {
+	t.Setenv("TUTOR_HTTP_ADDR", ":9090")
+	t.Setenv("TUTOR_ENV", "test")
+	t.Setenv("TUTOR_WORKFLOW_RUNTIME", "runtime.yaml")
+	t.Setenv("TUTOR_MODEL_KEY", "other-model")
+	t.Setenv("THIRDONE_BIN", "C:/bin/thirdone.exe")
+
+	cfg := LoadFromEnv()
+
+	if cfg.HTTPAddr != ":9090" {
+		t.Fatalf("HTTPAddr = %q", cfg.HTTPAddr)
+	}
+	if cfg.Environment != "test" {
+		t.Fatalf("Environment = %q", cfg.Environment)
+	}
+	if cfg.WorkflowRuntime != "runtime.yaml" {
+		t.Fatalf("WorkflowRuntime = %q", cfg.WorkflowRuntime)
+	}
+	if cfg.ModelKey != "other-model" {
+		t.Fatalf("ModelKey = %q", cfg.ModelKey)
+	}
+	if cfg.ThirdOneBin != "C:/bin/thirdone.exe" {
+		t.Fatalf("ThirdOneBin = %q", cfg.ThirdOneBin)
+	}
+}

internal/httpapi/handler.go

@@ -0,0 +1,47 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"tutor/internal/config"
+	"tutor/internal/workflows"
+)
+
+type Handler struct {
+	cfg    config.Config
+	runner workflows.Runner
+}
+
+func NewHandler(cfg config.Config, runner workflows.Runner) Handler {
+	return Handler{
+		cfg:    cfg,
+		runner: runner,
+	}
+}
+
+func (h Handler) Routes() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /healthz", h.health)
+	return mux
+}
+
+func (h Handler) health(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, healthResponse{
+		Status:      "ok",
+		Environment: h.cfg.Environment,
+		ModelKey:    h.cfg.ModelKey,
+	})
+}
+
+type healthResponse struct {
+	Status      string `json:"status"`
+	Environment string `json:"environment"`
+	ModelKey    string `json:"model_key"`
+}
+
+func writeJSON(w http.ResponseWriter, status int, value any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(value)
+}

internal/httpapi/handler_test.go

@@ -0,0 +1,42 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"tutor/internal/config"
+	"tutor/internal/workflows"
+)
+
+func TestHealth(t *testing.T) {
+	cfg := config.Config{
+		Environment: "test",
+		ModelKey:    "deepseek-v4-flash",
+	}
+	handler := NewHandler(cfg, workflows.NewStubRunner())
+
+	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	rec := httptest.NewRecorder()
+
+	handler.Routes().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body healthResponse
+	if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+		t.Fatalf("decode health response: %v", err)
+	}
+	if body.Status != "ok" {
+		t.Fatalf("body.Status = %q", body.Status)
+	}
+	if body.Environment != "test" {
+		t.Fatalf("body.Environment = %q", body.Environment)
+	}
+	if body.ModelKey != "deepseek-v4-flash" {
+		t.Fatalf("body.ModelKey = %q", body.ModelKey)
+	}
+}

internal/workflows/contracts.go

@@ -0,0 +1,192 @@
+package workflows
+
+type EvidenceKind string
+
+const (
+	EvidenceAnswer  EvidenceKind = "answer"
+	EvidenceGrading EvidenceKind = "grading"
+	EvidenceSource  EvidenceKind = "source"
+	EvidenceSession EvidenceKind = "session"
+	EvidenceAsset   EvidenceKind = "asset"
+)
+
+type EvidenceRef struct {
+	Kind       EvidenceKind `json:"kind"`
+	ID         string       `json:"id"`
+	Quote      string       `json:"quote,omitempty"`
+	Confidence float64      `json:"confidence"`
+}
+
+type ConceptRef struct {
+	ID    string `json:"id"`
+	Label string `json:"label"`
+	Track string `json:"track"`
+}
+
+type ReadinessState string
+
+const (
+	ReadinessUnknown        ReadinessState = "unknown"
+	ReadinessFragile        ReadinessState = "fragile"
+	ReadinessImproving      ReadinessState = "improving"
+	ReadinessInterviewReady ReadinessState = "interview_ready"
+	ReadinessStrongSignal   ReadinessState = "strong_signal"
+)
+
+type DiagnosticResult struct {
+	UserID                  string           `json:"user_id"`
+	Track                   string           `json:"track"`
+	TargetRole              string           `json:"target_role"`
+	Stack                   []string         `json:"stack"`
+	InitialReadiness        ReadinessState   `json:"initial_readiness"`
+	ConceptFindings         []ConceptFinding `json:"concept_findings"`
+	RecommendedNextConcepts []ConceptRef     `json:"recommended_next_concepts"`
+}
+
+type ConceptFinding struct {
+	Concept   ConceptRef     `json:"concept"`
+	Readiness ReadinessState `json:"readiness"`
+	Reason    string         `json:"reason"`
+	Evidence  []EvidenceRef  `json:"evidence"`
+}
+
+type GradedAnswer struct {
+	AnswerID                string                   `json:"answer_id"`
+	QuestionID              string                   `json:"question_id"`
+	Concepts                []ConceptRef             `json:"concepts"`
+	Scores                  AnswerScores             `json:"scores"`
+	Overall                 AnswerOverall            `json:"overall"`
+	Strengths               []string                 `json:"strengths"`
+	Gaps                    []string                 `json:"gaps"`
+	MisconceptionCandidates []MisconceptionCandidate `json:"misconception_candidates"`
+	FollowUp                FollowUpRecommendation   `json:"follow_up"`
+}
+
+type AnswerScores struct {
+	Correctness        int `json:"correctness"`
+	Depth              int `json:"depth"`
+	Communication      int `json:"communication"`
+	ProductionJudgment int `json:"production_judgment"`
+}
+
+type AnswerOverall string
+
+const (
+	AnswerMiss    AnswerOverall = "miss"
+	AnswerPartial AnswerOverall = "partial"
+	AnswerSolid   AnswerOverall = "solid"
+	AnswerStrong  AnswerOverall = "strong"
+)
+
+type MisconceptionCandidate struct {
+	Label       string        `json:"label"`
+	Description string        `json:"description"`
+	Evidence    []EvidenceRef `json:"evidence"`
+	Confidence  float64       `json:"confidence"`
+}
+
+type FollowUpRecommendation struct {
+	Needed   bool            `json:"needed"`
+	Question string          `json:"question,omitempty"`
+	Purpose  FollowUpPurpose `json:"purpose,omitempty"`
+}
+
+type FollowUpPurpose string
+
+const (
+	FollowUpClarify      FollowUpPurpose = "clarify"
+	FollowUpRepair       FollowUpPurpose = "repair"
+	FollowUpStretch      FollowUpPurpose = "stretch"
+	FollowUpPressureTest FollowUpPurpose = "pressure_test"
+)
+
+type MemoryUpdateCandidate struct {
+	UserID         string         `json:"user_id"`
+	SourceAnswerID string         `json:"source_answer_id"`
+	Updates        []MemoryUpdate `json:"updates"`
+}
+
+type MemoryUpdate struct {
+	Kind          MemoryUpdateKind `json:"kind"`
+	Concept       ConceptRef       `json:"concept"`
+	ProposedState ReadinessState   `json:"proposed_state"`
+	Summary       string           `json:"summary"`
+	Evidence      []EvidenceRef    `json:"evidence"`
+	Confidence    float64          `json:"confidence"`
+	Durability    Durability       `json:"durability"`
+}
+
+type MemoryUpdateKind string
+
+const (
+	MemoryConceptMastery MemoryUpdateKind = "concept_mastery"
+	MemoryMisconception  MemoryUpdateKind = "misconception"
+	MemoryIntervention   MemoryUpdateKind = "intervention"
+	MemoryReviewSchedule MemoryUpdateKind = "review_schedule"
+)
+
+type Durability string
+
+const (
+	DurabilityTentative Durability = "tentative"
+	DurabilityConfirmed Durability = "confirmed"
+)
+
+type NextChallenge struct {
+	UserID           string           `json:"user_id"`
+	Track            string           `json:"track"`
+	Concept          ConceptRef       `json:"concept"`
+	LadderLevel      LadderLevel      `json:"ladder_level"`
+	Question         string           `json:"question"`
+	Rationale        string           `json:"rationale"`
+	DifficultyAction DifficultyAction `json:"difficulty_action"`
+	Evidence         []EvidenceRef    `json:"evidence"`
+}
+
+type LadderLevel string
+
+const (
+	LadderDefine            LadderLevel = "define"
+	LadderTradeoffs         LadderLevel = "tradeoffs"
+	LadderDebug             LadderLevel = "debug"
+	LadderDesignConstraints LadderLevel = "design_constraints"
+	LadderInterviewPressure LadderLevel = "interview_pressure"
+)
+
+type DifficultyAction string
+
+const (
+	DifficultyLower   DifficultyAction = "lower"
+	DifficultyHold    DifficultyAction = "hold"
+	DifficultyRaise   DifficultyAction = "raise"
+	DifficultyRecover DifficultyAction = "recover"
+)
+
+type ReadinessUpdate struct {
+	UserID         string                  `json:"user_id"`
+	Track          string                  `json:"track"`
+	ConceptUpdates []ConceptReadinessDelta `json:"concept_updates"`
+	Unlocks        []Unlock                `json:"unlocks"`
+}
+
+type ConceptReadinessDelta struct {
+	Concept  ConceptRef     `json:"concept"`
+	Previous ReadinessState `json:"previous"`
+	Next     ReadinessState `json:"next"`
+	Reason   string         `json:"reason"`
+	Evidence []EvidenceRef  `json:"evidence"`
+}
+
+type Unlock struct {
+	Kind   UnlockKind `json:"kind"`
+	Label  string     `json:"label"`
+	Reason string     `json:"reason"`
+}
+
+type UnlockKind string
+
+const (
+	UnlockBossQuestion   UnlockKind = "boss_question"
+	UnlockReviewCard     UnlockKind = "review_card"
+	UnlockPortfolioEntry UnlockKind = "portfolio_entry"
+)

internal/workflows/runner.go

@@ -0,0 +1,66 @@
+package workflows
+
+import (
+	"context"
+	"errors"
+)
+
+var ErrNotImplemented = errors.New("workflow runner not implemented")
+
+type DiagnosticInput struct {
+	UserID     string
+	Track      string
+	TargetRole string
+	Stack      []string
+}
+
+type Runner interface {
+	DiagnoseJobSeeker(context.Context, DiagnosticInput) (DiagnosticResult, error)
+	GradeInterviewAnswer(context.Context, GradeAnswerInput) (GradedAnswer, error)
+	ExtractLearningMemory(context.Context, GradedAnswer) (MemoryUpdateCandidate, error)
+	SelectNextChallenge(context.Context, NextChallengeInput) (NextChallenge, error)
+	UpdateReadinessMap(context.Context, ReadinessUpdateInput) (ReadinessUpdate, error)
+}
+
+type GradeAnswerInput struct {
+	UserID     string
+	QuestionID string
+	AnswerID   string
+	AnswerText string
+}
+
+type NextChallengeInput struct {
+	UserID string
+	Track  string
+}
+
+type ReadinessUpdateInput struct {
+	UserID string
+	Track  string
+}
+
+type StubRunner struct{}
+
+func NewStubRunner() StubRunner {
+	return StubRunner{}
+}
+
+func (StubRunner) DiagnoseJobSeeker(context.Context, DiagnosticInput) (DiagnosticResult, error) {
+	return DiagnosticResult{}, ErrNotImplemented
+}
+
+func (StubRunner) GradeInterviewAnswer(context.Context, GradeAnswerInput) (GradedAnswer, error) {
+	return GradedAnswer{}, ErrNotImplemented
+}
+
+func (StubRunner) ExtractLearningMemory(context.Context, GradedAnswer) (MemoryUpdateCandidate, error) {
+	return MemoryUpdateCandidate{}, ErrNotImplemented
+}
+
+func (StubRunner) SelectNextChallenge(context.Context, NextChallengeInput) (NextChallenge, error) {
+	return NextChallenge{}, ErrNotImplemented
+}
+
+func (StubRunner) UpdateReadinessMap(context.Context, ReadinessUpdateInput) (ReadinessUpdate, error) {
+	return ReadinessUpdate{}, ErrNotImplemented
+}

internal/workflows/runner_test.go

@@ -0,0 +1,21 @@
+package workflows
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestStubRunnerReturnsTypedNotImplemented(t *testing.T) {
+	runner := NewStubRunner()
+
+	_, err := runner.DiagnoseJobSeeker(context.Background(), DiagnosticInput{
+		UserID:     "user-1",
+		Track:      "backend-developer",
+		TargetRole: "junior-backend-developer",
+	})
+
+	if !errors.Is(err, ErrNotImplemented) {
+		t.Fatalf("err = %v, want %v", err, ErrNotImplemented)
+	}
+}