Backend Template

Clean architecture based backend template in Go.

Makefile

Makefile requires installed dependecies:

• go
• docker-compose
• migrate

$ 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

$ ./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.

# 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

• apskel-pos Backend

License

This project is licensed under the MIT 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

   git clone <repository-url>
   cd apskel-pos-backend
   

2. Install dependencies

   go mod tidy
   

3. Set up database

   # Set your PostgreSQL database URL
   export DATABASE_URL="postgres://username:password@localhost:5432/apskel_pos?sslmode=disable"
   

4. Run migrations

   make migration-up
   

Usage

Development

# 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

# 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

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

Create User

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

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

apskel-pos-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 - HTTP router and URL matcher
• GORM - ORM for database operations
• PostgreSQL Driver - PostgreSQL database driver
• Validator - Struct validation
• 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.