### Environment Configuration Example

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Illustrates environment variable configuration for the Aris API application. Covers settings for server, database, cache, authentication, OAuth2, object storage, and worker pools.

```bash
# Copy environment template
cp env/api.env.template env/api.env

# Example configuration (env/api.env)
PORT=8080
READ_TIMEOUT=10s
WRITE_TIMEOUT=5m
LOG_LEVEL=INFO
LOG_DIR=./logs

# PostgreSQL Database
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
POSTGRES_DATABASE=mydb
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_SSLMODE=disable

# Redis Cache
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=redispassword

# JWT Authentication
JWT_ACCESS_TOKEN_EXPIRED=12h
JWT_ACCESS_TOKEN_SECRET=your-access-secret-key
JWT_REFRESH_TOKEN_EXPIRED=168h
JWT_REFRESH_TOKEN_SECRET=your-refresh-secret-key

# OAuth2 GitHub
OAUTH2_STATE_STRING=random-state-string
OAUTH2_GITHUB_CLIENT_ID=your-github-client-id
OAUTH2_GITHUB_CLIENT_SECRET=your-github-client-secret
OAUTH2_GITHUB_REDIRECT_URL=http://localhost:8080/v1/oauth2/github/callback

# OAuth2 Google
OAUTH2_GOOGLE_CLIENT_ID=your-google-client-id
OAUTH2_GOOGLE_CLIENT_SECRET=your-google-client-secret
OAUTH2_GOOGLE_REDIRECT_URL=http://localhost:8080/v1/oauth2/google/callback

# MinIO Object Storage
MINIO_ENDPOINT=minio:9000
MINIO_TLS=false
MINIO_ACCESS_ID=minio-access-id
MINIO_ACCESS_KEY=minio-access-key

# Worker Pool Settings
POOL_WORKERS=8
POOL_QUEUE_SIZE=100
SQL_BATCH_SIZE=500
```

--------------------------------

### GET /api/v1/oauth2/login

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Initiates the OAuth2 authentication flow by returning the authorization URL.

```APIDOC
## GET /api/v1/oauth2/login

### Description
Returns the authorization URL for the specified platform (GitHub or Google) to begin the authentication process.

### Method
GET

### Endpoint
/api/v1/oauth2/login

### Parameters
#### Query Parameters
- **platform** (string) - Required - The OAuth provider (e.g., "github" or "google").

### Response
#### Success Response (200)
- **redirectURL** (string) - The URL to redirect the user to for authentication.

#### Response Example
{
  "data": {
    "redirectURL": "https://github.com/login/oauth/authorize?client_id=xxx..."
  }
}
```

--------------------------------

### GET /health

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Verifies the server availability and basic operational status.

```APIDOC
## GET /health

### Description
Verifies server availability and basic functionality.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Indicates the server is operational ("ok").

#### Response Example
{
  "data": {
    "status": "ok"
  }
}
```

--------------------------------

### Aris API CLI Commands

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Provides command-line interface commands for managing the Aris API server and database. Uses Cobra for CLI framework. Includes starting the server, running migrations, and building the application.

```bash
# Start the API server with default settings (localhost:8080)
go run main.go server start

# Start server with custom host and port
go run main.go server start --host 0.0.0.0 --port 3000

# Run database migration to create/update schema
go run main.go database migrate

# Build and run the binary
go build -o aris-api-tmpl main.go
./aris-api-tmpl server start --port 8080
```

--------------------------------

### Get Current User Info

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Retrieves the information of the currently authenticated user.

```APIDOC
## GET /api/v1/user/current

### Description
Retrieves the details of the currently authenticated user, including their ID, creation date, last login, permissions, name, email, and avatar.

### Method
GET

### Endpoint
/api/v1/user/current

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://localhost:8080/api/v1/user/current \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the user information.
  - **user** (object) - User details.
    - **id** (integer) - Unique identifier for the user.
    - **createdAt** (string) - Timestamp when the user was created.
    - **lastLogin** (string) - Timestamp of the user's last login.
    - **permission** (string) - User's permission level (e.g., "user").
    - **name** (string) - The user's name.
    - **email** (string) - The user's email address.
    - **avatar** (string) - URL to the user's avatar image.

#### Response Example (Success)
```json
{
  "data": {
    "user": {
      "id": 1,
      "createdAt": "2024-01-15 10:30:00",
      "lastLogin": "2024-03-01 14:25:30",
      "permission": "user",
      "name": "johndoe",
      "email": "john@example.com",
      "avatar": "https://avatars.githubusercontent.com/u/12345"
    }
  }
}
```

#### Error Response (401)
- **data** (object) - Contains error details.
  - **error** (object) - Error object.
    - **code** (string) - Error code (e.g., "UNAUTHORIZED").
    - **message** (string) - Description of the error.

#### Response Example (Error)
```json
{
  "data": {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Unauthorized"
    }
  }
}
```
```

