# afloresc/e-commerce-api architecture

> Architecture diagram of the GitHub repository afloresc/e-commerce-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afloresc/e-commerce-api
- Repository: https://github.com/afloresc/e-commerce-api

## Overview

#### Purpose and Entry Point
This is a Go e-commerce HTTP API for authentication, product browsing/management, cart operations, and checkout/payment integration. The process starts at `cmd/main.go`, which is expected to assemble domain routers and middleware into the API server.

#### API Composition
Each major business domain follows a handler/router/service split:
- HTTP route registration and request handling: `internal/auth/router.go`, `internal/cart/router.go`, `internal/product/router.go`
- Business operations: `internal/auth/service.go`, `internal/cart/service.go`, `internal/payment/service.go`
- HTTP response/request boundary: `internal/auth/handler.go`, `internal/payment/handler.go`

This structure keeps transport concerns in handlers, orchestration in services, and domain persistence/model concerns localized.

#### Authentication and Authorization
Authentication is implemented as a dedicated module with JWT support:
- `internal/auth/handler.go`
- `internal/auth/service.go`
- `internal/auth/jwt.go`

JWT validation is also exposed as shared middleware in `middleware/jwt.go`. Protected cart, checkout, and administrative product-management routes should pass through this boundary, allowing services to operate on authenticated user context rather than raw credentials.

#### Product Catalog and Inventory Boundary
The product module owns catalog-oriented data and persistence access:
- `internal/product/model.go`
- `internal/product/repository.go`
- `internal/product/service.go`

The repository is the principal persistence boundary for products; handlers should call the service rather than access storage directly. Product routes in `internal/product/router.go` support the catalog flow, including viewing/searching products and likely privileged CRUD/inventory operations.

#### Cart Lifecycle
The cart module represents user shopping state and cart mutation workflows:
- `internal/cart/model.go`
- `internal/cart/service.go`
- `internal/cart/handler.go`

Requests enter through cart routes, are authenticated via JWT middleware, then invoke cart services to add or remove products. The cart service is the appropriate boundary for validating product availability, associating cart state with the current user, and calculating checkout-ready cart contents.

#### Checkout and Payment Integration
Payment is isolated from cart and product HTTP concerns:
- `internal/payment/router.go`
- `internal/payment/handler.go`
- `internal/payment/service.go`

The expected control flow is authenticated user → cart retrieval/validation → payment service → external payment gateway (such as Stripe, per the repository description). The payment service should contain gateway-specific interactions and translate external success/failure into application-level checkout outcomes.

#### Runtime and External Dependencies
The runtime is a Go API application, defined by `go.mod` and launched from `cmd/main.go`. JWT is the material security mechanism. A third-party payment gateway is the primary external-service boundary, mediated through `internal/payment/service.go`. Persistence technology is not identifiable from the provided tree; product storage is abstracted behind `internal/product/repository.go`.

