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

Jan 2026 · 10 min read · Puchidemy · Case study

Building Puchi: From Product Idea to Service Architecture

Deriving backend service boundaries from product domain needs: Next.js PWA, Go Kratos v3 monorepo (auth, core, learn, media, notification), NATS event bus, and Cloudflare R2 audio streaming.

✎ puchidemy/puchi-backend · #Puchidemy #Go #Kratos v3 #Next.js #PWA #Microservices #Product Engineering

Building Puchi: From Product Idea to Service Architecture
figure 1 — Puchidemy System Design: Learner PWA ──► Envoy Gateway ──► 5 Go Kratos Services ──► PostgreSQL / NATS / Cloudflare R2

At a glance

5 Services

Go Kratos Monorepo

Protobuf contracts & gRPC/HTTP

PWA

Mobile First Content

Edge CDN & IndexedDB cache

NATS Bus

Async XP & Streaks

Non-blocking quiz feedback

GitOps

ArgoCD on K3s

Automated declarative releases

Problem Context

Designing an online language learning platform requires balancing rapid client-side lesson interactivity (audio playback, quiz validations, offline PWA access) with reliable backend services for user auth, learning progress tracking, XP streaks, and media storage without over-engineering.

Naive approach vs. engineered

✕ Monolithic Language App with Direct Media Delivery

  • Serving high-frequency audio pronunciation files consumes server CPU and saturates network bandwidth.
  • Synchronous user gamification (XP, streaks, leaderboard) adds 200ms+ latency to quiz submissions.
  • Monolithic schema intertwines static language grammar rules with mutable learner test attempts.

✓ Puchi Cloud-Native EdTech Architecture

  • Cloudflare R2 edge audio streaming keeps media delivery separate from backend request handling.
  • NATS event stream processes gamification in background, returning quiz results without blocking the request.
  • Domain separation: immutable curriculum tree decoupled from append-only learner progress logs.
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

Building Puchi: From Product Idea to Service Architecture

Architecture & Design

Puchi derives its 5 Go microservices directly from user domain boundaries: `auth` (opaque sessions & OAuth), `core` (gamification, XP, streaks, user profiles), `learn` (pedagogical curriculum, lessons, quizzes), `media` (Cloudflare R2 audio asset uploads & streaming), and `notification` (email/push dispatches). Services are organized in a clean Go Kratos v3 monorepo sharing protobuf contracts and communicating asynchronously via NATS.

Key Technical Decisions

  1. 1Go Kratos v3 Framework: standardizes HTTP/gRPC dual-transport, configuration parsing, middleware, and dependency injection across all services.
  2. 2Decoupled Learning Progress: `learn-service` records lesson completion and immediately emits `learn.lesson.completed` over NATS, delegating XP and streak updates to `core-service`.
  3. 3Cloudflare R2 Audio Distribution: high-quality Vietnamese pronunciation audio stored in R2 with edge CDN caching, saving server bandwidth.
  4. 4Protobuf-First Contracts: API schemas defined in `.proto` files automatically generate TypeScript clients for Next.js and Go structs for services.

From Learner Journey to Microservice Boundaries

When designing Puchi, we modeled services strictly after learner interactions:

  1. Authentication & OAuth -> auth-service
  2. Story & Scene Navigation -> learn-service
  3. Audio Pronunciation Streaming -> media-service (backed by Cloudflare R2)
  4. XP Streaks & Daily Rewards -> core-service (via NATS events)
  5. Email Reminders & Notifications -> notification-service.

This functional separation ensures that an influx of learners listening to audio lessons never impacts the latency of authentication or progress evaluation.

Code & Configuration

Puchi Learn Service Event Dispatcher · go
func (s *LearnService) SubmitQuizAttempt(ctx context.Context, req *pb.SubmitAttemptRequest) (*pb.SubmitAttemptReply, error) {
    result, err := s.evaluator.Grade(ctx, req.QuizId, req.Answers)
    if err != nil {
        return nil, err
    }

    // Emit async domain event for Core Service (XP/Streak calculation)
    event := &events.LessonCompletedEvent{
        UserID:     req.UserId,
        LessonID:   req.LessonId,
        Score:      result.Score,
        Passed:     result.Passed,
        Timestamp:  time.Now().Unix(),
    }
    _ = s.eventBus.Publish("learn.lesson.completed", event)

    return &pb.SubmitAttemptReply{Passed: result.Passed, Score: result.Score}, nil
}

Verified repository evidence

  • backend · direct

    Structured 5 domain microservices in a Go monorepo using the Kratos v3 framework with unified protobuf schemas.

    ↳ Monorepo services sharing protobuf contracts, clean dependency injection, gRPC/HTTP endpoints, and decoupled business logic.

    puchidemy/puchi-backend ↗
  • 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

  • Product domain boundaries should dictate service boundaries, not arbitrary technical slicing.
  • Asynchronous NATS messaging keeps the learner's quiz completion response instantaneous.
  • Kratos v3 monorepo provides microservice modularity without the pain of managing multiple Git repositories.