--------------------------------

### GET /ssehealth

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Provides a streaming response for testing Server-Sent Events (SSE) functionality.

```APIDOC
## GET /ssehealth

### Description
Sends 30 heartbeat events at regular intervals to verify real-time streaming capabilities.

### Method
GET

### Endpoint
/ssehealth

### Response
#### Success Response (200)
- **data** (string) - Heartbeat event payload containing sequence number.

#### Response Example
data: {"dataType":"heartbeat","status":"","data":"0"}
```

--------------------------------

### Get Current User Info API

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Retrieves information about the currently authenticated user. Requires JWT authentication. Returns user details on success or an unauthorized error.

```bash
curl -X GET http://localhost:8080/api/v1/user/current \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx"
```

--------------------------------

### Define Database Models and Migrations

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Shows the definition of a User model using GORM tags and the initialization of database migrations. This ensures consistent schema management across environments.

```go
type User struct {
    BaseModel
    ID           uint            `gorm:"primaryKey;autoIncrement"`
    Name         string          `gorm:"not null"`
    Email        string          `gorm:"not null"`
    Avatar       string          `gorm:"not null"`
    Permission   enum.Permission `gorm:"not null;default:'reader'"`
    LastLogin    time.Time
    GithubBindID string          `gorm:"unique"`
    GoogleBindID string          `gorm:"unique"`
}

func main() {
    database.InitDatabase()
    db := database.GetDBInstance(context.Background())
    db.AutoMigrate(&model.User{})
}
```

--------------------------------

### Implement Token Bucket Rate Limiting Middleware

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Demonstrates how to apply rate limiting to API routes using a token bucket algorithm. This middleware uses Redis for distributed state management and supports custom capacity and refill periods.

```go
huma.Register(oauth2Group, huma.Operation{
    OperationID: "oauth2Callback",
    Method:      http.MethodPost,
    Path:        "/callback",
    Middlewares: huma.Middlewares{
        middleware.TokenBucketRateLimiterMiddleware(
            "oauth2Callback",
            "",
            time.Minute,
            10,
        ),
    },
}, oauth2Handler.HandleCallback)
```

--------------------------------

### Access OpenAPI Documentation via CLI

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Provides commands to interact with the auto-generated OpenAPI V3 documentation. These commands allow developers to view the API explorer or retrieve the raw JSON specification.

```bash
curl http://localhost:8080/docs
curl http://localhost:8080/openapi.json
```

--------------------------------

### Docker Deployment

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Instructions for deploying the Aris API application using Docker Compose.

```APIDOC
## Docker Deployment

Deploy the application using Docker Compose with PostgreSQL, Redis, and MinIO services.

### Docker Volumes
Create required Docker volumes for persistent storage:
```bash
docker volume create postgresql-data
docker volume create redis-data
docker volume create minio-data
```

### Starting Services
- **Start all services (PostgreSQL, Redis, MinIO, API server):**
  ```bash
docker compose -f docker/docker-compose-full.yml up -d
  ```
- **Start development environment with a single container:**
  ```bash
docker compose -f docker/docker-compose-dev-single.yml up -d
  ```

### Managing Logs
- **View logs for the API service:**
  ```bash
docker compose -f docker/docker-compose-full.yml logs -f api
  ```

### Stopping Services
- **Stop all services:**
  ```bash
docker compose -f docker/docker-compose-full.yml down
  ```
```

--------------------------------

### Initiate OAuth2 Authentication

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Retrieves the authorization URL for a specified platform (GitHub or Google). The client must redirect the user to the returned URL to complete the flow.

```bash
curl -X GET "http://localhost:8080/api/v1/oauth2/login?platform=github"
curl -X GET "http://localhost:8080/api/v1/oauth2/login?platform=google"
```

--------------------------------

