init
This commit is contained in:
aditya.siregar
@@ -57,8 +57,254 @@ $ ./bin/http-server --env-path ./config/env/.env
|
||||
```
|
||||
|
||||
## API Docs
|
||||
* [enaklo-pos Backend](https://enaklo-pos-be.app-dev.altru.id/docs/index.html#/)
|
||||
* [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/enaklo-pos-be/blob/main/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 <repository-url>
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user