# ajitirto/ms-learn architecture

> Architecture diagram of the GitHub repository ajitirto/ms-learn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ajitirto/ms-learn
- Repository: https://github.com/ajitirto/ms-learn

## Overview

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`](https://github.com/ajitirto/ms-learn/blob/main/docker-compose.yml) (Compose Stack), [`gateway/nginx/nginx.conf`](https://github.com/ajitirto/ms-learn/blob/main/gateway/nginx/nginx.conf) (Gateway), [`frontend`](https://github.com/ajitirto/ms-learn/tree/main/frontend) (Frontend), [`services/order-service`](https://github.com/ajitirto/ms-learn/tree/main/services/order-service) (Order Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>client"))
  node_frontend["Frontend<br/>nextjs app"]
  node_authctx["AuthCtx<br/>session state<br/>[AuthContext.tsx]"]
  node_api_client["API Client<br/>backend client<br/>[api.ts]"]
end

subgraph group_edge["Edge"]
  node_gateway["Gateway<br/>nginx edge<br/>[nginx.conf]"]
end

subgraph group_services["Services"]
  node_auth_service["Auth Service<br/>identity api"]
  node_product_service["Product Service<br/>catalog api"]
  node_cart_service["Cart Service<br/>cart store"]
  node_order_service["Order Service<br/>checkout orchestrator"]
  node_payment_service["Payment Service<br/>payment api"]
  node_auth_handler["Auth Handler<br/>http handlers<br/>[auth_handler.go]"]
  node_product_handlers["Catalog Handlers<br/>http handlers<br/>[product_handler.go]"]
  node_cart_handler["Cart Handler<br/>http handlers<br/>[cart_handler.go]"]
  node_order_handler["Order Handler<br/>http handlers<br/>[order_handler.go]"]
  node_payment_handler["Payment Handler<br/>http handlers<br/>[payment_handler.go]"]
  node_grpc_clients["gRPC Clients<br/>internal rpc"]
end

subgraph group_platform["Platform"]
  node_shared["Shared<br/>cross-cutting"]
  node_proto["Protos<br/>rpc contracts"]
  node_observability[("Observability<br/>otel stack")]
  node_compose["Compose Stack<br/>runtime topology<br/>[docker-compose.yml]"]
end

node_browser -->|"uses"| node_frontend
node_frontend -->|"calls"| node_gateway
node_gateway -->|"routes /auth"| node_auth_service
node_gateway -->|"routes /products"| node_product_service
node_gateway -->|"routes /cart"| node_cart_service
node_gateway -->|"routes /orders"| node_order_service
node_gateway -->|"routes /payments"| node_payment_service
node_frontend -->|"uses"| node_authctx
node_frontend -->|"uses"| node_api_client
node_auth_service -.->|"imports"| node_shared
node_product_service -.->|"imports"| node_shared
node_order_service -.->|"imports"| node_shared
node_payment_service -.->|"imports"| node_shared
node_order_service -->|"uses"| node_grpc_clients
node_grpc_clients -.->|"implements"| node_proto
node_compose -->|"starts"| node_observability
node_compose -->|"starts"| node_gateway
node_compose -->|"starts"| node_auth_service
node_compose -->|"starts"| node_product_service
node_compose -->|"starts"| node_cart_service
node_compose -->|"starts"| node_order_service
node_compose -->|"starts"| node_payment_service

click node_frontend "https://github.com/ajitirto/ms-learn/tree/main/frontend"
click node_authctx "https://github.com/ajitirto/ms-learn/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_api_client "https://github.com/ajitirto/ms-learn/blob/main/frontend/src/lib/api.ts"
click node_gateway "https://github.com/ajitirto/ms-learn/blob/main/gateway/nginx/nginx.conf"
click node_auth_service "https://github.com/ajitirto/ms-learn/tree/main/services/auth-service"
click node_product_service "https://github.com/ajitirto/ms-learn/tree/main/services/product-service"
click node_cart_service "https://github.com/ajitirto/ms-learn/tree/main/services/cart-service"
click node_order_service "https://github.com/ajitirto/ms-learn/tree/main/services/order-service"
click node_payment_service "https://github.com/ajitirto/ms-learn/tree/main/services/payment-service"
click node_auth_handler "https://github.com/ajitirto/ms-learn/blob/main/services/auth-service/internal/handler/auth_handler.go"
click node_product_handlers "https://github.com/ajitirto/ms-learn/blob/main/services/product-service/internal/handler/product_handler.go"
click node_cart_handler "https://github.com/ajitirto/ms-learn/blob/main/services/cart-service/internal/handler/cart_handler.go"
click node_order_handler "https://github.com/ajitirto/ms-learn/blob/main/services/order-service/internal/handler/order_handler.go"
click node_payment_handler "https://github.com/ajitirto/ms-learn/blob/main/services/payment-service/internal/handler/payment_handler.go"
click node_grpc_clients "https://github.com/ajitirto/ms-learn/tree/main/services/order-service/internal/grpcclient"
click node_shared "https://github.com/ajitirto/ms-learn/tree/main/services/shared"
click node_proto "https://github.com/ajitirto/ms-learn/tree/main/services/proto"
click node_observability "https://github.com/ajitirto/ms-learn/blob/main/docker/otel-collector-config.yaml"
click node_compose "https://github.com/ajitirto/ms-learn/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_frontend,node_authctx,node_api_client toneBlue
class node_gateway toneAmber
class node_auth_service,node_product_service,node_cart_service,node_order_service,node_payment_service,node_auth_handler,node_product_handlers,node_cart_handler,node_order_handler,node_payment_handler,node_grpc_clients toneMint
class node_shared,node_proto,node_observability,node_compose toneRose
```