### Docker Deployment Commands

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Commands for deploying the Aris API application using Docker Compose. Includes creating volumes, starting/stopping services, and viewing logs for different environments.

```bash
# Create required Docker volumes
docker volume create postgresql-data
docker volume create redis-data
docker volume create minio-data

# Start all services (PostgreSQL, Redis, MinIO, API server)
docker compose -f docker/docker-compose-full.yml up -d

# Start development environment with single container
docker compose -f docker/docker-compose-dev-single.yml up -d

# View logs
docker compose -f docker/docker-compose-full.yml logs -f api

# Stop all services
docker compose -f docker/docker-compose-full.yml down
```

--------------------------------

### Test SSE Streaming

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Verifies real-time streaming capabilities by connecting to the SSE health endpoint. It expects a stream of heartbeat events.

```bash
curl -X GET http://localhost:8080/ssehealth -H "Accept: text/event-stream"
```

--------------------------------

### CLI Commands

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Provides essential command-line interface commands for managing the Aris API server and database.

```APIDOC
## CLI Commands

The application provides a CLI interface for server management and database operations using Cobra.

### Starting the Server
- **Start with default settings:**
  ```bash
  go run main.go server start
  ```
- **Start with custom host and port:**
  ```bash
  go run main.go server start --host 0.0.0.0 --port 3000
  ```

### Database Operations
- **Run database migration:**
  ```bash
  go run main.go database migrate
  ```

### Building the Application
- **Build the binary:**
  ```bash
  go build -o aris-api-tmpl main.go
  ./aris-api-tmpl server start --port 8080
  ```
```

--------------------------------

### POST /api/v1/oauth2/callback

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Handles the OAuth2 callback and exchanges the authorization code for JWT tokens.

```APIDOC
## POST /api/v1/oauth2/callback

### Description
Exchanges the authorization code for tokens, creates or updates the user account, and returns JWT access and refresh tokens.

### Method
POST

### Endpoint
/api/v1/oauth2/callback

### Request Body
- **platform** (string) - Required - The OAuth provider.
- **code** (string) - Required - The authorization code from the provider.
- **state** (string) - Required - The state string for security verification.

### Response
#### Success Response (200)
- **accessToken** (string) - JWT access token.
- **refreshToken** (string) - JWT refresh token.

#### Response Example
{
  "data": {
    "accessToken": "...",
    "refreshToken": "..."
  }
}
```

--------------------------------

### Environment Configuration

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Details the environment variables used to configure the Aris API application.

```APIDOC
## Environment Configuration

Configure the application using environment variables. Copy the template and modify values as needed.

### Setup
```bash
cp env/api.env.template env/api.env
```

### Example Configuration (`env/api.env`)
```bash
# Server Settings
PORT=8080
READ_TIMEOUT=10s
WRITE_TIMEOUT=5m
LOG_LEVEL=INFO
LOG_DIR=./logs

# PostgreSQL Database
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
POSTGRES_DATABASE=mydb
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_SSLMODE=disable

# Redis Cache
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=redispassword

# JWT Authentication
JWT_ACCESS_TOKEN_EXPIRED=12h
JWT_ACCESS_TOKEN_SECRET=your-access-secret-key
JWT_REFRESH_TOKEN_EXPIRED=168h
JWT_REFRESH_TOKEN_SECRET=your-refresh-secret-key

# OAuth2 GitHub
OAUTH2_STATE_STRING=random-state-string
OAUTH2_GITHUB_CLIENT_ID=your-github-client-id
OAUTH2_GITHUB_CLIENT_SECRET=your-github-client-secret
OAUTH2_GITHUB_REDIRECT_URL=http://localhost:8080/v1/oauth2/github/callback

# OAuth2 Google
OAUTH2_GOOGLE_CLIENT_ID=your-google-client-id
OAUTH2_GOOGLE_CLIENT_SECRET=your-google-client-secret
OAUTH2_GOOGLE_REDIRECT_URL=http://localhost:8080/v1/oauth2/google/callback

# MinIO Object Storage
MINIO_ENDPOINT=minio:9000
MINIO_TLS=false
MINIO_ACCESS_ID=minio-access-id
MINIO_ACCESS_KEY=minio-access-key

# Worker Pool Settings
POOL_WORKERS=8
POOL_QUEUE_SIZE=100
SQL_BATCH_SIZE=500
```
```

--------------------------------

