Merge pull request #21 from willwearing/add-autoresearch-self-improvement-loop

Add autoresearch self-improvement loop to docs

Author: willwearing

.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+.turbo
+*.env
+*.env.local
+.DS_Store
+coverage
+playwright-report
+tasks
+docs
+.git

.github/workflows/ci-deploy.yml

@@ -0,0 +1,83 @@
+name: CI & Deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ─── Tests ───────────────────────────────────────────
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.6"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build shared package
+        run: cd packages/shared && bun run build
+
+      - name: Generate Prisma client
+        run: cd backend && bun x prisma generate
+
+      - name: Run backend tests
+        run: cd backend && bun run test
+
+      - name: Run frontend tests
+        run: cd apps/web && bun run test
+
+  # ─── Deploy backend to Railway (only on main) ───────
+  deploy-backend:
+    name: Deploy Backend (Railway)
+    needs: test
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Railway CLI
+        run: npm install -g @railway/cli
+
+      - name: Deploy to Railway
+        run: railway up --service ${{ vars.RAILWAY_SERVICE_NAME }}
+        env:
+          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+
+  # ─── Deploy frontend to Vercel (only on main) ───────
+  deploy-frontend:
+    name: Deploy Frontend (Vercel)
+    needs: test
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.6"
+
+      - name: Install Vercel CLI
+        run: npm install -g vercel
+
+      - name: Pull Vercel env
+        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+        working-directory: apps/web
+
+      - name: Build
+        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+        working-directory: apps/web
+
+      - name: Deploy
+        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
+        working-directory: apps/web

apps/web/.posthog-events.json

@@ -0,0 +1,128 @@
+[
+  {
+    "event": "sign_up",
+    "description": "User created a new account",
+    "file": "src/components/auth/auth-form.tsx",
+    "properties": ["method"]
+  },
+  {
+    "event": "sign_in",
+    "description": "User signed in successfully",
+    "file": "src/components/auth/auth-form.tsx",
+    "properties": ["method"]
+  },
+  {
+    "event": "course_enrolled",
+    "description": "User enrolled in a course",
+    "file": "various",
+    "properties": ["course_id", "course_name"]
+  },
+  {
+    "event": "subscription_started",
+    "description": "User started a paid subscription",
+    "file": "various",
+    "properties": ["plan", "billing_period"]
+  },
+  {
+    "event": "diagnostic_started",
+    "description": "User began a diagnostic assessment",
+    "file": "src/components/app/diagnostic-flow.tsx",
+    "properties": ["course_id", "total_estimated"]
+  },
+  {
+    "event": "diagnostic_question_answered",
+    "description": "User answered a diagnostic question (or skipped with 'I don't know')",
+    "file": "src/components/app/diagnostic-flow.tsx",
+    "properties": ["course_id", "question_number", "was_correct", "was_skipped", "response_time_ms"]
+  },
+  {
+    "event": "diagnostic_completed",
+    "description": "Diagnostic assessment finished with results",
+    "file": "src/components/app/diagnostic-flow.tsx",
+    "properties": ["course_id", "concepts_known", "total_concepts"]
+  },
+  {
+    "event": "lesson_started",
+    "description": "User started a lesson for a concept",
+    "file": "src/components/app/lesson-flow.tsx",
+    "properties": ["course_id", "concept_id", "concept_name", "total_knowledge_points"]
+  },
+  {
+    "event": "lesson_practice_answered",
+    "description": "User answered a practice problem within a lesson",
+    "file": "src/components/app/lesson-flow.tsx",
+    "properties": ["concept_id", "problem_id", "was_correct", "response_time_ms"]
+  },
+  {
+    "event": "lesson_audio_played",
+    "description": "User played audio for a lesson knowledge point",
+    "file": "src/components/app/lesson-flow.tsx",
+    "properties": ["concept_id", "kp_slug"]
+  },
+  {
+    "event": "lesson_completed",
+    "description": "User completed all knowledge points in a lesson",
+    "file": "src/components/app/lesson-flow.tsx",
+    "properties": ["concept_id", "concept_name", "duration_seconds"]
+  },
+  {
+    "event": "quiz_started",
+    "description": "User started a timed quiz",
+    "file": "src/components/app/quiz-flow.tsx",
+    "properties": ["quiz_id", "total_problems", "time_limit_ms"]
+  },
+  {
+    "event": "quiz_question_answered",
+    "description": "User answered a quiz question",
+    "file": "src/components/app/quiz-flow.tsx",
+    "properties": ["quiz_id", "question_index", "response_time_ms"]
+  },
+  {
+    "event": "quiz_completed",
+    "description": "Quiz finished with pass/fail result",
+    "file": "src/components/app/quiz-flow.tsx",
+    "properties": ["concept_id", "passed", "score"]
+  },
+  {
+    "event": "review_started",
+    "description": "User started a spaced repetition review session",
+    "file": "src/components/app/review-flow.tsx",
+    "properties": ["concept_id", "total_problems"]
+  },
+  {
+    "event": "review_problem_answered",
+    "description": "User answered a review problem",
+    "file": "src/components/app/review-flow.tsx",
+    "properties": ["concept_id", "problem_id", "was_correct", "response_time_ms"]
+  },
+  {
+    "event": "review_completed",
+    "description": "Review session finished with pass/fail result",
+    "file": "src/components/app/review-flow.tsx",
+    "properties": ["concept_id", "passed", "score"]
+  },
+  {
+    "event": "section_exam_started",
+    "description": "User started a timed section exam",
+    "file": "src/components/app/section-exam-flow.tsx",
+    "properties": ["section_id", "total_problems", "time_limit_ms"]
+  },
+  {
+    "event": "section_exam_question_answered",
+    "description": "User answered a section exam question",
+    "file": "src/components/app/section-exam-flow.tsx",
+    "properties": ["section_id", "question_index", "response_time_ms"]
+  },
+  {
+    "event": "section_exam_completed",
+    "description": "Section exam finished with pass/fail and score",
+    "file": "src/components/app/section-exam-flow.tsx",
+    "properties": ["section_id", "passed", "score"]
+  },
+  {
+    "event": "study_task_dispatched",
+    "description": "Study router redirected user to their next task",
+    "file": "src/components/app/study-router.tsx",
+    "properties": ["course_id", "task_type"]
+  }
+]

