# ieiskyler/user-management architecture

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

- Interactive diagram: https://gitdiagram.com/ieiskyler/user-management
- Repository: https://github.com/ieiskyler/user-management

## Overview

This is a Gin-based user management REST API. Clients register accounts, log in to receive a JWT, then present that token to access paginated user listings. The main internal layers are routing and authentication middleware, HTTP handlers, business services, and a GORM repository backed by PostgreSQL. Startup wires these components, configures the database connection pool, and migrates the user table. The README documents the endpoint capabilities; connections not demonstrated by the supplied excerpts are omitted.

Main entry points: [`cmd/api/main.go`](https://github.com/ieiskyler/user-management/blob/develop/cmd/api/main.go) (Application startup), [`internal/handler/user_handler.go`](https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_handler.go) (User listing handler), [`internal/server/router.go`](https://github.com/ieiskyler/user-management/blob/develop/internal/server/router.go) (HTTP routing), [`internal/repository/user_repository.go`](https://github.com/ieiskyler/user-management/blob/develop/internal/repository/user_repository.go) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API runtime"]
  node_main["Application startup<br/>[main.go]"]
  node_router["HTTP routing<br/>[router.go]"]
  node_response["API error responses<br/>[response.go]"]
end

subgraph group_identity["Identity"]
  node_auth_middleware["JWT middleware<br/>[auth_middleware.go]"]
  node_auth_handler["Register and login<br/>[auth_handler.go]"]
  node_auth_service["Auth business logic<br/>[auth_service.go]"]
  node_jwt_config["JWT secret config<br/>[auth.go]"]
end

subgraph group_users["User listing"]
  node_user_handler["User listing handler<br/>[user_handler.go]"]
  node_query["Pagination query<br/>[user_query.go]"]
  node_user_response["User summaries<br/>[user_response.go]"]
  node_user_service["User listing service<br/>[user_service.go]"]
end

subgraph group_data["Persistence"]
  node_user_repository["User repository<br/>[user_repository.go]"]
  node_user_model["User model<br/>[user.go]"]
  node_database_config["Database setup<br/>[database.go]"]
  node_pool_config["Pool settings<br/>[database_pool.go]"]
end

node_client(("API client"))
node_postgres[("PostgreSQL")]

node_client -->|"sends HTTP requests"| node_router
node_main -->|"connects database"| node_database_config
node_main -->|"constructs repository"| node_user_repository
node_main -->|"constructs service"| node_auth_service
node_main -->|"constructs service"| node_user_service
node_main -->|"constructs handler"| node_auth_handler
node_main -->|"constructs handler"| node_user_handler
node_main -->|"starts router"| node_router
node_router -->|"routes auth requests"| node_auth_handler
node_router -->|"protects user route"| node_auth_middleware
node_router -->|"routes user listing"| node_user_handler
node_auth_handler -->|"calls auth operations"| node_auth_service
node_auth_handler -->|"formats errors"| node_response
node_auth_service -->|"creates and finds users"| node_user_repository
node_auth_service -->|"loads signing secret"| node_jwt_config
node_auth_middleware -->|"loads validation secret"| node_jwt_config
node_auth_middleware -->|"formats errors"| node_response
node_user_handler -->|"binds and normalizes"| node_query
node_user_handler -->|"requests page"| node_user_service
node_user_handler -->|"converts user results"| node_user_response
node_user_handler -->|"formats errors"| node_response
node_user_service -->|"fetches page"| node_user_repository
node_user_repository -->|"reads and writes users"| node_postgres
node_user_repository -->|"queries user records"| node_user_model
node_database_config -->|"loads pool settings"| node_pool_config
node_database_config -->|"opens and migrates"| node_postgres
node_database_config -->|"migrates user table"| node_user_model

click node_main "https://github.com/ieiskyler/user-management/blob/develop/cmd/api/main.go"
click node_router "https://github.com/ieiskyler/user-management/blob/develop/internal/server/router.go"
click node_auth_middleware "https://github.com/ieiskyler/user-management/blob/develop/internal/middleware/auth_middleware.go"
click node_auth_handler "https://github.com/ieiskyler/user-management/blob/develop/internal/handler/auth_handler.go"
click node_auth_service "https://github.com/ieiskyler/user-management/blob/develop/internal/service/auth_service.go"
click node_user_handler "https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_handler.go"
click node_query "https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_query.go"
click node_user_response "https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_response.go"
click node_user_service "https://github.com/ieiskyler/user-management/blob/develop/internal/service/user_service.go"
click node_user_repository "https://github.com/ieiskyler/user-management/blob/develop/internal/repository/user_repository.go"
click node_user_model "https://github.com/ieiskyler/user-management/blob/develop/internal/models/user.go"
click node_database_config "https://github.com/ieiskyler/user-management/blob/develop/internal/config/database.go"
click node_pool_config "https://github.com/ieiskyler/user-management/blob/develop/internal/config/database_pool.go"
click node_jwt_config "https://github.com/ieiskyler/user-management/blob/develop/internal/config/auth.go"
click node_response "https://github.com/ieiskyler/user-management/blob/develop/internal/response/response.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_main,node_router,node_response,node_client toneBlue
class node_auth_middleware,node_auth_handler,node_auth_service,node_jwt_config,node_postgres toneAmber
class node_user_handler,node_query,node_user_response,node_user_service toneMint
class node_user_repository,node_user_model,node_database_config,node_pool_config toneRose
```

## Components

### API runtime

- [Application startup](https://github.com/ieiskyler/user-management/blob/develop/cmd/api/main.go): `cmd/api/main.go`
- [HTTP routing](https://github.com/ieiskyler/user-management/blob/develop/internal/server/router.go): `internal/server/router.go`
- [API error responses](https://github.com/ieiskyler/user-management/blob/develop/internal/response/response.go): `internal/response/response.go`

### Identity

- [JWT middleware](https://github.com/ieiskyler/user-management/blob/develop/internal/middleware/auth_middleware.go): `internal/middleware/auth_middleware.go`
- [Register and login](https://github.com/ieiskyler/user-management/blob/develop/internal/handler/auth_handler.go): `internal/handler/auth_handler.go`
- [Auth business logic](https://github.com/ieiskyler/user-management/blob/develop/internal/service/auth_service.go): `internal/service/auth_service.go`
- [JWT secret config](https://github.com/ieiskyler/user-management/blob/develop/internal/config/auth.go): `internal/config/auth.go`

### User listing

- [User listing handler](https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_handler.go): `internal/handler/user_handler.go`
- [Pagination query](https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_query.go): `internal/handler/user_query.go`
- [User summaries](https://github.com/ieiskyler/user-management/blob/develop/internal/handler/user_response.go): `internal/handler/user_response.go`
- [User listing service](https://github.com/ieiskyler/user-management/blob/develop/internal/service/user_service.go): `internal/service/user_service.go`

### Persistence

- [User repository](https://github.com/ieiskyler/user-management/blob/develop/internal/repository/user_repository.go): `internal/repository/user_repository.go`
- [User model](https://github.com/ieiskyler/user-management/blob/develop/internal/models/user.go): `internal/models/user.go`
- [Database setup](https://github.com/ieiskyler/user-management/blob/develop/internal/config/database.go): `internal/config/database.go`
- [Pool settings](https://github.com/ieiskyler/user-management/blob/develop/internal/config/database_pool.go): `internal/config/database_pool.go`

### Other components

- **API client**
- **PostgreSQL**

## Connections

- API client → HTTP routing: sends HTTP requests (evidence: `README.md`)
- Application startup → Database setup: connects database (evidence: `cmd/api/main.go`)
- Application startup → User repository: constructs repository (evidence: `cmd/api/main.go`)
- Application startup → Auth business logic: constructs service (evidence: `cmd/api/main.go`)
- Application startup → User listing service: constructs service (evidence: `cmd/api/main.go`)
- Application startup → Register and login: constructs handler (evidence: `cmd/api/main.go`)
- Application startup → User listing handler: constructs handler (evidence: `cmd/api/main.go`)
- Application startup → HTTP routing: starts router (evidence: `cmd/api/main.go`)
- HTTP routing → Register and login: routes auth requests (evidence: `internal/server/router.go`)
- HTTP routing → JWT middleware: protects user route (evidence: `internal/server/router.go`)
- HTTP routing → User listing handler: routes user listing (evidence: `internal/server/router.go`)
- Register and login → Auth business logic: calls auth operations (evidence: `internal/handler/auth_handler.go`)
- Register and login → API error responses: formats errors (evidence: `internal/handler/auth_handler.go`)
- Auth business logic → User repository: creates and finds users (evidence: `internal/service/auth_service.go`)
- Auth business logic → JWT secret config: loads signing secret (evidence: `internal/service/auth_service.go`)
- JWT middleware → JWT secret config: loads validation secret (evidence: `internal/middleware/auth_middleware.go`)
- JWT middleware → API error responses: formats errors (evidence: `internal/middleware/auth_middleware.go`)
- User listing handler → Pagination query: binds and normalizes (evidence: `internal/handler/user_handler.go`)
- User listing handler → User listing service: requests page (evidence: `internal/handler/user_handler.go`)
- User listing handler → User summaries: converts user results (evidence: `internal/handler/user_handler.go`)
- User listing handler → API error responses: formats errors (evidence: `internal/handler/user_handler.go`)
- User listing service → User repository: fetches page (evidence: `internal/service/user_service.go`)
- User repository → PostgreSQL: reads and writes users (evidence: `internal/repository/user_repository.go`)
- User repository → User model: queries user records (evidence: `internal/repository/user_repository.go`)
- Database setup → Pool settings: loads pool settings (evidence: `internal/config/database.go`)
- Database setup → PostgreSQL: opens and migrates (evidence: `internal/config/database.go`)
- Database setup → User model: migrates user table (evidence: `internal/config/database.go`)