✎ Key Insights in 30 Seconds
Architecture note: Domain modeling for interactive language learning: City -> Story -> Scene -> Content -> Activity hierarchy, separating static pedagogical curriculum from dynamic learner progress and XP streaks.
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.
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
- 1Immutable Content Nodes: learning content is versioned and immutable, allowing aggressive caching in browser IndexedDB and edge CDNs.
- 2Decoupled Learner Attempt Log: user attempts are recorded as append-only events, preserving full learning history for analytics.
- 3Asynchronous Gamification: XP points and streak milestones are computed asynchronously in the background via NATS subscribers.
- 4Polymorphic Activity Schema: flexible activity types (multiple-choice, fill-in-blank, pronunciation listening) validated via strongly-typed JSONB schemas in PostgreSQL.
Code & Configuration
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.