apps/web/src/components/app/diagnostic-flow.tsx

@@ -8,7 +8,7 @@ import { ProblemRenderer, type ProblemFeedback } from "@/components/app/problems
 import { Button } from "@/components/ui/button";
 import { Progress } from "@/components/ui/progress";
 import type { Problem, ProblemAnswer } from "@/lib/types";
-import { trackDiagnosticComplete } from "@/lib/posthog/events";
+import { trackDiagnosticComplete, trackDiagnosticStarted, trackDiagnosticQuestionAnswered } from "@/lib/posthog/events";
 
 interface DiagnosticState {
   sessionId: string;
@@ -66,6 +66,12 @@ export function DiagnosticFlow({ orgSlug, courseId, academyId, token, initialDat
     );
   }, [diagnosticBasePath, token]);
 
+  // Track diagnostic start
+  useEffect(() => {
+    trackDiagnosticStarted(courseId, initialData.totalEstimated);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // If initially complete, fetch result
   useEffect(() => {
     if (state.isComplete && !result && !fetchingRef.current) {
@@ -96,6 +102,13 @@ export function DiagnosticFlow({ orgSlug, courseId, academyId, token, initialDat
       );
 
       const skipped = answer === "__I_DONT_KNOW__";
+      trackDiagnosticQuestionAnswered(
+        courseId,
+        state.questionNumber,
+        response.wasCorrect,
+        skipped,
+        Date.now() - startTimeRef.current,
+      );
       setFeedback({ wasCorrect: response.wasCorrect, skipped });
 
       // After brief delay, show next question or complete

apps/web/src/components/app/lesson-flow.tsx

@@ -9,7 +9,7 @@ import { Progress } from "@/components/ui/progress";
 import { BookOpen, CheckCircle2, ClipboardList, Play, Pause, Volume2 } from "lucide-react";
 import { useAudioPlayer } from "@/lib/hooks/use-audio-player";
 import { useLessonAudio } from "@/lib/hooks/use-lesson-audio";
-import { trackLessonComplete } from "@/lib/posthog/events";
+import { trackLessonComplete, trackLessonStarted, trackLessonPracticeAnswered, trackLessonAudioPlayed } from "@/lib/posthog/events";
 import { LessonRichContent } from "@/components/app/lesson-rich-content";
 import type { Problem, ProblemAnswer, RichContentBlock } from "@/lib/types";
 
@@ -68,6 +68,8 @@ export function LessonFlow({ orgSlug, courseId, token, lesson }: LessonFlowProps
     const startedAt = Date.now();
     lessonStartRef.current = startedAt;
     practiceStartRef.current = startedAt;
+    trackLessonStarted(courseId, lesson.conceptId, lesson.conceptName, lesson.knowledgePoints.length);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   function resetPractice() {
@@ -149,6 +151,12 @@ export function LessonFlow({ orgSlug, courseId, token, lesson }: LessonFlowProps
         }
       );
 
+      trackLessonPracticeAnswered(
+        lesson.conceptId,
+        currentProblem.id,
+        response.correct,
+        Date.now() - practiceStartRef.current,
+      );
       setPracticeFeedback({
         wasCorrect: response.correct,
         explanation: response.feedback,
@@ -207,16 +215,17 @@ export function LessonFlow({ orgSlug, courseId, token, lesson }: LessonFlowProps
 
             return (
               <button
-                onClick={() =>
+                onClick={() => {
+                  trackLessonAudioPlayed(lesson.conceptId, kp.slug);
                   loadQueue([
                     {
                       id: kp.id,
                       title: `${lesson.conceptName} - ${kp.slug}`,
                       audioUrl: kpAudio.instructionUrl!,
                       durationSeconds: kpAudio.instructionDuration,
                     },
-                  ])
-                }
+                  ]);
+                }}
                 className="flex items-center gap-2 rounded-lg bg-primary/10 p-3 text-sm text-primary hover:bg-primary/20 transition-colors w-full"
               >
                 {isCurrentlyPlaying ? (

apps/web/src/components/app/quiz-flow.tsx

@@ -9,7 +9,7 @@ import { Progress } from "@/components/ui/progress";
 import type { Problem, ProblemAnswer } from "@/lib/types";
 import Link from "next/link";
 import { Clock } from "lucide-react";
-import { trackQuizComplete } from "@/lib/posthog/events";
+import { trackQuizComplete, trackQuizStarted, trackQuizQuestionAnswered } from "@/lib/posthog/events";
 
 interface QuizData {
   quizId: string;
@@ -50,6 +50,12 @@ export function QuizFlow({ orgSlug, courseId, token, quizData }: QuizFlowProps)
 
   const basePath = `/orgs/${orgSlug}/courses/${courseId}`;
 
+  // Track quiz start
+  useEffect(() => {
+    trackQuizStarted(quizData.quizId, quizData.totalProblems, quizData.timeLimitMs);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // Timer
   useEffect(() => {
     if (result) return;
@@ -94,6 +100,11 @@ export function QuizFlow({ orgSlug, courseId, token, quizData }: QuizFlowProps)
         }
       );
 
+      trackQuizQuestionAnswered(
+        quizData.quizId,
+        currentIndex,
+        Date.now() - questionStartRef.current,
+      );
       setAnsweredCount(response.answeredCount);
 
       // Move to next or stay on last

apps/web/src/components/app/review-flow.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useRef } from "react";
+import { useState, useRef, useEffect } from "react";
 import { useRouter } from "next/navigation";
 import { apiClientFetch } from "@/lib/api-client";
 import { ProblemRenderer, type ProblemFeedback } from "@/components/app/problems/problem-renderer";
@@ -9,6 +9,7 @@ import { Progress } from "@/components/ui/progress";
 import type { Problem, ProblemAnswer } from "@/lib/types";
 import Link from "next/link";
 import { CheckCircle, XCircle } from "lucide-react";
+import { trackReviewStarted, trackReviewProblemAnswered, trackReviewCompleted } from "@/lib/posthog/events";
 
 interface ReviewData {
   sessionId: string;
@@ -49,6 +50,12 @@ export function ReviewFlow({ orgSlug, courseId, conceptId, token, initialData }:
 
   const basePath = `/orgs/${orgSlug}/courses/${courseId}`;
 
+  // Track review start on mount
+  useEffect(() => {
+    trackReviewStarted(conceptId, initialData.totalProblems);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   async function handleSubmit(answer: ProblemAnswer) {
     if (submitting) return;
     setSubmitting(true);
@@ -69,6 +76,12 @@ export function ReviewFlow({ orgSlug, courseId, conceptId, token, initialData }:
       );
 
       const wasCorrect = response.correct;
+      trackReviewProblemAnswered(
+        conceptId,
+        problem.id,
+        wasCorrect,
+        Date.now() - startTimeRef.current,
+      );
       if (wasCorrect) setCorrectCount((prev) => prev + 1);
       setFeedback({ wasCorrect, explanation: response.feedback });
 
@@ -91,6 +104,7 @@ export function ReviewFlow({ orgSlug, courseId, conceptId, token, initialData }:
                 body: JSON.stringify({ sessionId }),
               }
             );
+            trackReviewCompleted(conceptId, completeResult.passed, completeResult.score);
             setResult(completeResult);
           } catch {
             // Still show what we have