be-service-qris/LAYOUT.md

# 📊 API Service Project Layout

## 🎯 Project Overview Dashboard

### 📈 Key Metrics
- **Language**: Go 1.24.4
- **Framework**: Gin 1.10.1
- **Database**: PostgreSQL with GORM
- **Authentication**: JWT + Keycloak
- **Documentation**: Swagger/OpenAPI 3.0
- **Container**: Docker & Docker Compose

### 🏗️ Architecture Overview
```
api-service/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── config/          # Config loader
│   ├── server/          # HTTP server setup + routes binding
│   ├── handler/         # HTTP handlers (controller layer)
│   ├── service/         # Business logic
│   ├── repository/      # DB access layer
│   ├── model/           # App/domain models
│   └── middleware/      # HTTP middlewares
├── pkg/                 # Reusable packages independent of business logic
│   ├── logger/
│   ├── utils/
│   └── validator/
├── scripts/             # Deployment & build automation
└── docs/                # Documentation (incl. swagger)
```

## 🚀 Development Environment Layout

### 📋 Prerequisites Setup
```bash
# Required tools
- Go 1.24.4+
- PostgreSQL 12+
- Docker & Docker Compose
- Keycloak Server (optional)

# Development tools
- Air (hot reload)
- Swag (Swagger docs)
- Make (build automation)
```

### 🔧 Configuration Files Layout
```
project-root/
├── .env                          # Environment variables
├── .air.toml                    # Air configuration
├── Makefile                     # Build commands
├── docker-compose.yml           # Docker services
├── Dockerfile                   # Container image
└── .goreleaser.yml             # Release configuration
```

## 📚 API Documentation Layout

### 🌐 Base URL Structure
```
http://localhost:8080/api/v1
```

### 📖 Endpoint Categories

#### 🔍 Health & Monitoring
- `GET /api/v1/health` - Health check
- `GET /api/v1/` - Hello world
- `GET /api/v1/metrics` - Application metrics

#### 🔐 Authentication Endpoints
- `POST /api/v1/auth/login` - User login
- `POST /api/v1/auth/register` - User registration
- `POST /api/v1/auth/refresh` - Token refresh
- `POST /api/v1/auth/logout` - User logout

#### 👤 User Management
- `GET /api/v1/users/profile` - Get user profile
- `PUT /api/v1/users/profile` - Update user profile
- `GET /api/v1/users` - List users (admin)
- `GET /api/v1/users/:id` - Get user by ID

#### 📦 Product Management
- `GET /api/v1/products` - List products
- `POST /api/v1/products` - Create product
- `GET /api/v1/products/:id` - Get product
- `PUT /api/v1/products/:id` - Update product
- `DELETE /api/v1/products/:id` - Delete product

#### 🔄 Real-time Features
- `GET /api/v1/websocket` - WebSocket connection
- `GET /api/v1/webservice` - Web service endpoint

### 📊 Swagger Documentation
- **Interactive UI**: http://localhost:8080/swagger/index.html
- **OpenAPI JSON**: http://localhost:8080/swagger/doc.json

## 🐳 Docker Deployment Layout

### 🏃 Development Environment
```bash
# Start all services
make docker-run

# Services included:
- PostgreSQL database
- API service with hot reload
- pgAdmin (database management)
```

### 🚀 Production Environment
```bash
# Build production image
docker build -t api-service:prod .

# Run production container
docker run -d \
  -p 8080:8080 \
  --env-file .env \
  --name api-service \
  api-service:prod
```

### 📦 Docker Compose Services
```yaml
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: api_service
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  api:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    environment:
      - BLUEPRINT_DB_HOST=postgres
    volumes:
      - .:/app
    command: air -c .air.toml
```

## 🛠️ Development Workflow Layout

### 🔄 Daily Development Cycle
```bash
# 1. Start development environment
make watch

# 2. Run tests
make test

# 3. Check code quality
make lint

# 4. Build for production
make build
```

### 🧪 Testing Strategy
```
tests/
├── unit/                       # Unit tests
├── integration/               # Integration tests
├── e2e/                       # End-to-end tests
└── fixtures/                  # Test data
```

### 📊 Monitoring & Logging
- **Health Check**: `/api/v1/health`
- **Metrics**: Prometheus metrics
- **Logging**: Structured JSON logs
- **Tracing**: Distributed tracing support

## 📁 File Structure Detailed Layout

### 📄 Configuration Files
```
.env.example                    # Environment template
config/
├── config.go                  # Configuration struct
├── config_test.go            # Configuration tests
└── validation.go             # Config validation
```

### 🗄️ Database Layout
```
database/
├── migrations/               # Database migrations
├── seeds/                    # Seed data
├── models/                   # GORM models
└── repositories/             # Data access layer
```

### 🎯 Handler Layout
```
handlers/
├── auth.go                   # Authentication handlers
├── user.go                   # User management handlers
├── product.go                # Product handlers
├── health.go                 # Health check handlers
└── middleware/               # HTTP middleware
    ├── auth.go              # JWT middleware
    ├── cors.go              # CORS middleware
    └── logger.go            # Logging middleware
```

### 🌐 Route Layout
```
routes/
├── v1/
│   ├── routes.go            # Route definitions
│   ├── auth_routes.go       # Auth routes
│   ├── user_routes.go       # User routes
│   └── product_routes.go    # Product routes
└── middleware.go            # Route middleware
```

## 🚀 Quick Start Commands

### 🏃 Development
```bash
# Clone and setup
git clone <repo-url>
cd api-service
cp .env.example .env
make docker-run

# Start development
make watch
```

### 🧪 Testing
```bash
# Run all tests
make all

# Run specific test
make test
make itest
```

### 🚀 Production
```bash
# Build and run
make build
./main.exe
```

## 📊 Performance Monitoring Layout

### 📈 Metrics Collection
- **Request Duration**: Track API response times
- **Error Rates**: Monitor error frequencies
- **Database Performance**: Query execution times
- **Memory Usage**: Application memory consumption

### 🔍 Health Checks
- **Database Connectivity**: PostgreSQL connection status
- **External Services**: Keycloak availability
- **Resource Usage**: CPU and memory utilization

## 🎯 Next Steps

1. **Setup Environment**: Copy `.env.example` to `.env`
2. **Start Database**: Run `make docker-run`
3. **Start Development**: Run `make watch`
4. **Test API**: Visit `http://localhost:8080/swagger/index.html`
5. **Run Tests**: Execute `make all`

## 📞 Support & Resources

- **Documentation**: Check `/docs` folder
- **API Testing**: Use Swagger UI at `/swagger/index.html`
- **Database**: Access pgAdmin at `http://localhost:5050`
- **Issues**: Create GitHub issues for bugs/features