chapter 2 · Building Puchi
  1. 1
  2. 2
  3. 3
  4. 4
page 4 of 4 · read 0%

Jan 2026 · 9 min read · Puchidemy · Architecture note

Designing a Story-Based Language Learning Engine

Domain modeling for interactive language learning: City -> Story -> Scene -> Content -> Activity hierarchy, separating static pedagogical curriculum from dynamic learner progress and XP streaks.

✎ puchidemy/puchi-backend · #Puchidemy #Domain-Driven Design #Next.js #Go #PostgreSQL #Product Engineering

Problem Context

Tightly coupling static lesson content (stories, dialogues, vocabulary, audio assets) with mutable learner state (scores, attempts, streaks, XP) causes severe database contention, schema bloat, and makes content authoring slow and fragile.

Puchi Story-Based Learning Domain Hierarchy
CityHanoi / HCMCStoryTopic & GoalSceneContext/DialogActivityQuiz/PronounceUser AttemptEvaluation & ScoreAsynchronous Mastery & Gamification Engine (NATS Event Bus)Event `learn.lesson.completed` ──► Core Service Updates XP, Daily Streaks, Leaderboard without HTTP blocking

Designing a Story-Based Language Learning Engine

Architecture & Design

Puchi models the learning engine into two strictly decoupled layers: (1) Static Content Hierarchy (City -> Story -> Scene -> Content -> Activity) stored with optimistic caching and CDN distribution, and (2) Dynamic Learner State (UserAttempt -> MasteryRecord -> StreakCounter) updated via asynchronous NATS event streams. Learners can retry activities infinitely without locking curriculum tables.

Key Technical Decisions

  1. 1Immutable Content Nodes: learning content is versioned and immutable, allowing aggressive caching in browser IndexedDB and edge CDNs.
  2. 2Decoupled Learner Attempt Log: user attempts are recorded as append-only events, preserving full learning history for analytics.
  3. 3Asynchronous Gamification: XP points and streak milestones are computed asynchronously in the background via NATS subscribers.
  4. 4Polymorphic Activity Schema: flexible activity types (multiple-choice, fill-in-blank, pronunciation listening) validated via strongly-typed JSONB schemas in PostgreSQL.

Code & Configuration

Puchi Content Hierarchy & Attempt Types · typescript
export interface SceneContent {
  id: string;
  storyId: string;
  order: number;
  dialogues: Array<{
    speaker: string;
    vietnamese: string;
    english: string;
    audioUrl: string;
  }>;
  activities: Array<{
    id: string;
    type: "MULTIPLE_CHOICE" | "FILL_BLANK" | "LISTEN_SELECT";
    question: string;
    options: string[];
    correctAnswer: string;
  }>;
}

Verified repository evidence

  • product · direct

    Modeled a story-driven language learning domain separating static pedagogical content hierarchies from dynamic learner progress and streak tracking.

    ↳ Hierarchical content model (Story -> Scene -> Content -> Activity) decoupled from user attempt evaluations and asynchronous XP/streak calculations via NATS.

    puchidemy/puchi-backend ↗

Key Engineering Takeaways

  • Separating content architecture from learner state enables instant offline PWA caching without synchronization conflicts.
  • Append-only attempt logs unlock rich analytics on learner difficulty curves.
  • Domain-driven design creates clean boundaries that scale gracefully as curriculum expands.