### Handle OAuth2 Callback

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Exchanges an authorization code for JWT access and refresh tokens. Requires the platform, code, and state parameters in the request body.

```bash
curl -X POST http://localhost:8080/api/v1/oauth2/callback \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "github",
    "code": "authorization_code_from_oauth_provider",
    "state": "oauth2_state_string"
  }'
```

--------------------------------

### Manage JWT Authentication Claims and Tokens

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Defines the structure for JWT claims and provides utility functions for encoding and decoding tokens. These functions ensure secure user identification and expiration management using HS256 signing.

```go
type Claims struct {
    jwt.RegisteredClaims
    UserID uint `json:"user_id"`
}

func EncodeToken(userID uint) (string, error) {
    claims := Claims{
        UserID: userID,
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().UTC().Add(12 * time.Hour)),
        },
    }
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte("your-secret-key"))
}

func DecodeToken(tokenString string) (uint, error) {
    token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, errors.New("unexpected signing method")
        }
        return []byte("your-secret-key"), nil
    })
    if err != nil {
        return 0, err
    }
    claims, ok := token.Claims.(*Claims)
    if !ok || !token.Valid {
        return 0, errors.New("token is invalid")
    }
    return claims.UserID, nil
}
```

--------------------------------

### Refresh Access Token

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Uses a valid refresh token to obtain a new pair of access and refresh tokens. This is essential for maintaining user sessions without re-authenticating.

```bash
curl -X POST http://localhost:8080/api/v1/token/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxLCJleHAiOjE3MTAzNjgwMDB9.xxx"
  }'
```

--------------------------------

### Verify Server Health

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Checks if the server is operational by hitting the health endpoint. Returns a JSON object with a status field.

```bash
curl -X GET http://localhost:8080/health
```

--------------------------------

### Update User API

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Updates the profile information for the currently authenticated user.

```APIDOC
## PATCH /api/v1/user/

### Description
Updates the current authenticated user's profile information including name, email, and avatar. Requires JWT authentication and appropriate user permissions.

### Method
PATCH

### Endpoint
/api/v1/user/

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **user** (object) - Required - The user object containing fields to update.
  - **name** (string) - Optional - The new name for the user.
  - **email** (string) - Optional - The new email address for the user.
  - **avatar** (string) - Optional - The URL for the user's new avatar.

### Request Example
```bash
curl -X PATCH http://localhost:8080/api/v1/user/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx" \
  -H "Content-Type: application/json" \
  -d '{ "user": { "name": "John Doe", "email": "newemail@example.com", "avatar": "https://example.com/new-avatar.png" } }'
```

### Response
#### Success Response (200)
- **data** (object) - An empty object indicating a successful update.

#### Response Example (Success)
```json
{
  "data": {}
}
```

#### Error Response (403)
- **data** (object) - Contains error details.
  - **error** (object) - Error object.
    - **code** (string) - Error code (e.g., "FORBIDDEN").
    - **message** (string) - Description of the error.

#### Response Example (Error)
```json
{
  "data": {
    "error": {
      "code": "FORBIDDEN",
      "message": "Permission denied"
    }
  }
}
```
```

--------------------------------

### Update User Profile API

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Updates the profile information for the currently authenticated user, including name, email, and avatar. Requires JWT authentication and appropriate permissions. Accepts JSON payload for updates.

```bash
curl -X PATCH http://localhost:8080/api/v1/user/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx" \
  -H "Content-Type: application/json" \
  -d '{ \
    "user": { \
      "name": "John Doe", \
      "email": "newemail@example.com", \
      "avatar": "https://example.com/new-avatar.png" \
    } \
  }'
```

--------------------------------

### POST /api/v1/token/refresh

Source: https://context7.com/hcd233/aris-api-tmpl/llms.txt

Refreshes an expired access token using a valid refresh token.

```APIDOC
## POST /api/v1/token/refresh

### Description
Maintains user sessions by exchanging an existing refresh token for a new pair of tokens.

### Method
POST

### Endpoint
/api/v1/token/refresh

### Request Body
- **refreshToken** (string) - Required - The valid refresh token.

### Response
#### Success Response (200)
- **accessToken** (string) - New JWT access token.
- **refreshToken** (string) - New JWT refresh token.

#### Response Example
{
  "data": {
    "accessToken": "...",
    "refreshToken": "..."
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.