LK_API_Temp/README.md

# LK API Template

A modern, production-ready API template built with Go and Nuxt 3, featuring comprehensive authentication, mailing capabilities, and automatic API documentation.

## 🚀 Features

- **Backend (Go)**

  - Chi router for efficient HTTP routing
  - Swagger/OpenAPI documentation
  - SendGrid integration for email notifications
  - Rate limiting support
  - Redis caching
  - PostgreSQL database integration
  - JWT-based authentication
  - Environment-based configuration
  - Structured logging with Zap
  - Hot reload support with Air

- **Frontend (Nuxt 3 + TypeScript)**
  - Vue 3 with Composition API
  - TypeScript support
  - Nuxt modules ecosystem
  - Hot Module Replacement (HMR)
  - Auto-imports for components and composables
  - Server-side rendering capabilities
  - File-based routing

## 📋 Prerequisites

- Go 1.23.4 or higher
- Bun 1.0 or higher (for frontend development)
- Docker and Docker Compose
- SendGrid API key (for email functionality)
- Platform-specific requirements:
  - **Mac/Linux**:
    - direnv (for environment management)
    - make
  - **Windows**:
    - Git Bash, WSL2, or PowerShell
    - make (optional, commands can be run manually)

## 🛠️ Installation

1. Clone the repository:

```bash
git clone https://github.com/FernandoJVideira/LK_API_Temp.git
cd LK_API_Temp
```

2. Install Bun (if not already installed):

**Mac/Linux**:

```bash
curl -fsSL https://bun.sh/install | bash
```

**Windows**:

```bash
# Install WSL2 first if not already installed
# Then run the same command as Mac/Linux inside WSL2
```

3. Set up environment variables:

**Mac/Linux with direnv**:

```bash
cp .envrc.example .envrc
# Edit .envrc with your configuration
direnv allow
```

**Windows or alternative setup**:

```bash
cp .env.example .env
# Edit .env with your configuration
```

4. Install backend dependencies:

```bash
go mod download
```

5. Install frontend dependencies:

```bash
cd web
bun install
```

## 🚀 Development

### Infrastructure

**Mac/Linux**:

```bash
# Start services
make start

# Stop services
make stop
```

**Windows (without make)**:

```bash
# Start services
docker-compose up -d

# Stop services
docker-compose down
```

### Database Management

**Mac/Linux**:

```bash
# Create new migration
make migration name=your_migration_name

# Run migrations
make migrate-up

# Rollback migrations
make migrate-down

# Seed database
make seed
```

**Windows (without make)**:

```bash
# Create new migration
go run ./cmd/migrate create your_migration_name

# Run migrations
go run ./cmd/migrate up

# Rollback migrations
go run ./cmd/migrate down

# Seed database
go run ./cmd/migrate seed
```

### Backend

**Mac/Linux**:

```bash
# Install Air (if not already installed)
go install github.com/cosmtrek/air@latest

# Run with hot reload
air
```

**Windows**:

```bash
# Install Air (if not already installed)
go install github.com/cosmtrek/air@latest

# Run with hot reload (Git Bash or WSL)
air

# Alternative without Air
go run ./cmd/api
```

The API will be available at `http://localhost:8080` with the base path `/v1`.

### Frontend

All platforms:

```bash
cd web
bun run dev
```

The frontend will be available at `http://localhost:3000`.

For other frontend commands:

```bash
# Build for production
bun run build

# Preview production build
bun run preview

# Lint
bun run lint

# Type check
bun run typecheck
```

Note: Bun provides significantly faster installation and execution times compared to npm or yarn. It also includes built-in TypeScript support and other optimizations for modern web development.

## 🔧 Environment Configuration

### Using direnv (Mac/Linux recommended)

The `.envrc` file is used with direnv to automatically load environment variables when entering the project directory. Example configuration:

```bash
# Server
export ADDR=:8080
export EXTERNAL_URL=localhost:8080
export FRONTEND_URL=http://localhost:3000
export ENV=development

# Database
export DB_ADDR=postgres://postgres:postgres@localhost:5432/lk_tmpl?sslmode=disable
export DB_MAX_OPEN_CONNS=30
export DB_MAX_IDLE_CONNS=30
export DB_MAX_IDLE_TIME=15m

# Additional variables...
```

### Using .env file (Windows or alternative)

The same variables should be set in your `.env` file without the `export` keyword:

```env
ADDR=:8080
EXTERNAL_URL=localhost:8080
FRONTEND_URL=http://localhost:3000
ENV=development
# Additional variables...
```

## 🔍 Monitoring

- Redis Commander UI: `http://localhost:8081`
  - Mac/Linux: Access directly
  - Windows: If using WSL2, use the WSL2 IP address instead of localhost
- Metrics and debugging endpoints available through expvar

## 📚 API Documentation

The API documentation is automatically generated using Swagger. Once the server is running, you can access the Swagger UI at: `http://localhost:8080/v1/swagger/index.html#/`