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

# 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

# Start all services
make docker-run

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

🚀 Production Environment

# 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

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

# 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

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

# Start development
make watch

🧪 Testing

# Run all tests
make all

# Run specific test
make test
make itest

🚀 Production

# 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