meti-backend/README.md

<h1 align="center">
    <img height="80" width="160" src="./assets/gopher-icon.gif" alt="Go"><br>Backend Template
</h1>

> Clean architecture based backend template in Go.

## Makefile

Makefile requires installed dependecies:
* [go](https://go.dev/doc/install)
* [docker-compose](https://docs.docker.com/compose/reference)
* [migrate](https://github.com/golang-migrate/migrate)


```shell
$ make

Usage: make [command]

Commands:
 rename-project name={name}    Rename project
 
 build-http                    Build http server

 migration-create name={name}  Create migration
 migration-up                  Up migrations
 migration-down                Down last migration

 docker-up                     Up docker services
 docker-down                   Down docker services

 fmt                           Format source code
 test                          Run unit tests

```

## HTTP Server

```shell
$ ./bin/http-server --help

Usage: http-server

Flags:
  -h, --help               Show mycontext-sensitive help.
      --env-path=STRING    Path to env config file
```

**Configuration** is based on the environment variables. See [.env.template](.env).

```shell
# Expose env vars before and start server
$ ./bin/http-server

# Expose env vars from the file and start server
$ ./bin/http-server --env-path ./config/env/.env
```

## API Docs
* [eslogad Backend](https://eslogad-be.app-dev.altru.id/docs/index.html#/)

## License

This project is licensed under the [MIT License](https://github.com/pvarentsov/eslogad-be/blob/main/LICENSE).

# Apskel POS Backend

A SaaS Point of Sale (POS) Restaurant System backend built with clean architecture principles in Go.

## Architecture Overview

This application follows a clean architecture pattern with clear separation of concerns:

```
Handler → Service → Processor → Repository
```

### Layers

1. **Contract Package** (`internal/contract/`)
   - Request/Response DTOs for API communication
   - Contains JSON tags for serialization
   - Input validation tags

2. **Handler Layer** (`internal/handler/`)
   - HTTP request/response handling
   - Request validation using go-playground/validator
   - Route definitions and middleware
   - Transforms contracts to/from services

3. **Service Layer** (`internal/service/`)
   - Business logic orchestration
   - Calls processors and transformers
   - Coordinates between different business operations

4. **Processor Layer** (`internal/processor/`)
   - Complex business operations
   - Cross-repository transactions
   - Business rule enforcement
   - Handles operations like order creation with inventory updates

5. **Repository Layer** (`internal/repository/`)
   - Data access layer
   - Individual repository per entity
   - Database-specific operations
   - Uses entities for database models

6. **Supporting Packages**:
   - **Models** (`internal/models/`) - Pure business logic models (no database dependencies)
   - **Entities** (`internal/entities/`) - Database models with GORM tags
   - **Constants** (`internal/constants/`) - Type-safe enums and business constants
   - **Transformer** (`internal/transformer/`) - Contract ↔ Model conversions
   - **Mappers** (`internal/mappers/`) - Model ↔ Entity conversions

## Key Features

- **Clean Architecture**: Strict separation between business logic and infrastructure
- **Type Safety**: Constants package with validation helpers
- **Validation**: Comprehensive request validation using go-playground/validator
- **Error Handling**: Structured error responses with proper HTTP status codes
- **Database Independence**: Business logic never depends on database implementation
- **Testability**: Each layer can be tested independently

## API Endpoints

### Health Check
- `GET /api/v1/health` - Health check endpoint

### Organizations
- `POST /api/v1/organizations` - Create organization
- `GET /api/v1/organizations` - List organizations
- `GET /api/v1/organizations/{id}` - Get organization by ID
- `PUT /api/v1/organizations/{id}` - Update organization
- `DELETE /api/v1/organizations/{id}` - Delete organization

### Users
- `POST /api/v1/users` - Create user
- `GET /api/v1/users` - List users
- `GET /api/v1/users/{id}` - Get user by ID
- `PUT /api/v1/users/{id}` - Update user
- `DELETE /api/v1/users/{id}` - Delete user
- `PUT /api/v1/users/{id}/password` - Change password
- `PUT /api/v1/users/{id}/activate` - Activate user
- `PUT /api/v1/users/{id}/deactivate` - Deactivate user

### Orders
- `POST /api/v1/orders` - Create order with items
- `GET /api/v1/orders` - List orders
- `GET /api/v1/orders/{id}` - Get order by ID
- `GET /api/v1/orders/{id}?include_items=true` - Get order with items
- `PUT /api/v1/orders/{id}` - Update order
- `PUT /api/v1/orders/{id}/cancel` - Cancel order
- `PUT /api/v1/orders/{id}/complete` - Complete order
- `POST /api/v1/orders/{id}/items` - Add item to order

### Order Items
- `PUT /api/v1/order-items/{id}` - Update order item
- `DELETE /api/v1/order-items/{id}` - Remove order item

## Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd eslogad-backend
   ```

2. **Install dependencies**
   ```bash
   go mod tidy
   ```

3. **Set up database**
   ```bash
   # Set your PostgreSQL database URL
   export DATABASE_URL="postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"
   ```

4. **Run migrations**
   ```bash
   make migration-up
   ```

## Usage

### Development

```bash
# Start the server
go run cmd/server/main.go -port 8080 -db-url "postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"

# Or using environment variable
export DATABASE_URL="postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"
go run cmd/server/main.go -port 8080
```

### Using Make Commands

```bash
# Run the application
make start

# Format code
make fmt

# Run tests
make test

# Build for production
make build-http

# Docker operations
make docker-up
make docker-down

# Database migrations
make migration-create name=create_users_table
make migration-up
make migration-down
```

## Example API Usage

### Create Organization
```bash
curl -X POST http://localhost:8080/api/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Restaurant",
    "plan_type": "premium"
  }'
```

### Create User
```bash
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "uuid-here",
    "username": "john_doe",
    "email": "john@example.com",
    "password": "password123",
    "full_name": "John Doe",
    "role": "manager"
  }'
```

### Create Order with Items
```bash
curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "outlet_id": "uuid-here",
    "user_id": "uuid-here",
    "table_number": "A1",
    "order_type": "dine_in",
    "notes": "No onions",
    "order_items": [
      {
        "product_id": "uuid-here",
        "quantity": 2,
        "unit_price": 15.99
      }
    ]
  }'
```

## Project Structure

```
eslogad-backend/
├── cmd/
│   └── server/           # Application entry point
├── internal/
│   ├── app/             # Application wiring and dependency injection
│   ├── contract/        # API contracts (request/response DTOs)
│   ├── handler/         # HTTP handlers and routes
│   ├── service/         # Business logic orchestration
│   ├── processor/       # Complex business operations
│   ├── repository/      # Data access layer
│   ├── models/          # Pure business models
│   ├── entities/        # Database entities (GORM models)
│   ├── constants/       # Business constants and enums
│   ├── transformer/     # Contract ↔ Model transformations
│   └── mappers/         # Model ↔ Entity transformations
├── migrations/          # Database migrations
├── Makefile            # Build and development commands
├── go.mod              # Go module definition
└── README.md           # This file
```

## Dependencies

- **[Gorilla Mux](https://github.com/gorilla/mux)** - HTTP router and URL matcher
- **[GORM](https://gorm.io/)** - ORM for database operations
- **[PostgreSQL Driver](https://github.com/lib/pq)** - PostgreSQL database driver
- **[Validator](https://github.com/go-playground/validator)** - Struct validation
- **[UUID](https://github.com/google/uuid)** - UUID generation and parsing

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.