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
✎ Key Insights in 30 Seconds
Case study: 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.
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.
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
- 1Go Kratos v3 Framework: standardizes HTTP/gRPC dual-transport, configuration parsing, middleware, and dependency injection across all services.
- 2Decoupled Learning Progress: `learn-service` records lesson completion and immediately emits `learn.lesson.completed` over NATS, delegating XP and streak updates to `core-service`.
- 3Cloudflare R2 Audio Distribution: high-quality Vietnamese pronunciation audio stored in R2 with edge CDN caching, saving server bandwidth.
- 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:
- Authentication & OAuth ->
auth-service - Story & Scene Navigation ->
learn-service - Audio Pronunciation Streaming ->
media-service(backed by Cloudflare R2) - XP Streaks & Daily Rewards ->
core-service(via NATS events) - 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.
✎ tip
Audio files are cached globally on Cloudflare Edge with Cache-Control headers, eliminating egress bandwidth costs.
Code & Configuration
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.
