Backend Template
> 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
* [apskel-pos Backend](https://apskel-pos-be.app-dev.altru.id/docs/index.html#/)
## License
This project is licensed under the [MIT License](https://github.com/pvarentsov/apskel-pos-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
cd apskel-pos-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
```
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](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.