Clean, scalable backend service engineered for modern e-commerce platforms in Go.
Learning Go has been a journey of exploring not only a new language, but also the community and philosophies that shape it. KomeCore began as a personal project to understand idiomatic Go, question architectural conventions, and discover where principles like Clean Architecture truly fit.
Open-sourced as a practical foundation for Go e-commerce backends, it reflects my ongoing exploration of building software that is not just well-structured, but ✨ purposeful.
Discover the engineering behind KomeCore in the Developer Architecture Tutorial
This project is open-source software licensed under the MIT License.
- Multi-Shop Catalog & Variants: Manage multiple independent shops, rich product options and variants, media image galleries, and search-friendly URLs.
- Cart & Multi-Shop Checkout: Customers can buy items from multiple shops in a single cart, with real-time calculations for shipping fees, discounts, and taxes.
- Discounts & Promotions Engine: Create promotional vouchers and coupons with rules like minimum spend requirements, discount limits, and customer usage quotas.
- Payments & Automated Reconciliation: Supports popular payment methods (bank transfers, QRIS, e-wallets) with automatic verification and instant order status updates.
- Fulfillment & Logistics: Accurate courier rate calculations, waybill generation, and complete parcel tracking from packing to final delivery.
- Product Reviews & Customer Wishlists: Verified buyer reviews and star ratings to build shopper trust, plus saved favorites and wishlist collections.
- Staff Administration & Analytics: Management portal for merchant staff with role permissions, sales reports, and insights into top-performing products.
- Dual-Dialect Database Support: Works seamlessly on both PostgreSQL and Microsoft SQL Server without changing any business logic.
- Flash-Sale Inventory Protection: Prevents overselling during high-traffic sales by holding stock during checkout and automatically restoring it if payment fails.
- Double-Charge Protection (Idempotency): Shields customers from duplicate orders and accidental double-charges caused by double-clicks or dropped internet connections.
- Guaranteed Event Delivery (Outbox): Ensures background tasks (like order confirmation emails and notifications) are never lost, even if a service temporarily restarts.
- Smart Catalog Search: Fast product discovery that understands word variations and ranks the most relevant products first.
- Customer & Staff Security: Safe authentication for shoppers and store admins, featuring Google one-click login, email verification codes, and secure sessions.
- Built-In Reliability & Safety: Protects the API from traffic abuse, hides sensitive internal errors from clients, and includes automated contract testing.
| Category | Technology | Tool / Library |
|---|---|---|
| Language & Runtime | Go | Go 1.25+ |
| HTTP Routing | Chi | github.com/go-chi/chi/v5 |
| Relational Database | PostgreSQL & SQL Server | pgx/v5, go-mssqldb |
| Distributed Caching | Redis | Redis 7+ (go-redis/v9) |
| Payment Processing | Midtrans | Core API |
| Object Storage | Cloud Storage | Supabase, GCS, S3 |
| Auth & Security | JWT & Cookies | golang-jwt/v5, bcrypt |
| Observability | Structured Logging | uber-go/zap |
Environment Setup: Configure
DB_TARGET(postgres·supabase·sqlserver),STORAGE_PROVIDER(supabase·gcs·noop), andREDIS_ENABLED(true·false) directly in.env. Database migrations live inmigrations/<dialect>/.
Spins up the application server, PostgreSQL 16 database container, and isolated network in one command.
docker compose up --build -d
curl http://localhost:7129/health
# {"status":"healthy"}Uses the Air daemon (.air.toml) for instant automatic recompilation whenever .go files are saved.
cp .env.example .env
make migrate && make seed
make dev # or run `air`Task runner shortcuts for database migrations, seeds, test execution, and server startup.
cp .env.example .env
make migrate # or: make migrate-supabase / make migrate-sqlserver
make seed
make run
make testRuns and tests the clean single-binary application daemon directly via the go CLI.
cp .env.example .env
go mod download
make migrate
go run ./cmd/komecore
go run ./cmd/komecore --version # outputs: komecore v1.0.0
go test -v -count=1 ./...KomeCore provides 100% verified testing collections covering all 95 API endpoints across 14 business domains:
| Client / Format | Source File / Directory | Description & Instructions |
|---|---|---|
| Postman | api/postman_collection.json |
Import directly into Postman Desktop or Web. Complete with collection variables and pre-configured request payloads. |
| VS Code REST Client | api/komecore.http |
Open in VS Code and click Send Request directly in your editor. Zero external desktop client required. |
| Bruno | api/bruno/ |
Open the folder in the Bruno API Client. Fully offline, Git-friendly .bru request files. |
| OpenAPI / Swagger | api/openapi.yaml & api/openapi-v1.0.0.yaml |
Import into Swagger UI, Redoc, or Insomnia. Full JSON schemas for all request/response DTOs and envelopes. |
For detailed steps on setting up environment variables, auth tokens, and testing order flows, see the API README.
komecore/
├── cmd/komecore/ # App entry point
├── internal/
│ ├── apperror/ # Error types and codes
│ ├── authctx/ # Authenticated actor context
│ ├── bootstrap/ # Dependency wiring and lifecycle
│ ├── config/ # Environment configuration
│ ├── httpx/ # HTTP utilities and middleware
│ ├── infra/ # External infrastructure adapters
│ └── modules/ # Business domains
│ └── <module>/ # Domain logic
│ ├── <module>http/ # HTTP handlers and DTOs
│ └── <module>persistence/ # Database operations
├── api/ # API specs and collections
├── docs/ # Architecture and guides
├── migrations/ # Database migrations
├── pkg/ # Reusable utilities
└── test/ # Architecture and integration tests
Explore the technical guides to understand the internal mechanics:
- Developer Architecture Tutorial: Deep walkthrough explaining module architecture, the full request journey, and five complex distributed lifecycles (multi-shop checkout, atomic stock reservation, webhook settlement, transactional outbox, and 24h Redis idempotency).
- API Documentation & Collections: Complete guide to all 95 endpoints with ready-to-use Postman collections, Bruno workspace, VS Code REST Client files, and frozen OpenAPI 3.0 specifications.