## Components

### Client

Browser-facing web app

- **Browser**: client · End-user entrypoint that consumes the web app
- [Frontend](https://github.com/ajitirto/ms-learn/tree/main/frontend): nextjs app · Next.js web UI with route-based views and centralized session/API access · `frontend`
- [AuthCtx](https://github.com/ajitirto/ms-learn/blob/main/frontend/src/contexts/AuthContext.tsx): session state · Frontend auth/session context for user state · `frontend/src/contexts/AuthContext.tsx`
- [API Client](https://github.com/ajitirto/ms-learn/blob/main/frontend/src/lib/api.ts): backend client · Frontend API abstraction used by pages and features · `frontend/src/lib/api.ts`

### Edge

Network boundary and routing layer

- [Gateway](https://github.com/ajitirto/ms-learn/blob/main/gateway/nginx/nginx.conf): nginx edge · Single external API entrypoint and reverse proxy to internal services · `gateway/nginx/nginx.conf`

### Services

Go microservices

- [Auth Service](https://github.com/ajitirto/ms-learn/tree/main/services/auth-service): identity api · Registration, login, refresh, and profile boundary backed by Postgres and Redis · `services/auth-service`
- [Product Service](https://github.com/ajitirto/ms-learn/tree/main/services/product-service): catalog api · Product and category source of truth with Postgres and Redis · `services/product-service`
- [Cart Service](https://github.com/ajitirto/ms-learn/tree/main/services/cart-service): cart store · Redis-backed shopping cart state and checkout summary API · `services/cart-service`
- [Order Service](https://github.com/ajitirto/ms-learn/tree/main/services/order-service): checkout orchestrator · Order lifecycle and checkout coordination with internal RPC clients · `services/order-service`
- [Payment Service](https://github.com/ajitirto/ms-learn/tree/main/services/payment-service): payment api · Payment records, status, refunds, and webhook boundary · `services/payment-service`
- [Auth Handler](https://github.com/ajitirto/ms-learn/blob/main/services/auth-service/internal/handler/auth_handler.go): http handlers · HTTP endpoints for auth operations · `services/auth-service/internal/handler/auth_handler.go`
- [Catalog Handlers](https://github.com/ajitirto/ms-learn/blob/main/services/product-service/internal/handler/product_handler.go): http handlers · HTTP endpoints for products and categories · `services/product-service/internal/handler/product_handler.go`
- [Cart Handler](https://github.com/ajitirto/ms-learn/blob/main/services/cart-service/internal/handler/cart_handler.go): http handlers · HTTP endpoints for cart mutations and summary · `services/cart-service/internal/handler/cart_handler.go`
- [Order Handler](https://github.com/ajitirto/ms-learn/blob/main/services/order-service/internal/handler/order_handler.go): http handlers · HTTP endpoints for orders and checkout flows · `services/order-service/internal/handler/order_handler.go`
- [Payment Handler](https://github.com/ajitirto/ms-learn/blob/main/services/payment-service/internal/handler/payment_handler.go): http handlers · HTTP endpoints for payment lifecycle and webhooks · `services/payment-service/internal/handler/payment_handler.go`
- [gRPC Clients](https://github.com/ajitirto/ms-learn/tree/main/services/order-service/internal/grpcclient): internal rpc · Order service clients for product and payment RPCs · `services/order-service/internal/grpcclient`

### Platform

Shared code, observability, and local runtime

- [Shared](https://github.com/ajitirto/ms-learn/tree/main/services/shared): cross-cutting · JWT, middleware, response, and tracing helpers shared by services · `services/shared`
- [Protos](https://github.com/ajitirto/ms-learn/tree/main/services/proto): rpc contracts · gRPC service definitions for product and payment · `services/proto`
- [Observability](https://github.com/ajitirto/ms-learn/blob/main/docker/otel-collector-config.yaml): otel stack · OpenTelemetry collector and Jaeger tracing in the local stack · `docker/otel-collector-config.yaml`
- [Compose Stack](https://github.com/ajitirto/ms-learn/blob/main/docker-compose.yml): runtime topology · Containerized local deployment wiring services, databases, gateway, and tracing · `docker-compose.yml`

## Connections

- 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
