package httpapi import ( "context" "encoding/base64" "errors" "io" "log/slog" "net/http" "strings" "time" "speech-learning-api/internal/config" "speech-learning-api/internal/domain" "speech-learning-api/internal/services" ) type DataStore interface { GetUser(ctx context.Context, id string) (domain.User, error) GetPrimaryProfile(ctx context.Context, userID string) (domain.LearnerProfile, error) UpdatePreferences(ctx context.Context, userID, uiLanguage, targetLanguage, cefrLevel string, dailyGoalMinutes int) (domain.LearnerProfile, error) ListLanguages(ctx context.Context) ([]domain.LanguageProfile, error) GetLanguage(ctx context.Context, code string) (domain.LanguageProfile, error) NextLessonAndExercise(ctx context.Context, profile domain.LearnerProfile, avoidReferenceText ...string) (domain.Lesson, domain.Exercise, error) SaveGeneratedExercise(ctx context.Context, userID string, generated domain.GeneratedExercise) (domain.Lesson, domain.Exercise, error) GetExercise(ctx context.Context, id, userID string) (domain.Exercise, error) SaveAttempt(ctx context.Context, attempt domain.Attempt) (domain.Attempt, error) Progress(ctx context.Context, userID string, limit int) (domain.ProgressSummary, error) AdminOverview(ctx context.Context) (domain.AdminOverview, error) AdminUsers(ctx context.Context, search string, page int) (domain.AdminUserPage, error) CreateConversationSession(ctx context.Context, userID, targetLanguage, cefrLevel string) (domain.ConversationSession, error) SaveConversationTurn(ctx context.Context, turn domain.ConversationTurn) (domain.ConversationTurn, error) DebugStatus(ctx context.Context) domain.DebugDBStatus } type Server struct { cfg config.Config logger *slog.Logger store DataStore auth *services.AuthService speech services.SpeechService teacher services.TeacherAgent started time.Time } func NewServer(cfg config.Config, logger *slog.Logger, store DataStore, auth *services.AuthService, speech services.SpeechService, teacher services.TeacherAgent) *Server { return &Server{cfg: cfg, logger: logger, store: store, auth: auth, speech: speech, teacher: teacher, started: time.Now()} } func (s *Server) Routes() http.Handler { mux := http.NewServeMux() mux.HandleFunc("GET /health", s.health) mux.HandleFunc("POST /auth/register", s.register) mux.HandleFunc("POST /auth/login", s.login) mux.HandleFunc("POST /auth/logout", s.logout) mux.Handle("GET /me", s.requireAuth(http.HandlerFunc(s.me))) mux.Handle("PATCH /me/preferences", s.requireAuth(http.HandlerFunc(s.updatePreferences))) mux.Handle("GET /languages", s.requireAuth(http.HandlerFunc(s.languages))) mux.Handle("GET /languages/{code}/voices", s.requireAuth(http.HandlerFunc(s.languageVoices))) mux.Handle("GET /dashboard", s.requireAuth(http.HandlerFunc(s.dashboard))) mux.Handle("GET /progress", s.requireAuth(http.HandlerFunc(s.progress))) mux.Handle("POST /lessons/next", s.requireAuth(http.HandlerFunc(s.nextLesson))) mux.Handle("GET /practice/exercises/{id}/audio", s.requireAuth(http.HandlerFunc(s.exerciseAudio))) mux.Handle("POST /practice/attempts", s.requireAuth(http.HandlerFunc(s.createAttempt))) mux.Handle("POST /conversation/start", s.requireAuth(http.HandlerFunc(s.startConversation))) mux.Handle("POST /conversation/{id}/turn", s.requireAuth(http.HandlerFunc(s.conversationTurn))) mux.Handle("GET /admin/overview", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.adminOverview)))) mux.Handle("GET /admin/users", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.adminUsers)))) if s.cfg.DebugEnabled { mux.Handle("GET /debug/status", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugStatus)))) mux.Handle("GET /debug/db", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugDB)))) mux.Handle("GET /debug/flowise", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugFlowise)))) mux.Handle("GET /debug/azure", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugAzure)))) mux.Handle("GET /debug/runtime", s.requireAuth(s.requireAdmin(http.HandlerFunc(s.debugRuntime)))) } return s.requestID(s.requestLogging(s.cors(mux))) } func (s *Server) health(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, map[string]string{"status": "ok"}) } func (s *Server) register(w http.ResponseWriter, r *http.Request) { var req struct { Email string `json:"email"` Password string `json:"password"` UILanguage string `json:"ui_language"` TargetLanguage string `json:"target_language"` DailyGoalMinutes int `json:"daily_goal_minutes"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } result, err := s.auth.Register(r.Context(), req.Email, req.Password, req.UILanguage, req.TargetLanguage, req.DailyGoalMinutes) if err != nil { writeError(w, http.StatusBadRequest, err) return } writeJSON(w, http.StatusCreated, result) } func (s *Server) login(w http.ResponseWriter, r *http.Request) { var req struct { Email string `json:"email"` Password string `json:"password"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } result, err := s.auth.Login(r.Context(), req.Email, req.Password) if err != nil { status := http.StatusInternalServerError if errors.Is(err, services.ErrInvalidCredentials) { status = http.StatusUnauthorized } writeError(w, status, err) return } writeJSON(w, http.StatusOK, result) } func (s *Server) logout(w http.ResponseWriter, r *http.Request) { writeJSON(w, http.StatusOK, map[string]string{"status": "ok"}) } func (s *Server) me(w http.ResponseWriter, r *http.Request) { user, err := s.store.GetUser(r.Context(), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), user.ID) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, map[string]any{"user": user, "profile": profile}) } func (s *Server) updatePreferences(w http.ResponseWriter, r *http.Request) { var req struct { UILanguage string `json:"ui_language"` TargetLanguage string `json:"target_language"` CEFRLevel string `json:"cefr_level"` DailyGoalMinutes int `json:"daily_goal_minutes"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } profile, err := s.store.UpdatePreferences(r.Context(), currentUserID(r), req.UILanguage, req.TargetLanguage, valueOr(req.CEFRLevel, "A1"), req.DailyGoalMinutes) if err != nil { writeError(w, http.StatusBadRequest, err) return } writeJSON(w, http.StatusOK, profile) } func (s *Server) languages(w http.ResponseWriter, r *http.Request) { languages, err := s.store.ListLanguages(r.Context()) if err != nil { writeError(w, http.StatusInternalServerError, err) return } writeJSON(w, http.StatusOK, languages) } func (s *Server) languageVoices(w http.ResponseWriter, r *http.Request) { lang, err := s.store.GetLanguage(r.Context(), r.PathValue("code")) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, map[string]any{"code": lang.Code, "voices": lang.Voices, "default_voice": lang.DefaultTTSVoice}) } func (s *Server) dashboard(w http.ResponseWriter, r *http.Request) { userID := currentUserID(r) user, err := s.store.GetUser(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } progress, err := s.store.Progress(r.Context(), userID, 5) if err != nil { writeError(w, http.StatusInternalServerError, err) return } lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, nil) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, domain.Dashboard{ User: user, Profile: profile, Progress: progress, NextLesson: lesson, NextExercise: exercise, }) } func (s *Server) progress(w http.ResponseWriter, r *http.Request) { progress, err := s.store.Progress(r.Context(), currentUserID(r), 20) if err != nil { writeError(w, http.StatusInternalServerError, err) return } writeJSON(w, http.StatusOK, progress) } func (s *Server) nextLesson(w http.ResponseWriter, r *http.Request) { userID := currentUserID(r) var req struct { PreviousExerciseID string `json:"previous_exercise_id"` RecentExerciseIDs []string `json:"recent_exercise_ids"` } if err := decodeJSON(r, &req); err != nil && !errors.Is(err, io.EOF) { writeError(w, http.StatusBadRequest, err) return } recentIDs := req.RecentExerciseIDs if req.PreviousExerciseID != "" && (len(recentIDs) == 0 || recentIDs[len(recentIDs)-1] != req.PreviousExerciseID) { recentIDs = append(recentIDs, req.PreviousExerciseID) } if len(recentIDs) > 3 { writeError(w, http.StatusBadRequest, errors.New("at most three recent exercises are allowed")) return } avoidReferenceTexts := make([]string, 0, len(recentIDs)) for _, id := range recentIDs { previous, err := s.store.GetExercise(r.Context(), id, userID) if err != nil { writeError(w, http.StatusNotFound, err) return } avoidReferenceTexts = append(avoidReferenceTexts, previous.TargetText) } user, err := s.store.GetUser(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), userID) if err != nil { writeError(w, http.StatusNotFound, err) return } progress, err := s.store.Progress(r.Context(), userID, 10) if err != nil { writeError(w, http.StatusInternalServerError, err) return } lesson, exercise, err := s.nextAgentExercise(r.Context(), user, profile, progress, avoidReferenceTexts) if err != nil { writeError(w, http.StatusNotFound, err) return } writeJSON(w, http.StatusOK, map[string]any{"lesson": lesson, "exercise": exercise}) } func (s *Server) nextAgentExercise(ctx context.Context, user domain.User, profile domain.LearnerProfile, progress domain.ProgressSummary, avoidReferenceTexts []string) (domain.Lesson, domain.Exercise, error) { avoidReferenceText := "" if len(avoidReferenceTexts) > 0 { avoidReferenceText = avoidReferenceTexts[len(avoidReferenceTexts)-1] } generated, err := s.teacher.NextExercise(ctx, domain.GeneratedExerciseRequest{ UserID: user.ID, Profile: profile, Progress: progress, TargetLanguage: profile.TargetLanguage, CEFRLevel: profile.CEFRLevel, UILanguage: user.UILanguage, SessionID: flowiseSessionID(user.ID, profile.TargetLanguage, "practice"), RecentWeakWords: progress.WeakWords, PreferredType: "repeat_sentence", AvoidReferenceText: avoidReferenceText, AvoidReferenceTexts: avoidReferenceTexts, }) if err == nil && generated.Source == "flowise" && strings.TrimSpace(generated.ReferenceText) != "" { lesson, exercise, saveErr := s.store.SaveGeneratedExercise(ctx, user.ID, generated) if saveErr == nil { s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID) return lesson, exercise, nil } s.logger.Warn("saving generated exercise failed, using seed fallback", "error", saveErr) } if err != nil { s.logger.Warn("flowise next exercise failed, using seed fallback", "error", err) } lesson, exercise, err := s.store.NextLessonAndExercise(ctx, profile, avoidReferenceTexts...) if err == nil { s.logger.Info("next exercise selected", "request_id", ctx.Value(requestIDKey), "source", exercise.Source, "exercise_id", exercise.ID) } return lesson, exercise, err } func (s *Server) exerciseAudio(w http.ResponseWriter, r *http.Request) { exercise, err := s.store.GetExercise(r.Context(), r.PathValue("id"), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } language, err := s.store.GetLanguage(r.Context(), exercise.TargetLanguage) if err != nil { writeError(w, http.StatusInternalServerError, err) return } audio, mime, err := s.speech.Synthesize(r.Context(), language.AzureLocale, language.DefaultTTSVoice, exercise.TargetText) if err != nil { writeError(w, http.StatusBadGateway, err) return } if len(audio) == 0 { writeError(w, http.StatusServiceUnavailable, errors.New("audio is unavailable")) return } w.Header().Set("Content-Type", mime) w.Header().Set("Cache-Control", "private, no-store") w.WriteHeader(http.StatusOK) _, _ = w.Write(audio) } func (s *Server) createAttempt(w http.ResponseWriter, r *http.Request) { if err := r.ParseMultipartForm(24 << 20); err != nil { writeError(w, http.StatusBadRequest, err) return } exerciseID := r.FormValue("exercise_id") exercise, err := s.store.GetExercise(r.Context(), exerciseID, currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } file, header, err := r.FormFile("audio") if err != nil { writeError(w, http.StatusBadRequest, errors.New("audio file is required")) return } defer file.Close() audio, err := io.ReadAll(io.LimitReader(file, 20<<20)) if err != nil { writeError(w, http.StatusBadRequest, err) return } contentType := header.Header.Get("Content-Type") if contentType == "" { contentType = "audio/wav" } result, err := s.speech.AssessPronunciation(r.Context(), services.PronunciationInput{ Audio: audio, ContentType: contentType, TargetText: exercise.TargetText, Locale: exercise.TargetLanguage, }) if err != nil { writeError(w, http.StatusBadGateway, err) return } teacher, err := s.teacher.FeedbackForAttempt(r.Context(), exercise.TargetText, result, weakWords(result.WordScores)) if err != nil { writeError(w, http.StatusBadGateway, err) return } attempt, err := s.store.SaveAttempt(r.Context(), domain.Attempt{ UserID: currentUserID(r), ExerciseID: exercise.ID, TargetLanguage: exercise.TargetLanguage, RecognizedText: result.RecognizedText, OverallScore: result.OverallScore, AccuracyScore: result.AccuracyScore, FluencyScore: result.FluencyScore, CompletenessScore: result.CompletenessScore, ProsodyScore: result.ProsodyScore, WordScores: result.WordScores, TeacherFeedback: teacher.TeacherFeedback, }) if err != nil { writeError(w, http.StatusInternalServerError, err) return } writeJSON(w, http.StatusCreated, map[string]any{"attempt": attempt, "teacher": teacher, "provider": result.Provider}) } func (s *Server) startConversation(w http.ResponseWriter, r *http.Request) { profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } session, err := s.store.CreateConversationSession(r.Context(), currentUserID(r), profile.TargetLanguage, profile.CEFRLevel) if err != nil { writeError(w, http.StatusInternalServerError, err) return } teacher, err := s.teacher.StartConversation(r.Context(), profile.TargetLanguage, profile.CEFRLevel) if err != nil { writeError(w, http.StatusBadGateway, err) return } lang, _ := s.store.GetLanguage(r.Context(), profile.TargetLanguage) audio, mime, _ := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, firstNonEmpty(teacher.TTSText, teacher.TargetText)) turn, _ := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: session.ID, Speaker: "teacher", Text: firstNonEmpty(teacher.TTSText, teacher.TargetText)}) writeJSON(w, http.StatusCreated, map[string]any{ "session": session, "turn": turn, "teacher": teacher, "audio": encodeAudio(audio, mime), }) } func (s *Server) conversationTurn(w http.ResponseWriter, r *http.Request) { var req struct { Text string `json:"text"` } if err := decodeJSON(r, &req); err != nil { writeError(w, http.StatusBadRequest, err) return } profile, err := s.store.GetPrimaryProfile(r.Context(), currentUserID(r)) if err != nil { writeError(w, http.StatusNotFound, err) return } sessionID := r.PathValue("id") userTurn, err := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: sessionID, Speaker: "learner", Text: req.Text}) if err != nil { writeError(w, http.StatusInternalServerError, err) return } teacher, err := s.teacher.ContinueConversation(r.Context(), profile.TargetLanguage, profile.CEFRLevel, req.Text) if err != nil { writeError(w, http.StatusBadGateway, err) return } lang, _ := s.store.GetLanguage(r.Context(), profile.TargetLanguage) audio, mime, _ := s.speech.Synthesize(r.Context(), lang.AzureLocale, lang.DefaultTTSVoice, firstNonEmpty(teacher.TTSText, teacher.TargetText)) teacherTurn, _ := s.store.SaveConversationTurn(r.Context(), domain.ConversationTurn{SessionID: sessionID, Speaker: "teacher", Text: firstNonEmpty(teacher.TTSText, teacher.TargetText)}) writeJSON(w, http.StatusOK, map[string]any{ "user_turn": userTurn, "teacher_turn": teacherTurn, "teacher": teacher, "audio": encodeAudio(audio, mime), }) } func weakWords(words []domain.WordScore) []domain.WordScore { out := make([]domain.WordScore, 0) for _, word := range words { if word.Accuracy < 75 { out = append(out, word) } } return out } func encodeAudio(audio []byte, mime string) map[string]string { if len(audio) == 0 { return nil } return map[string]string{ "mime_type": mime, "base64": base64.StdEncoding.EncodeToString(audio), } } func firstNonEmpty(values ...string) string { for _, value := range values { if strings.TrimSpace(value) != "" { return value } } return "" } func flowiseSessionID(userID, targetLanguage, scope string) string { parts := []string{strings.TrimSpace(userID), strings.TrimSpace(targetLanguage), strings.TrimSpace(scope)} for i, part := range parts { parts[i] = strings.ReplaceAll(part, " ", "_") } return strings.Join(parts, ":") } func valueOr(value, fallback string) string { if strings.TrimSpace(value) == "" { return fallback } return value }