How ajitirto/ms-learn works
1. This repository is a microservice e-commerce platform with three clear tiers: a Next.js web frontend, an nginx gateway, and five Go services behind it. The boundary is important: browsers talk to the frontend, the frontend talks to the gateway, and the gateway routes API calls to individual services.
2. The frontend lives in frontend/ and is a Next.js 14 app using TypeScript and Tailwind. Its routes are split by domain: login/register, product catalog and product detail, cart, checkout, order list/detail, and admin views for products and orders. AuthContext and lib/api.ts suggest the frontend centralizes session state and backend API access rather than calling services directly from each page.
3. The gateway lives in gateway/ and is nginx-based. It acts as the single external API entrypoint on port 80, proxying /api/v1/... traffic to the Go services and also serving the frontend entrypoint in the local stack. This makes the gateway the main network boundary between the browser-facing world and internal service ports.
4. Each Go service follows the same internal structure: cmd/ for startup, internal/config for environment-driven setup, internal/handler for HTTP handlers, and internal/repository or internal/store for persistence. That layout indicates a classic layered service design with minimal shared runtime coupling.
5. auth-service owns registration, login, refresh tokens, and profile management. It uses PostgreSQL for user data and Redis for session/token-related state, and it depends on shared JWT and middleware code from services/shared. In the architecture diagram, this service is the identity boundary for authenticated API access.
6. product-service owns catalog data and categories. It has separate handlers and repositories for products and categories, and the readme shows it uses PostgreSQL plus Redis, which implies a mix of durable catalog storage and cache-backed reads. This service is the source of truth for product metadata used elsewhere in the system.
7. cart-service is Redis-based and intentionally lightweight. It stores shopping cart state in Redis rather than in a relational database, which makes it a volatile, session-like subsystem tied closely to the authenticated user. Its API is narrow: add/update/remove items, clear cart, and produce checkout summary.
8. order-service is the orchestration point for checkout and order lifecycle. It has its own PostgreSQL database for order records and also contains grpcclient code for product and payment, which indicates it coordinates with those services internally rather than only via REST. This is the clearest example of inter-service dependency in the repo.
9. payment-service owns payment records and payment lifecycle, with its own PostgreSQL database. The API includes payment creation, status lookup, refunds, methods, and webhook handling, so it is the external payment boundary of the platform. The webhook endpoint suggests it receives asynchronous events from a payment provider or simulator.
10. Data ownership is strictly separated by service: auth has its own Postgres instance and Redis session store, products has its own Postgres and cache, cart uses Redis only, orders has its own Postgres, and payments has its own Postgres. This per-service storage model is a major architectural constraint and should be shown explicitly in any diagram.
11. The services/shared/ module holds cross-cutting concerns: standard response formatting, middleware, JWT helpers, and tracing helpers. This shared code reduces duplication but does not collapse service boundaries, since each service still has its own main, config, handlers, and repositories.
12. Observability is first-class in the local stack. Docker Compose brings up an OpenTelemetry collector and Jaeger UI, and the shared tracing package indicates services emit traces through OTel. This means request flow visibility is a platform-level concern, not an afterthought inside a single service.
13. The local runtime is fully containerized. docker-compose.yml, service-specific Dockerfiles, database init SQL scripts, and the nginx config define the deployment topology for development. The docker/init-scripts/*/init.sql files show that each database is initialized independently, matching the service-owned data model.
14. There are also services/proto/ definitions for product and payment, which align with the order service’s gRPC client directory. That suggests the system is already shaped for internal RPC between services even though the external API remains REST over HTTP.
15. The .openspec, .opencode, and .sisyphus folders are process/documentation artifacts rather than runtime components. They describe proposed or archived changes and operational notes, so they matter for development workflow but not for the production request path.
Main entry points: docker-compose.yml Compose Stack · nginx.conf Gateway · frontend Frontend · order-service Order Service
Components 20
Client
Browser-facing web app
- Browser · End-user entrypoint that consumes the web app
- Frontend · Next.js web UI with route-based views and centralized session/API access
frontend - AuthCtx · Frontend auth/session context for user state
frontend/src/contexts/AuthContext.tsx - API Client · Frontend API abstraction used by pages and features
frontend/src/lib/api.ts
Edge
Network boundary and routing layer
- Gateway · Single external API entrypoint and reverse proxy to internal services
gateway/nginx/nginx.conf
Services
Go microservices
- Auth Service · Registration, login, refresh, and profile boundary backed by Postgres and Redis
services/auth-service - Product Service · Product and category source of truth with Postgres and Redis
services/product-service - Cart Service · Redis-backed shopping cart state and checkout summary API
services/cart-service - Order Service · Order lifecycle and checkout coordination with internal RPC clients
services/order-service - Payment Service · Payment records, status, refunds, and webhook boundary
services/payment-service - Auth Handler · HTTP endpoints for auth operations
services/auth-service/internal/handler/auth_handler.go - Catalog Handlers · HTTP endpoints for products and categories
services/product-service/internal/handler/product_handler.go - Cart Handler · HTTP endpoints for cart mutations and summary
services/cart-service/internal/handler/cart_handler.go - Order Handler · HTTP endpoints for orders and checkout flows
services/order-service/internal/handler/order_handler.go - Payment Handler · HTTP endpoints for payment lifecycle and webhooks
services/payment-service/internal/handler/payment_handler.go - gRPC Clients · Order service clients for product and payment RPCs
services/order-service/internal/grpcclient
Platform
Shared code, observability, and local runtime
- Shared · JWT, middleware, response, and tracing helpers shared by services
services/shared - Protos · gRPC service definitions for product and payment
services/proto - Observability · OpenTelemetry collector and Jaeger tracing in the local stack
docker/otel-collector-config.yaml - Compose Stack · Containerized local deployment wiring services, databases, gateway, and tracing
docker-compose.yml
Connections 22
- Browser → Frontend: uses · Users interact with the web app
- Frontend → Gateway: calls · Frontend sends API traffic through the edge gateway
- Gateway → Auth Service: routes /auth · Gateway proxies auth API requests
- Gateway → Product Service: routes /products · Gateway proxies catalog API requests
- Gateway → Cart Service: routes /cart · Gateway proxies cart API requests
- Gateway → Order Service: routes /orders · Gateway proxies order API requests
- Gateway → Payment Service: routes /payments · Gateway proxies payment API requests
- Frontend → AuthCtx: uses · Frontend centralizes auth/session state
- Frontend → API Client: uses · Frontend pages use a shared backend client
- Auth Service → Shared: imports · Services reuse shared middleware, JWT, and response helpers
- Product Service → Shared: imports · Services reuse shared middleware, JWT, and response helpers
- Order Service → Shared: imports · Services reuse shared middleware, JWT, and response helpers
- Payment Service → Shared: imports · Services reuse shared middleware, JWT, and response helpers
- Order Service → gRPC Clients: uses · Order service coordinates product and payment over gRPC
- gRPC Clients → Protos: implements · RPC clients are shaped by shared protobuf contracts
- Compose Stack → Observability: starts · Local stack includes tracing collector and Jaeger
- Compose Stack → Gateway: starts · Compose wires the edge gateway into the runtime
- Compose Stack → Auth Service: starts · Compose runs the auth microservice
- Compose Stack → Product Service: starts · Compose runs the product microservice
- Compose Stack → Cart Service: starts · Compose runs the cart microservice
- Compose Stack → Order Service: starts · Compose runs the order microservice
- Compose Stack → Payment Service: starts · Compose runs the payment microservice