Main entry points: [`cmd/main.go`](https://github.com/afloresc/e-commerce-api/blob/main/cmd/main.go) (API Server), [`internal/cart/service.go`](https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/service.go) (Cart Service), [`middleware/jwt.go`](https://github.com/afloresc/e-commerce-api/blob/main/middleware/jwt.go) (JWT Middleware), [`internal/payment/service.go`](https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/service.go) (Payment Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Authentication"]
  node_auth_router["Auth Router<br/>HTTP routes<br/>[router.go]"]
  node_auth_handler["Auth Handler<br/>HTTP handler<br/>[handler.go]"]
  node_auth_service["Auth Service<br/>domain service<br/>[service.go]"]
  node_jwt["JWT Support<br/>token service<br/>[jwt.go]"]
  node_jwt_middleware["JWT Middleware<br/>shared middleware<br/>[jwt.go]"]
end

subgraph group_catalog["Product Catalog"]
  node_product_router["Product Router<br/>HTTP routes<br/>[router.go]"]
  node_product_service["Product Service<br/>domain service<br/>[service.go]"]
  node_product_repository[("Product Repository<br/>persistence boundary<br/>[repository.go]")]
  node_product_model["Product Model<br/>domain model<br/>[model.go]"]
end

subgraph group_cart["Cart"]
  node_cart_router["Cart Router<br/>HTTP routes<br/>[router.go]"]
  node_cart_handler["Cart Handler<br/>HTTP handler<br/>[handler.go]"]
  node_cart_service["Cart Service<br/>domain service<br/>[service.go]"]
  node_cart_model["Cart Model<br/>domain model<br/>[model.go]"]
end

subgraph group_payment["Checkout &amp; Payment"]
  node_payment_router["Payment Router<br/>HTTP routes<br/>[router.go]"]
  node_payment_handler["Payment Handler<br/>HTTP handler<br/>[handler.go]"]
  node_payment_service["Payment Service<br/>checkout service<br/>[service.go]"]
  node_payment_gateway{{"Payment Gateway<br/>external service"}}
end

node_main["API Server<br/>Go entry point<br/>[main.go]"]

node_main -->|"registers"| node_auth_router
node_main -->|"registers"| node_product_router
node_main -->|"registers"| node_cart_router
node_main -->|"registers"| node_payment_router
node_auth_router -->|"dispatches"| node_auth_handler
node_auth_handler -->|"auth operations"| node_auth_service
node_auth_service -->|"issues tokens"| node_jwt
node_jwt_middleware -->|"validates"| node_jwt
node_product_router -->|"catalog requests"| node_product_service
node_product_service -->|"reads and writes"| node_product_repository
node_product_repository -->|"persists"| node_product_model
node_jwt_middleware -->|"protects"| node_cart_router
node_cart_router -->|"dispatches"| node_cart_handler
node_cart_handler -->|"cart mutations"| node_cart_service
node_cart_service -->|"manages"| node_cart_model
node_cart_service -->|"validates availability"| node_product_service
node_jwt_middleware -->|"protects"| node_payment_router
node_payment_router -->|"dispatches"| node_payment_handler
node_payment_handler -->|"checkout request"| node_payment_service
node_payment_service -->|"retrieves cart"| node_cart_service
node_payment_service -->|"charges"| node_payment_gateway

click node_main "https://github.com/afloresc/e-commerce-api/blob/main/cmd/main.go"
click node_auth_router "https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/router.go"
click node_auth_handler "https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/handler.go"
click node_auth_service "https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/service.go"
click node_jwt "https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/jwt.go"
click node_jwt_middleware "https://github.com/afloresc/e-commerce-api/blob/main/middleware/jwt.go"
click node_product_router "https://github.com/afloresc/e-commerce-api/blob/main/internal/product/router.go"
click node_product_service "https://github.com/afloresc/e-commerce-api/blob/main/internal/product/service.go"
click node_product_repository "https://github.com/afloresc/e-commerce-api/blob/main/internal/product/repository.go"
click node_product_model "https://github.com/afloresc/e-commerce-api/blob/main/internal/product/model.go"
click node_cart_router "https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/router.go"
click node_cart_handler "https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/handler.go"
click node_cart_service "https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/service.go"
click node_cart_model "https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/model.go"
click node_payment_router "https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/router.go"
click node_payment_handler "https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/handler.go"
click node_payment_service "https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/service.go"

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_auth_router,node_auth_handler,node_auth_service,node_jwt,node_jwt_middleware toneBlue
class node_product_router,node_product_service,node_product_repository,node_product_model toneAmber
class node_cart_router,node_cart_handler,node_cart_service,node_cart_model toneMint
class node_payment_router,node_payment_handler,node_payment_service,node_payment_gateway toneRose
class node_main toneNeutral
```

## Components

### Authentication

- [Auth Router](https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/router.go): HTTP routes · `internal/auth/router.go`
- [Auth Handler](https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/handler.go): HTTP handler · `internal/auth/handler.go`
- [Auth Service](https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/service.go): domain service · `internal/auth/service.go`
- [JWT Support](https://github.com/afloresc/e-commerce-api/blob/main/internal/auth/jwt.go): token service · `internal/auth/jwt.go`
- [JWT Middleware](https://github.com/afloresc/e-commerce-api/blob/main/middleware/jwt.go): shared middleware · Authenticates protected requests and supplies user context. · `middleware/jwt.go`

### Product Catalog

- [Product Router](https://github.com/afloresc/e-commerce-api/blob/main/internal/product/router.go): HTTP routes · `internal/product/router.go`
- [Product Service](https://github.com/afloresc/e-commerce-api/blob/main/internal/product/service.go): domain service · `internal/product/service.go`
- [Product Repository](https://github.com/afloresc/e-commerce-api/blob/main/internal/product/repository.go): persistence boundary · `internal/product/repository.go`
- [Product Model](https://github.com/afloresc/e-commerce-api/blob/main/internal/product/model.go): domain model · `internal/product/model.go`

### Cart

- [Cart Router](https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/router.go): HTTP routes · `internal/cart/router.go`
- [Cart Handler](https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/handler.go): HTTP handler · `internal/cart/handler.go`
- [Cart Service](https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/service.go): domain service · Maintains user carts and validates checkout-ready contents. · `internal/cart/service.go`
- [Cart Model](https://github.com/afloresc/e-commerce-api/blob/main/internal/cart/model.go): domain model · `internal/cart/model.go`

### Checkout & Payment

- [Payment Router](https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/router.go): HTTP routes · `internal/payment/router.go`
- [Payment Handler](https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/handler.go): HTTP handler · `internal/payment/handler.go`
- [Payment Service](https://github.com/afloresc/e-commerce-api/blob/main/internal/payment/service.go): checkout service · Translates gateway outcomes into checkout results. · `internal/payment/service.go`
- **Payment Gateway**: external service · Third-party payment provider such as Stripe.

### Other components

- [API Server](https://github.com/afloresc/e-commerce-api/blob/main/cmd/main.go): Go entry point · Assembles routers and middleware. · `cmd/main.go`

## Connections

- API Server → Auth Router: registers
- API Server → Product Router: registers
- API Server → Cart Router: registers
- API Server → Payment Router: registers
- Auth Router → Auth Handler: dispatches
- Auth Handler → Auth Service: auth operations
- Auth Service → JWT Support: issues tokens
- JWT Middleware → JWT Support: validates
- Product Router → Product Service: catalog requests
- Product Service → Product Repository: reads and writes
- Product Repository → Product Model: persists
- JWT Middleware → Cart Router: protects
- Cart Router → Cart Handler: dispatches
- Cart Handler → Cart Service: cart mutations
- Cart Service → Cart Model: manages
- Cart Service → Product Service: validates availability
- JWT Middleware → Payment Router: protects
- Payment Router → Payment Handler: dispatches
- Payment Handler → Payment Service: checkout request
- Payment Service → Cart Service: retrieves cart
- Payment Service → Payment Gateway: charges