# habibi-source/ostore-service-api architecture

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

- Interactive diagram: https://gitdiagram.com/habibi-source/ostore-service-api
- Repository: https://github.com/habibi-source/ostore-service-api

## Overview

This is a Gin-based online-store API. Clients register or log in, then use public catalog and region endpoints or authenticated profile, store, address, and transaction endpoints; administrators can manage categories. Handlers pass work to use cases, which are wired to repositories at startup. Authentication validates JWTs and loads users, while repositories use MySQL; region repositories provide a separate external-data branch. The README is empty, and most handler, use-case, and repository implementations were not sampled, so those links reflect explicit startup wiring and the repository structure rather than unsampled internal call details.

Main entry points: [`cmd/api/main.go`](https://github.com/habibi-source/ostore-service-api/blob/main/cmd/api/main.go) (Gin API), [`internal/repository/user_repository.go`](https://github.com/habibi-source/ostore-service-api/blob/main/internal/repository/user_repository.go) (User repository), [`internal/usecase/auth_usecase.go`](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/auth_usecase.go) (Authentication), [`internal/usecase/user_usecase.go`](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/user_usecase.go) (User services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api_server["Gin API<br/>[main.go]"]
  node_auth_mw["Auth middleware<br/>[auth_middleware.go]"]
end

subgraph group_commerce["Store commerce"]
  node_store_handler["Store endpoints<br/>[store_handler.go]"]
  node_store_uc["Store services<br/>[store_usecase.go]"]
  node_address_handler["Address endpoints<br/>[address_handler.go]"]
  node_address_uc["Address services<br/>[address_usecase.go]"]
  node_category_handler["Category endpoints"]
  node_category_uc["Category services"]
  node_product_handler["Product endpoints<br/>[product_handler.go]"]
  node_product_uc["Product services<br/>[product_usecase.go]"]
  node_transaction_handler["Transaction endpoints"]
  node_transaction_uc["Transaction services"]
  node_region_handler["Region endpoints<br/>[region_handler.go]"]
  node_region_uc["Region services<br/>[region_usecase.go]"]
end

subgraph group_identity["Identity and accounts"]
  node_auth_handler["Auth endpoints<br/>[auth_handler.go]"]
  node_auth_uc["Authentication<br/>[auth_usecase.go]"]
  node_user_handler["User endpoints<br/>[user_handler.go]"]
  node_user_uc["User services<br/>[user_usecase.go]"]
end

subgraph group_infra["Data and integrations"]
  node_user_repo["User repository<br/>[user_repository.go]"]
  node_store_repo["Store repository"]
  node_region_api_repos["Region API repositories"]
  node_mysql[("MySQL database<br/>[mysql.go]")]
  node_jwt["JWT utility<br/>[jwt.go]"]
end

node_client(("API client"))
node_external_regions(("Region data service"))

node_client -->|"sends requests"| node_api_server
node_api_server -->|"routes auth"| node_auth_handler
node_api_server -->|"routes user"| node_user_handler
node_api_server -->|"routes stores"| node_store_handler
node_api_server -->|"routes addresses"| node_address_handler
node_api_server -->|"routes categories"| node_category_handler
node_api_server -->|"routes products"| node_product_handler
node_api_server -->|"routes transactions"| node_transaction_handler
node_api_server -->|"routes regions"| node_region_handler
node_api_server -->|"protects routes"| node_auth_mw
node_auth_handler -->|"invokes"| node_auth_uc
node_auth_handler -->|"creates default store"| node_user_uc
node_auth_uc -->|"checks and saves users"| node_user_repo
node_auth_uc -->|"creates default store"| node_store_repo
node_auth_uc -->|"generates tokens"| node_jwt
node_auth_mw -->|"validates tokens"| node_jwt
node_auth_mw -->|"loads user"| node_user_repo
node_user_handler -->|"invokes"| node_user_uc
node_user_uc -->|"uses"| node_user_repo
node_user_uc -->|"uses"| node_store_repo
node_store_handler -->|"invokes"| node_store_uc
node_store_uc -->|"uses"| node_store_repo
node_address_handler -->|"invokes"| node_address_uc
node_address_uc -->|"uses"| node_user_repo
node_category_handler -->|"invokes"| node_category_uc
node_product_handler -->|"invokes"| node_product_uc
node_transaction_handler -->|"invokes"| node_transaction_uc
node_region_handler -->|"invokes"| node_region_uc
node_region_uc -->|"uses"| node_region_api_repos
node_external_regions -.->|"provides region data"| node_region_api_repos
node_store_repo -->|"reads and writes"| node_mysql
node_user_repo -->|"reads and writes"| node_mysql
node_product_uc -->|"persists products"| node_mysql
node_transaction_uc -->|"persists transactions"| node_mysql

click node_api_server "https://github.com/habibi-source/ostore-service-api/blob/main/cmd/api/main.go"
click node_auth_mw "https://github.com/habibi-source/ostore-service-api/blob/main/internal/middleware/auth_middleware.go"
click node_auth_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/auth_handler.go"
click node_auth_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/auth_usecase.go"
click node_user_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/user_handler.go"
click node_user_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/user_usecase.go"
click node_user_repo "https://github.com/habibi-source/ostore-service-api/blob/main/internal/repository/user_repository.go"
click node_store_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/store_handler.go"
click node_store_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/store_usecase.go"
click node_store_repo "https://github.com/habibi-source/ostore-service-api/blob/main/internal/repository/store_repository.go"
click node_address_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/address_handler.go"
click node_address_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/address_usecase.go"
click node_category_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/category_handler.go"
click node_category_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/category_usecase.go"
click node_product_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/product_handler.go"
click node_product_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/product_usecase.go"
click node_transaction_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/transaction_handler.go"
click node_transaction_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/transaction_usecase.go"
click node_region_handler "https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/region_handler.go"
click node_region_uc "https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/region_usecase.go"
click node_region_api_repos "https://github.com/habibi-source/ostore-service-api/tree/main/internal/repository"
click node_mysql "https://github.com/habibi-source/ostore-service-api/blob/main/pkg/database/mysql.go"
click node_jwt "https://github.com/habibi-source/ostore-service-api/blob/main/pkg/jwt/jwt.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_api_server,node_auth_mw,node_client toneBlue
class node_store_handler,node_store_uc,node_address_handler,node_address_uc,node_category_handler,node_category_uc,node_product_handler,node_product_uc,node_transaction_handler,node_transaction_uc,node_region_handler,node_region_uc toneAmber
class node_auth_handler,node_auth_uc,node_user_handler,node_user_uc toneMint
class node_user_repo,node_store_repo,node_region_api_repos,node_mysql,node_jwt toneRose
class node_external_regions toneIndigo
```

## Components

### API and access

- [Gin API](https://github.com/habibi-source/ostore-service-api/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Auth middleware](https://github.com/habibi-source/ostore-service-api/blob/main/internal/middleware/auth_middleware.go): `internal/middleware/auth_middleware.go`

### Store commerce

- [Store endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/store_handler.go): `internal/handler/store_handler.go`
- [Store services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/store_usecase.go): `internal/usecase/store_usecase.go`
- [Address endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/address_handler.go): `internal/handler/address_handler.go`
- [Address services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/address_usecase.go): `internal/usecase/address_usecase.go`
- [Category endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/category_handler.go): `internal/handler/category_handler.go`
- [Category services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/category_usecase.go): `internal/usecase/category_usecase.go`
- [Product endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/product_handler.go): `internal/handler/product_handler.go`
- [Product services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/product_usecase.go): `internal/usecase/product_usecase.go`
- [Transaction endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/transaction_handler.go): `internal/handler/transaction_handler.go`
- [Transaction services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/transaction_usecase.go): `internal/usecase/transaction_usecase.go`
- [Region endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/region_handler.go): `internal/handler/region_handler.go`
- [Region services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/region_usecase.go): `internal/usecase/region_usecase.go`

### Identity and accounts

- [Auth endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/auth_handler.go): `internal/handler/auth_handler.go`
- [Authentication](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/auth_usecase.go): `internal/usecase/auth_usecase.go`
- [User endpoints](https://github.com/habibi-source/ostore-service-api/blob/main/internal/handler/user_handler.go): `internal/handler/user_handler.go`
- [User services](https://github.com/habibi-source/ostore-service-api/blob/main/internal/usecase/user_usecase.go): `internal/usecase/user_usecase.go`

### Data and integrations

- [User repository](https://github.com/habibi-source/ostore-service-api/blob/main/internal/repository/user_repository.go): `internal/repository/user_repository.go`
- [Store repository](https://github.com/habibi-source/ostore-service-api/blob/main/internal/repository/store_repository.go): `internal/repository/store_repository.go`
- [Region API repositories](https://github.com/habibi-source/ostore-service-api/tree/main/internal/repository): `internal/repository`
- [MySQL database](https://github.com/habibi-source/ostore-service-api/blob/main/pkg/database/mysql.go): `pkg/database/mysql.go`
- [JWT utility](https://github.com/habibi-source/ostore-service-api/blob/main/pkg/jwt/jwt.go): `pkg/jwt/jwt.go`

### Other components

- **API client**
- **Region data service**

## Connections

- API client → Gin API: sends requests
- Gin API → Auth endpoints: routes auth
- Gin API → User endpoints: routes user
- Gin API → Store endpoints: routes stores
- Gin API → Address endpoints: routes addresses
- Gin API → Category endpoints: routes categories
- Gin API → Product endpoints: routes products
- Gin API → Transaction endpoints: routes transactions
- Gin API → Region endpoints: routes regions
- Gin API → Auth middleware: protects routes
- Auth endpoints → Authentication: invokes
- Auth endpoints → User services: creates default store
- Authentication → User repository: checks and saves users
- Authentication → Store repository: creates default store
- Authentication → JWT utility: generates tokens
- Auth middleware → JWT utility: validates tokens
- Auth middleware → User repository: loads user
- User endpoints → User services: invokes
- User services → User repository: uses
- User services → Store repository: uses
- Store endpoints → Store services: invokes
- Store services → Store repository: uses
- Address endpoints → Address services: invokes
- Address services → User repository: uses
- Category endpoints → Category services: invokes
- Product endpoints → Product services: invokes
- Transaction endpoints → Transaction services: invokes
- Region endpoints → Region services: invokes
- Region services → Region API repositories: uses
- Region data service → Region API repositories: provides region data
- Store repository → MySQL database: reads and writes
- User repository → MySQL database: reads and writes
- Product services → MySQL database: persists products
- Transaction services → MySQL database: persists transactions