# devbenho/luka-platform architecture

> Architecture diagram of the GitHub repository devbenho/luka-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devbenho/luka-platform
- Repository: https://github.com/devbenho/luka-platform

## Overview

Luka Platform is an e-commerce application with a Gin/MongoDB API and a Next.js interface. The backend workflow starts at HTTP routes, passes through handlers and domain services, and persists through repositories; order creation also prices products and reserves inventory, rolling back reservations if saving fails. User authentication, catalog, category, store, and inventory management are separate capabilities. The README also names warehouse management, but the tree shows only its model, so no operational warehouse flow is inferred. Edges are limited to route and service relationships evidenced by excerpts or the README.

Main entry points: [`internal/server/http/server.go`](https://github.com/devbenho/luka-platform/blob/main/internal/server/http/server.go) (HTTP Server), [`ports/http/orders/routes.go`](https://github.com/devbenho/luka-platform/blob/main/ports/http/orders/routes.go) (Order Routes), [`pkg/database/database.go`](https://github.com/devbenho/luka-platform/blob/main/pkg/database/database.go) (MongoDB Access), [`internal/inventory/services/inventory_service.go`](https://github.com/devbenho/luka-platform/blob/main/internal/inventory/services/inventory_service.go) (Inventory Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["HTTP Server<br/>[server.go]"]
  node_users_http["User Routes<br/>[routes.go]"]
  node_orders_http["Order Routes<br/>[routes.go]"]
  node_products_http["Product Routes<br/>[routes.go]"]
  node_inventory_http["Inventory Routes<br/>[routes.go]"]
  node_stores_http["Store Routes<br/>[routes.go]"]
  node_categories_http["Category Routes<br/>[routes.go]"]
end

subgraph group_commerce["Commerce Domains"]
  node_orders["Order Processing<br/>[order_service.go]"]
  node_order_repo["Order Repository"]
  node_products["Product Catalog<br/>[product_service.go]"]
  node_product_repo["Product Repository"]
  node_inventory["Inventory Operations"]
  node_inventory_repo["Inventory Repository"]
  node_stores["Store Management<br/>[store_service.go]"]
  node_store_repo["Store Repository"]
  node_categories["Category Management"]
  node_category_repo["Category Repository"]
  node_warehouse["Warehouse Model<br/>[warehouse.go]"]
end

subgraph group_identity["Identity"]
  node_users["User Management<br/>[user_service.go]"]
  node_user_repo["User Repository<br/>[user_repository.go]"]
  node_tokens["JWT Tokens<br/>[main.go]"]
  node_hasher["Password Hashing<br/>[main.go]"]
end

subgraph group_platform["Platform Services"]
  node_main["API Bootstrap<br/>[main.go]"]
  node_database[("MongoDB Access<br/>[database.go]")]
end

subgraph group_frontend["Web Interface"]
  node_web["Next.js Interface<br/>[header.tsx]"]
end

node_customer(("API Client"))

node_customer -->|"sends requests"| node_server
node_main -->|"starts"| node_server
node_main -->|"connects"| node_database
node_server -->|"maps routes"| node_users_http
node_server -->|"maps routes"| node_orders_http
node_server -->|"maps routes"| node_products_http
node_server -->|"maps routes"| node_inventory_http
node_server -->|"maps routes"| node_stores_http
node_server -->|"maps routes"| node_categories_http
node_users_http -->|"constructs service"| node_users
node_users_http -->|"constructs repository"| node_user_repo
node_users_http -->|"constructs token service"| node_tokens
node_users_http -->|"constructs hasher"| node_hasher
node_users -->|"reads and writes"| node_user_repo
node_users -->|"generates tokens"| node_tokens
node_users -->|"hashes passwords"| node_hasher
node_orders_http -->|"constructs service"| node_orders
node_orders_http -->|"constructs repository"| node_order_repo
node_orders_http -->|"constructs service"| node_inventory
node_orders_http -->|"constructs service"| node_products
node_orders_http -->|"constructs repository"| node_store_repo
node_orders -->|"gets product pricing"| node_products
node_orders -->|"reserves stock"| node_inventory
node_orders -->|"releases stock"| node_inventory
node_orders -->|"persists orders"| node_order_repo
node_products_http -->|"constructs service"| node_products
node_products_http -->|"constructs repository"| node_product_repo
node_products -->|"reads and writes"| node_product_repo
node_inventory_http -->|"constructs service"| node_inventory
node_inventory_http -->|"constructs repository"| node_inventory_repo
node_inventory -->|"reads and writes"| node_inventory_repo
node_inventory -->|"checks product"| node_product_repo
node_stores_http -->|"constructs service"| node_stores
node_stores_http -->|"constructs repository"| node_store_repo
node_stores -->|"reads and writes"| node_store_repo
node_categories_http -->|"constructs service"| node_categories
node_categories_http -->|"constructs repository"| node_category_repo
node_categories -->|"reads and writes"| node_category_repo
node_product_repo -.->|"uses database"| node_database
node_inventory_repo -->|"uses database"| node_database
node_order_repo -->|"uses database"| node_database
node_user_repo -->|"uses database"| node_database
node_store_repo -->|"uses database"| node_database
node_category_repo -->|"uses database"| node_database
node_customer -->|"uses interface"| node_web
node_web -.->|"API integration"| node_server

click node_main "https://github.com/devbenho/luka-platform/blob/main/cmd/api/main.go"
click node_server "https://github.com/devbenho/luka-platform/blob/main/internal/server/http/server.go"
click node_users_http "https://github.com/devbenho/luka-platform/blob/main/ports/http/users/routes.go"
click node_orders_http "https://github.com/devbenho/luka-platform/blob/main/ports/http/orders/routes.go"
click node_products_http "https://github.com/devbenho/luka-platform/blob/main/ports/http/products/routes.go"
click node_inventory_http "https://github.com/devbenho/luka-platform/blob/main/ports/http/inventories/routes.go"
click node_stores_http "https://github.com/devbenho/luka-platform/blob/main/ports/http/stores/routes.go"
click node_categories_http "https://github.com/devbenho/luka-platform/blob/main/ports/http/categories/routes.go"
click node_users "https://github.com/devbenho/luka-platform/blob/main/internal/user/services/user_service.go"
click node_user_repo "https://github.com/devbenho/luka-platform/blob/main/internal/user/repositories/user_repository.go"
click node_tokens "https://github.com/devbenho/luka-platform/blob/main/pkg/tokens/main.go"
click node_hasher "https://github.com/devbenho/luka-platform/blob/main/pkg/hasher/main.go"
click node_orders "https://github.com/devbenho/luka-platform/blob/main/internal/orders/services/order_service.go"
click node_order_repo "https://github.com/devbenho/luka-platform/blob/main/internal/orders/repositories/order_repository.go"
click node_products "https://github.com/devbenho/luka-platform/blob/main/internal/product/services/product_service.go"
click node_product_repo "https://github.com/devbenho/luka-platform/blob/main/internal/product/repositories/product_repository.go"
click node_inventory "https://github.com/devbenho/luka-platform/blob/main/internal/inventory/services/inventory_service.go"
click node_inventory_repo "https://github.com/devbenho/luka-platform/blob/main/internal/inventory/repositories/inventory_repository.go"
click node_stores "https://github.com/devbenho/luka-platform/blob/main/internal/store/services/store_service.go"
click node_store_repo "https://github.com/devbenho/luka-platform/blob/main/internal/store/repositories/store_repository.go"
click node_categories "https://github.com/devbenho/luka-platform/blob/main/internal/category/services/category_service.go"
click node_category_repo "https://github.com/devbenho/luka-platform/blob/main/internal/category/repositories/category_repository.go"
click node_warehouse "https://github.com/devbenho/luka-platform/blob/main/internal/warehouse/models/warehouse.go"
click node_database "https://github.com/devbenho/luka-platform/blob/main/pkg/database/database.go"
click node_web "https://github.com/devbenho/luka-platform/blob/main/web/src/app/(main)/(landing)/_sections/header.tsx"

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_server,node_users_http,node_orders_http,node_products_http,node_inventory_http,node_stores_http,node_categories_http,node_customer toneBlue
class node_orders,node_order_repo,node_products,node_product_repo,node_inventory,node_inventory_repo,node_stores,node_store_repo,node_categories,node_category_repo,node_warehouse toneAmber
class node_users,node_user_repo,node_tokens,node_hasher toneMint
class node_main,node_database toneRose
class node_web toneIndigo
```

## Components

### HTTP API

- [HTTP Server](https://github.com/devbenho/luka-platform/blob/main/internal/server/http/server.go): `internal/server/http/server.go`
- [User Routes](https://github.com/devbenho/luka-platform/blob/main/ports/http/users/routes.go): `ports/http/users/routes.go`
- [Order Routes](https://github.com/devbenho/luka-platform/blob/main/ports/http/orders/routes.go): `ports/http/orders/routes.go`
- [Product Routes](https://github.com/devbenho/luka-platform/blob/main/ports/http/products/routes.go): `ports/http/products/routes.go`
- [Inventory Routes](https://github.com/devbenho/luka-platform/blob/main/ports/http/inventories/routes.go): `ports/http/inventories/routes.go`
- [Store Routes](https://github.com/devbenho/luka-platform/blob/main/ports/http/stores/routes.go): `ports/http/stores/routes.go`
- [Category Routes](https://github.com/devbenho/luka-platform/blob/main/ports/http/categories/routes.go): `ports/http/categories/routes.go`

### Commerce Domains

- [Order Processing](https://github.com/devbenho/luka-platform/blob/main/internal/orders/services/order_service.go): `internal/orders/services/order_service.go`
- [Order Repository](https://github.com/devbenho/luka-platform/blob/main/internal/orders/repositories/order_repository.go): `internal/orders/repositories/order_repository.go`
- [Product Catalog](https://github.com/devbenho/luka-platform/blob/main/internal/product/services/product_service.go): `internal/product/services/product_service.go`
- [Product Repository](https://github.com/devbenho/luka-platform/blob/main/internal/product/repositories/product_repository.go): `internal/product/repositories/product_repository.go`
- [Inventory Operations](https://github.com/devbenho/luka-platform/blob/main/internal/inventory/services/inventory_service.go): `internal/inventory/services/inventory_service.go`
- [Inventory Repository](https://github.com/devbenho/luka-platform/blob/main/internal/inventory/repositories/inventory_repository.go): `internal/inventory/repositories/inventory_repository.go`
- [Store Management](https://github.com/devbenho/luka-platform/blob/main/internal/store/services/store_service.go): `internal/store/services/store_service.go`
- [Store Repository](https://github.com/devbenho/luka-platform/blob/main/internal/store/repositories/store_repository.go): `internal/store/repositories/store_repository.go`
- [Category Management](https://github.com/devbenho/luka-platform/blob/main/internal/category/services/category_service.go): `internal/category/services/category_service.go`
- [Category Repository](https://github.com/devbenho/luka-platform/blob/main/internal/category/repositories/category_repository.go): `internal/category/repositories/category_repository.go`
- [Warehouse Model](https://github.com/devbenho/luka-platform/blob/main/internal/warehouse/models/warehouse.go): `internal/warehouse/models/warehouse.go`

### Identity

- [User Management](https://github.com/devbenho/luka-platform/blob/main/internal/user/services/user_service.go): `internal/user/services/user_service.go`
- [User Repository](https://github.com/devbenho/luka-platform/blob/main/internal/user/repositories/user_repository.go): `internal/user/repositories/user_repository.go`
- [JWT Tokens](https://github.com/devbenho/luka-platform/blob/main/pkg/tokens/main.go): `pkg/tokens/main.go`
- [Password Hashing](https://github.com/devbenho/luka-platform/blob/main/pkg/hasher/main.go): `pkg/hasher/main.go`

### Platform Services

- [API Bootstrap](https://github.com/devbenho/luka-platform/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [MongoDB Access](https://github.com/devbenho/luka-platform/blob/main/pkg/database/database.go): `pkg/database/database.go`

### Web Interface

- [Next.js Interface](https://github.com/devbenho/luka-platform/blob/main/web/src/app/(main)/(landing)/_sections/header.tsx): `web/src/app/(main)/(landing)/_sections/header.tsx`

### Other components

- **API Client**

## Connections

- API Client → HTTP Server: sends requests (evidence: `README.md`)
- API Bootstrap → HTTP Server: starts (evidence: `cmd/api/main.go`)
- API Bootstrap → MongoDB Access: connects (evidence: `cmd/api/main.go`)
- HTTP Server → User Routes: maps routes (evidence: `internal/server/http/server.go`)
- HTTP Server → Order Routes: maps routes (evidence: `internal/server/http/server.go`)
- HTTP Server → Product Routes: maps routes (evidence: `internal/server/http/server.go`)
- HTTP Server → Inventory Routes: maps routes (evidence: `internal/server/http/server.go`)
- HTTP Server → Store Routes: maps routes (evidence: `internal/server/http/server.go`)
- HTTP Server → Category Routes: maps routes (evidence: `internal/server/http/server.go`)
- User Routes → User Management: constructs service (evidence: `ports/http/users/routes.go`)
- User Routes → User Repository: constructs repository (evidence: `ports/http/users/routes.go`)
- User Routes → JWT Tokens: constructs token service (evidence: `ports/http/users/routes.go`)
- User Routes → Password Hashing: constructs hasher (evidence: `ports/http/users/routes.go`)
- User Management → User Repository: reads and writes (evidence: `internal/user/services/user_service.go`)
- User Management → JWT Tokens: generates tokens (evidence: `internal/user/services/user_service.go`)
- User Management → Password Hashing: hashes passwords (evidence: `internal/user/services/user_service.go`)
- Order Routes → Order Processing: constructs service (evidence: `ports/http/orders/routes.go`)
- Order Routes → Order Repository: constructs repository (evidence: `ports/http/orders/routes.go`)
- Order Routes → Inventory Operations: constructs service (evidence: `ports/http/orders/routes.go`)
- Order Routes → Product Catalog: constructs service (evidence: `ports/http/orders/routes.go`)
- Order Routes → Store Repository: constructs repository (evidence: `ports/http/orders/routes.go`)
- Order Processing → Product Catalog: gets product pricing (evidence: `internal/orders/services/order_service.go`)
- Order Processing → Inventory Operations: reserves stock (evidence: `internal/orders/services/order_service.go`)
- Order Processing → Inventory Operations: releases stock (evidence: `internal/orders/services/order_service.go`)
- Order Processing → Order Repository: persists orders (evidence: `internal/orders/services/order_service.go`)
- Product Routes → Product Catalog: constructs service (evidence: `ports/http/products/routes.go`)
- Product Routes → Product Repository: constructs repository (evidence: `ports/http/products/routes.go`)
- Product Catalog → Product Repository: reads and writes (evidence: `internal/product/services/product_service.go`)
- Inventory Routes → Inventory Operations: constructs service (evidence: `ports/http/inventories/routes.go`)
- Inventory Routes → Inventory Repository: constructs repository (evidence: `ports/http/inventories/routes.go`)
- Inventory Operations → Inventory Repository: reads and writes (evidence: `internal/inventory/services/inventory_service.go`)
- Inventory Operations → Product Repository: checks product (evidence: `internal/inventory/services/inventory_service.go`)
- Store Routes → Store Management: constructs service (evidence: `ports/http/stores/routes.go`)
- Store Routes → Store Repository: constructs repository (evidence: `ports/http/stores/routes.go`)
- Store Management → Store Repository: reads and writes (evidence: `internal/store/services/store_service.go`)
- Category Routes → Category Management: constructs service (evidence: `ports/http/categories/routes.go`)
- Category Routes → Category Repository: constructs repository (evidence: `ports/http/categories/routes.go`)
- Category Management → Category Repository: reads and writes (evidence: `internal/category/services/category_service.go`)
- Product Repository → MongoDB Access: uses database
- Inventory Repository → MongoDB Access: uses database (evidence: `internal/inventory/repositories/inventory_repository.go`)
- Order Repository → MongoDB Access: uses database (evidence: `internal/orders/repositories/order_repository.go`)
- User Repository → MongoDB Access: uses database (evidence: `internal/user/repositories/user_repository.go`)
- Store Repository → MongoDB Access: uses database (evidence: `internal/store/repositories/store_repository.go`)
- Category Repository → MongoDB Access: uses database (evidence: `internal/category/repositories/category_repository.go`)
- API Client → Next.js Interface: uses interface (evidence: `README.md`)
- Next.js Interface → HTTP Server: API integration
