A robust order management system built with Go, featuring automated order lifecycle tracking, Redis caching, and JWT-based authentication.

• 🔐 JWT Authentication - Secure user authentication with role-based access control
• 📦 Order Lifecycle Management - Automated status progression with background tracking
• 🚀 Redis Caching - High-performance order caching with automatic invalidation
• 👑 Admin Dashboard - Administrative functions for order management
• 🔄 Concurrent Processing - Safe handling of concurrent order operations
• 🐳 Docker Support - Full containerization with Docker Compose

Trachios/ ├── cmd/server/ # Application entry point ├── internal/ │ ├── api/ │ │ ├── handler/ # HTTP request handlers │ │ └── middleware/ # Authentication & authorization middleware │ ├── config/ # Configuration management │ ├── domain/ # Business entities (User, Order) │ ├── repository/ # Data access layer │ ├── service/ # Business logic layer │ └── worker/ # Background processing ├── pkg/util/ # Shared utilities ├── test/ # Integration tests └── configs/ # Configuration files 

• Go 1.24+
• Docker & Docker Compose
• PostgreSQL 15+
• Redis 7+

git clone https://github.com/varun-karmikanda/trachios.git cd trachios

cp .env.example .env cp configs/config.yaml.example configs/config.yaml

Edit .env with your configuration:

SERVER_PORT=8080 POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_USER=trachios_user POSTGRES_PASSWORD=your_secure_password POSTGRES_DB=trachios_db REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD= JWT_SECRET=your_jwt_secret_key_here ADMIN_EMAIL=admin@example.com ADMIN_PASSWORD=admin_secure_password

docker-compose up -d

# Start PostgreSQL and Redis docker-compose up -d postgres redis # Run migrations (if using golang-migrate) migrate -path internal/repository/migrations -database "postgres://user:password@localhost:5432/db?sslmode=disable" up # Start the server go run cmd/server/main.go

http://localhost:8080/api/v1 

Check if the server is running.

curl -X GET http://localhost:8080/api/v1/health

Register a new user account.

curl -X POST http://localhost:8080/api/v1/register \ -H "Content-Type: application/json" \ -d '{  "name": "John Doe",  "email": "john@example.com",  "password": "securepassword123"  }'

Authenticate and get JWT token.

curl -X POST http://localhost:8080/api/v1/login \ -H "Content-Type: application/json" \ -d '{  "email": "john@example.com",  "password": "securepassword123"  }'

Save the returned token for authenticated requests:

export TOKEN="your_jwt_token_here"

Get the currently authenticated user's information.

curl -X GET http://localhost:8080/api/v1/user \ -H "Authorization: Bearer $TOKEN"

Create a new order (authenticated users only).

curl -X POST http://localhost:8080/api/v1/orders \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{  "item_description": "MacBook Pro 16-inch M3"  }'

Retrieve all orders for the authenticated user.

curl -X GET http://localhost:8080/api/v1/my-orders \ -H "Authorization: Bearer $TOKEN"

Retrieve a specific order by ID (user can only access their own orders, admins can access any).

curl -X GET http://localhost:8080/api/v1/orders/1 \ -H "Authorization: Bearer $TOKEN"

Cancel an order (user can only cancel their own orders).

curl -X PUT http://localhost:8080/api/v1/orders/1/cancel \ -H "Authorization: Bearer $TOKEN"

These endpoints require admin privileges.

Retrieve all orders in the system (admin only).

curl -X GET http://localhost:8080/api/v1/orders \ -H "Authorization: Bearer $ADMIN_TOKEN"

Manually update an order's status (admin only).

curl -X PUT http://localhost:8080/api/v1/orders/1/status \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{  "status": "delivered"  }'

Valid status values:

• created
• dispatched
• in_transit
• delivered
• cancelled

# First, login as admin to get admin token curl -X POST http://localhost:8080/api/v1/login \ -H "Content-Type: application/json" \ -d '{  "email": "admin@example.com",  "password": "admin_password"  }' # Save admin token export ADMIN_TOKEN="your_admin_jwt_token_here"

# 1. Register a new user curl -X POST http://localhost:8080/api/v1/register \ -H "Content-Type: application/json" \ -d '{"name": "Test User", "email": "test@example.com", "password": "password123"}' # 2. Login and get token RESPONSE=$(curl -s -X POST http://localhost:8080/api/v1/login \  -H "Content-Type: application/json" \  -d '{"email": "test@example.com", "password": "password123"}') TOKEN=$(echo $RESPONSE | jq -r '.token') # 3. Create an order curl -X POST http://localhost:8080/api/v1/orders \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"item_description": "iPhone 15 Pro"}' # 4. Check my orders curl -X GET http://localhost:8080/api/v1/my-orders \ -H "Authorization: Bearer $TOKEN" # 5. Get specific order (replace 1 with actual order ID) curl -X GET http://localhost:8080/api/v1/orders/1 \ -H "Authorization: Bearer $TOKEN"

Orders automatically progress through the following statuses:

1. created → 15 seconds (dev) → dispatched
2. dispatched → 15 seconds (dev) → in_transit
3. in_transit → 15 seconds (dev) → delivered

• Automatic Progression: Orders move through lifecycle stages automatically every 15 seconds (configured for development)
• Admin Override: Admins can manually update order status at any time using the /orders/{orderID}/status endpoint
• Cancellation: Users can cancel orders (except delivered/cancelled orders) using the /orders/{orderID}/cancel endpoint
• Background Tracking: Each order has its own goroutine managing lifecycle progression

You can monitor an order's automatic progression:

# Create order and note the returned ID ORDER_ID=$(curl -s -X POST http://localhost:8080/api/v1/orders \  -H "Authorization: Bearer $TOKEN" \  -H "Content-Type: application/json" \  -d '{"item_description": "Test Item"}' | jq -r '.id') # Check status every 16 seconds to see progression (dev timing) for i in {1..4}; do echo "Check $i:" curl -s -X GET http://localhost:8080/api/v1/orders/$ORDER_ID \ -H "Authorization: Bearer $TOKEN" | jq '.status' sleep 16 done

The application uses both environment variables and YAML configuration:

# configs/config.yaml server: port: 8080 postgres: host: "localhost" port: 5432 user: "trachios_user" password: "secure_password" dbname: "trachios_db" sslmode: "disable" redis: host: "localhost" port: 6379 password: "" db: 0 jwt: secret: "your-jwt-secret-here" admin: email: "admin@example.com" password: "admin_password"

CREATE TABLE users ( id BIGSERIAL PRIMARY KEY, name VARCHAR(255) NOT NULL, email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, role user_role NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); CREATE TYPE user_role AS ENUM ('customer', 'admin');

CREATE TABLE orders ( id BIGSERIAL PRIMARY KEY, customer_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE, item_description TEXT NOT NULL, status order_status NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); CREATE TYPE order_status AS ENUM ( 'created', 'dispatched', 'in_transit', 'delivered', 'cancelled' );

The project includes comprehensive integration tests that validate all functionality:

# Make sure the server is running first go run cmd/server/main.go # In another terminal, run tests go test -v ./test/...

The tests validate:

• ✅ User authentication (registration, login, JWT validation)
• ✅ Order creation and retrieval
• ✅ Automated status progression (waits 16 seconds for progression)
• ✅ Order cancellation functionality
• ✅ Admin-only operations and access control
• ✅ Concurrent order processing (creates 5 orders simultaneously)

The api_lifecycle_test.go includes:

• Authentication testing (user and admin)
• Order creation and management
• Status progression testing with 16-second wait
• Order cancellation validation
• Admin function testing
• Concurrent operation testing

• cmd/server/main.go: Application entry point and routing
• internal/service/order_service.go: Core business logic with Redis caching
• internal/api/handler/: HTTP request handlers
• internal/repository/: Data access layer
• pkg/util/: Shared utilities (password hashing, JSON responses)

The OrderService handles:

• Order lifecycle management with background goroutines
• Redis caching with automatic invalidation (5-minute cache duration)
• Concurrent order tracking with thread-safe operations
• Admin override capabilities with goroutine management

The AuthMiddleware provides:

• JWT token validation
• User context injection
• Role-based access control (customer/admin)

• UserRepository: User CRUD operations with admin seeding
• OrderRepository: Order data management
• Database connections: PostgreSQL and Redis clients with connection pooling

1. Add new domain entity in internal/domain/
2. Create repository in internal/repository/
3. Implement service logic in internal/service/
4. Add HTTP handlers in internal/api/handler/
5. Update routes in cmd/server/main.go

# Build and deploy with Docker Compose docker-compose up -d # Or build manually docker build -t trachios:latest . docker run -p 8080:8080 trachios:latest

Create environment-specific configuration files:

• configs/config.dev.yaml
• configs/config.prod.yaml
• configs/config.test.yaml

• Cache Duration: 5 minutes per order (configured in order_service.go)
• Cache Keys: order:{id} format
• Invalidation: Automatic on status updates and admin overrides
• Hit/Miss Logging: Enabled for monitoring cache performance

• Connection pooling configured in postgres.go
• Max idle connections: 25
• Max open connections: 25
• Connection max lifetime: 5 minutes
• Prepared statements for better performance

The application provides structured logging for:

• Order lifecycle events and goroutine management
• Cache operations (hits/misses) for performance monitoring
• Authentication attempts and failures
• Admin overrides and goroutine stopping/starting

• Password Hashing: Uses bcrypt with default cost (configured in password.go)
• JWT Security: Tokens expire in 72 hours (configured in user_handler.go)
• SQL Injection: Protected with parameterized queries throughout repositories
• Authorization: Role-based access control with middleware
• Admin Seeding: Automatic admin user creation on first startup

The API returns appropriate HTTP status codes:

• 200 - Success
• 201 - Created (registration, order creation)
• 400 - Bad Request (validation errors, invalid order states)
• 401 - Unauthorized (invalid/missing token)
• 403 - Forbidden (insufficient privileges)
• 404 - Not Found (user/order not found)
• 500 - Internal Server Error

Error responses follow this format:

{ "error": "Error message description" }

1. Database Connection Failed

   # Check PostgreSQL is running docker-compose ps postgres # Check connection psql -h localhost -p 5432 -U username -d database

2. Redis Connection Failed

   # Check Redis is running docker-compose ps redis # Test connection redis-cli -h localhost -p 6379 ping

3. JWT Token Issues

   • Ensure JWT_SECRET is set and consistent
   • Check token expiration (72 hours default)
   • Verify Authorization header format: Bearer <token>

4. Order Status Not Progressing

   • Check server logs for goroutine errors
   • Verify order is not cancelled or delivered
   • Confirm background tracking is active

5. Admin Access Issues

   • Verify admin credentials in .env file
   • Check admin user was created during server startup
   • Ensure admin token is used for admin endpoints

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow Go best practices and conventions
• Add tests for new functionality
• Update documentation for API changes
• Use meaningful commit messages
• Test all endpoints with curl before submitting

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

For support and questions:

• Create an issue on GitHub
• Check the troubleshooting section
• Review the test cases for usage examples
• Test endpoints using the provided curl commands

Trachios - Efficient Order Management for Modern Applications