AI-native marketplace for product discovery, shopping, and commerce operations
built by Vesta Vision as a hackathon project
BTKCommerce is a server-rendered Go marketplace built for a hackathon setting where judges need to evaluate both product experience and engineering depth quickly. It combines a working storefront, multimodal product discovery, shopping assistant flows, seller/admin workspaces, and AI-provider integration points that degrade gracefully when credentials are not available.
The project is designed to show how an AI-native commerce platform can be assembled with a pragmatic stack: Go, templ, HTMX, Tailwind CSS v4, Docker Compose, source-owned UI primitives, and mock-safe AI infrastructure.
BTKCommerce can be evaluated locally without cloud credentials. AI-powered routes include mock or rule-based fallbacks, so product discovery, visual flows, and assistant surfaces stay usable even when Gemini/Vertex credentials have not been configured.
Recommended review path:
-
Start the stack:
docker compose up --build
-
Open the app:
-
Explore the main surfaces:
- Storefront product discovery, product pages, cart, checkout, and orders.
- Storefront assistant at
/assistant. - Seller workspace and seller assistant at
/sellerand/seller/assistant. - Admin workspace and admin assistant at
/adminand/admin/assistant. - AI credential management at
/admin/ai-credentials.
Useful review documents:
- Marketplace flows: storefront browsing, product detail views, cart and order-oriented pages, seller/admin shells, and operational workspace surfaces.
- Shopping assistants: storefront, seller, and admin assistant surfaces with surface-specific context and behavior.
- Multimodal discovery: visual search and preview flows with graceful mock fallback when live AI credentials are missing.
- Operational AI: seller order assistance, approval-first seller actions, admin health summaries, AI log visibility, and search sync support.
- Credential management: provider keys are managed through the admin UI, encrypted at rest, and hot-reloaded for Gemini-backed features.
- Source-owned UI system: local
templuiprimitives, strict template boundaries, Tailwind CSS v4 theme, and i18n-ready labels. - Docker-first runtime: app, worker, PostgreSQL, Redis, Typesense, Qdrant, NATS, and MinIO are wired through Compose.
- AI-native search and product discovery.
- Product detail pages with preview-oriented commerce flows.
- Cart, checkout, order success, and order support surfaces.
- Conversational shopping assistant with contextual launch points.
- Visual product search, room placement, and try-on style preview flows.
- Gemini/Vertex-compatible provider structure with mock fallback.
- Rule-based degradation for search and vision flows when credentials are unavailable.
- Embedding and visual-analysis seed artifact workflows for richer local demos.
- Assistant memory and retrieval integrations backed by Qdrant when available.
- AI operation logs and provider health visibility.
- Seller workspace for listings, orders, queue summaries, and fulfillment-oriented support.
- Seller assistant with approval-first proposals for shipping, delivery, and cancellation actions.
- Admin workspace for search sync health, moderation-style review, AI log inspection, and operational summaries.
- Secure AI credential management through
/admin/ai-credentials.
- Go standard library HTTP with Chi router.
- Type-safe HTML templates via
templ. - Progressive interactivity via HTMX.
- Tailwind CSS v4 with a custom warm/orange theme.
- Source-owned
templuiprimitives undercomponents/. - Clean viewmodel boundary between domain services and UI templates.
- Turkish and English i18n support with zero hardcoded UI text in
.templfiles.
| Layer | Technology |
|---|---|
| Language | Go 1.26+ |
| HTTP Router | Chi |
| Templates | templ |
| Interactivity | HTMX |
| Styling | Tailwind CSS v4 |
| Build Tool | Vite |
| Database | PostgreSQL |
| Cache | Redis |
| Search | Typesense |
| Vector Store | Qdrant |
| Events | NATS JetStream |
| Object Storage | MinIO / filesystem adapter |
| AI Provider | Gemini / Vertex-compatible providers with mock fallback |
git clone https://github.com/vestavision/btkcommerce.git
cd btkcommerce
docker compose up --buildNo AI credentials are required for evaluation. When credentials are missing, AI-backed routes use mock or rule-based fallbacks instead of failing.
| Service | URL |
|---|---|
| App with templ reload | http://localhost:7331 |
| Vite HMR | http://localhost:5173 |
| Typesense | http://localhost:28108 |
| Qdrant | http://localhost:26333 |
| MinIO Console | http://localhost:29001 |
| PostgreSQL | localhost:25432 |
| Redis | localhost:26379 |
| NATS | localhost:24222 |
docker build --target production -t btkcommerce:latest .
docker run --rm -p 8090:8090 btkcommerce:latestSeed images, visual analysis, and embeddings can be prepared with local Ollama and imported through the Docker Compose ops container. The marketplace seed step downloads curated product images into MinIO under seed/demo/products/...; imported Ollama artifacts are authoritative for seed products, so search sync will not retry Gemini image analysis or live Gemini embedding for those products.
Full runbooks:
Happy path:
ollama pull nomic-embed-text
ollama pull qwen3-vl:4b
go run ./cmd/ops seed images validate \
--manifest assets/seed/image-packs.json \
--check-remote=true
go run ./cmd/ops seed visuals generate \
--namespace demo \
--seed 20260517 \
--products 25 \
--image-manifest assets/seed/image-packs.json \
--output /tmp/btkcommerce-seed-visuals.jsonl.gz \
--ollama-url http://127.0.0.1:11434 \
--model qwen3-vl:4b \
--ollama-timeout 5m
go run ./cmd/ops embeddings generate \
--input assets/seed/products.json \
--output /tmp/btkcommerce-seed-embeddings.jsonl.gz \
--ollama-url http://127.0.0.1:11434 \
--model nomic-embed-text
docker compose up -d postgres typesense qdrant nats minio minio-init
make ops-seed-marketplace
make ops-seed-visuals-import ARTIFACTS_DIR=/tmp VISUAL_OUTPUT=/tmp/btkcommerce-seed-visuals.jsonl.gz SEED_NAMESPACE=demo
make ops-embeddings-import ARTIFACTS_DIR=/tmp EMBED_FILE=/tmp/btkcommerce-seed-embeddings.jsonl.gz
docker compose up -d worker-devWindows PowerShell wrappers:
./scripts/visuals/generate.ps1 -ArtifactFile C:\Temp\btkcommerce-seed-visuals.jsonl.gz -OllamaUrl http://127.0.0.1:11434 -Model qwen3-vl:4b
./scripts/visuals/import.ps1 -ArtifactFile C:\Temp\btkcommerce-seed-visuals.jsonl.gzBTKCommerce follows a clean architecture with domain-driven service interfaces and strict UI separation:
Storefront / Seller / Admin
|
UI Layer: pages, compositions, fragments, layouts
|
ViewModel Boundary: internal/ui/viewmodel
|
Domain Layer: internal/domain/*
|
Platform Layer: server, runtime, config, i18n
|
Infrastructure: database, search, vector, object storage, providers
Important boundaries:
- UI templates consume viewmodels; they do not import domain packages.
- HTMX fragment endpoints return fragment templates, not full pages.
- Source-owned primitives under
components/are used instead of raw form controls. - AI routes must work without provider credentials through mock or rule-based fallbacks.
- Production-targeted object storage stays behind the
ObjectStoragecontract.
For more detail, see:
btkcommerce/
├── cmd/ # web, worker, ops, templsync entrypoints
├── components/ # source-owned UI primitives
├── internal/
│ ├── domain/ # business interfaces and mock/db-backed services
│ ├── infra/ # storage, providers, queues, search, credentials
│ ├── platform/ # runtime, server, config, i18n
│ └── ui/ # templ pages, fragments, compositions, viewmodels
├── assets/ # images, seed data, local assets
├── db/ # migrations
├── docs/ # architecture, operations, assistant notes
├── scripts/ # Docker and ops helper scripts
├── compose.yml # Docker Compose stack
└── Dockerfile # multi-stage production build
BTKCommerce is i18n-ready with zero hardcoded UI text in .templ files.
- Default locale: Turkish (
tr) - Supported locales: Turkish (
tr) and English (en) - Resolution order:
?lang=query param,langcookie,Accept-Languageheader, then defaulttr
Translations live in internal/platform/i18n/. Labels are defined in internal/ui/viewmodel and resolved per request in the server layer.
Shipped or implemented for the hackathon demo:
- Source-owned UI primitives and marketplace compositions.
- Mock-backed storefront, seller, and admin flows.
- Storefront, seller, and admin assistant surfaces.
- Visual search and preview-oriented AI flows with fallback behavior.
- AI credential management through the admin UI.
- Search, vector, queue, cache, and object-storage integration points.
- Offline seed artifact tooling for images, visuals, and embeddings.
Next areas:
- Payments and fulfillment hardening.
- Richer approval-backed admin mutations.
- Production object storage integration beyond the current filesystem/dev adapter path.
- More assistant intelligence from persisted feedback and operational metadata.
- Expanded collaboration, sharing, and export workflows.
Credential secrets are never passed through environment variables. They are encrypted with an ML-KEM-768 + AES-GCM envelope and stored in data/credentials/records.json. Manage them through the admin UI at /admin/ai-credentials or the ops CLI.
If credentials are missing, Gemini-backed features degrade through mock or rule-based behavior. Vision and search routes must not fail simply because provider credentials are unavailable.
For vulnerability disclosures, see SECURITY.md.
We welcome contributions. Please read CONTRIBUTING.md for setup instructions, coding conventions, and the pull request workflow.
- Report bugs through GitHub Issues
- Propose features through GitHub Discussions
- Security issues: see SECURITY.md
BTKCommerce is licensed under the Apache License 2.0.
Copyright 2024-2026 Vesta Vision
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Built with care by Vesta Vision