Skip to main content

​
System Components

VibeLearn has 6 core components:
ComponentDescription
Hooks (src/hooks/)5 TypeScript hooks — compiled to ESM, built to plugin/scripts/
Worker Service (src/services/worker-service.ts)Express API on port 37778, Bun-managed, handles analysis asynchronously
Analysis Pipeline (src/services/analysis/)4-stage pipeline: StackDetector → StaticAnalyzer → ConceptExtractor → QuizGenerator
Upstream Sync (src/services/sync/)HMAC-signed POST to api.vibelearn.dev; OfflineQueue for retry
Database (src/services/sqlite/)SQLite3 at ~/.vibelearn/vibelearn.db
CLI (src/cli/vl/)vl quiz, vl status, vl gaps, vl login

​
Data Flow

Claude Code / Cursor Session
        │
        │  Hook events (SessionStart, PostToolUse, Stop...)
        ▼
┌───────────────────────┐
│   Hook Layer          │
│  - Strip <private>    │
│  - Fire-and-forget    │
│    HTTP to worker     │
└────────┬──────────────┘
         │ HTTP :37778
         ▼
┌───────────────────────┐
│   Worker Service      │
│   (Bun + Express)     │
│                       │
│  /api/sessions/init   │
│  /api/sessions/obs... │
│  /api/vibelearn/...   │
└────────┬──────────────┘
         │
         ▼
┌───────────────────────┐     ┌──────────────────────┐
│   Analysis Pipeline   │     │   SQLite Database     │
│                       │     │                       │
│  1. StackDetector     │────▶│  sdk_sessions         │
│  2. StaticAnalyzer    │     │  observations         │
│  3. ConceptExtractor  │     │  vl_concepts          │
│  4. QuizGenerator     │     │  vl_questions         │
└────────┬──────────────┘     │  vl_stack_profiles    │
         │                    │  vl_developer_profile │
         ▼                    │  vl_quiz_attempts     │
┌───────────────────────┐     │  vl_sync_queue        │
│   UpstreamSync        │     └──────────────────────┘
│   HMAC-signed POST    │
│   → api.vibelearn.dev │
│   OfflineQueue retry  │
└───────────────────────┘

​
Session Lifecycle

1. User starts coding
        ↓
2. SessionStart hook → worker health check → session init
        ↓
3. PostToolUse hooks → file edits + bash captured as observations
        ↓
4. Stop hook → 5-step analysis pipeline runs
        ↓
5. vl quiz → developer reviews quiz questions

​
Analysis Pipeline Detail

​
1. StackDetector

Reads project config files: package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, build.gradle. Detects:
  • Language + runtime
  • Framework (React, Next.js, FastAPI, Gin, etc.)
  • ORM/DB client (Prisma, SQLAlchemy, GORM, etc.)
  • Testing tools (Jest, pytest, Go test, etc.)
Stores result in vl_stack_profiles.

​
2. StaticAnalyzer

AST-parses files modified during the session using tree-sitter. Identifies:
  • Custom hooks (React use* pattern)
  • API route definitions
  • Database query patterns
  • Authentication middleware
  • Component/class structure

​
3. ConceptExtractor

Single LLM call combining:
  • Stack profile from step 1
  • File patterns from step 2
  • Last assistant message from the transcript
  • Session observations
Output: session narrative (vibelearn_session_summaries) + concept list (vl_concepts).

​
4. QuizGenerator

Second LLM call: one quiz question per extracted concept. Skips concepts where mastery_score > 0.85 in vl_developer_profile. Question types: multiple_choice, fill_in_blank, explain_code. Output stored in vl_questions.

​
Directory Structure

src/
├── hooks/                          # 5 lifecycle hooks
│   ├── session-start.ts
│   ├── user-prompt-submit.ts
│   ├── post-tool-use.ts
│   ├── summarize.ts                # Stop hook — triggers pipeline
│   └── session-end.ts
├── services/
│   ├── worker-service.ts           # Express app entry
│   ├── analysis/
│   │   ├── StackDetector.ts
│   │   ├── StaticAnalyzer.ts
│   │   ├── ConceptExtractor.ts
│   │   └── QuizGenerator.ts
│   ├── sync/
│   │   ├── UpstreamSync.ts
│   │   └── OfflineQueue.ts
│   ├── sqlite/
│   │   ├── DatabaseManager.ts
│   │   └── migrations.ts
│   └── worker/http/routes/
│       ├── VibeLearnRoutes.ts      # Analysis + sync endpoints
│       ├── SessionRoutes.ts
│       └── ...
├── cli/vl/
│   └── index.ts                    # vl CLI
└── utils/
    └── tag-stripping.ts            # <private> tag removal