README
¶
Hanzo 
Hanzo is a scalable DX platform designed to power next-gen internet companies.
Development
Getting started
You can use make to setup your development enviroment. Running:
$ make deps
...will download the Go App Engine SDK and unzip it into sdk/. When hacking on
things you'll want to ensure $GOROOT and $GOPATH point to their respective
directories inside sdk/.
You can source the provided .env file to set these variables, or use
autoenv to set them automatically
whenever you cd into the project directory.
Installing Go tools
You can install the common Go command line tools and configure gocode to work
with App Engine by running:
$ make tools
Development server
You can then use make serve to run the local development server and make test to run tests.
You can create a local config.json file containing configuration variables to
customize settings locally (for instance to disable the auto fixture loading).
This Makefile is used to build, test, and deploy a Go application running on Google App Engine, with dependencies managed through a combination of Go tools, Python SDK scripts, and Node.js for asset compilation. Here's a detailed breakdown of how it works and the general flow of operations:
Key Concepts
- Google App Engine: This is the platform used for deploying and managing the application.
- Go SDK and App Engine SDK: Go is the language used, and the App Engine SDK is required for running the app locally and deploying it to the cloud.
- Node.js Assets: JavaScript and CSS assets are handled using tools like
requisite,uglifyjs, andstylus. - Staging and Production Environments: Different configurations are used for deploying to development, staging, and production environments.
How the Makefile Works
1. System Variables
os: Detects the operating system (linuxordarwin) and converts it to lowercase for uniformity.pwd: Stores the current directory path.platform: Constructs the platform string based on the OS and architecture.sdk: Defines the specific App Engine SDK version to be used.sdk_path,goroot,gopath: Defines paths where the Go SDK and Go environment will be installed.
2. SDK Installation
The SDK is downloaded if it doesn’t exist. The following steps are performed:
-
.sdktarget: Downloads the App Engine SDK as a zip file and unzips it into a.sdkfolder.- It also performs extra setup (e.g., downloading
mtime_file_watcher.pyto monitor file changes).
- It also performs extra setup (e.g., downloading
-
.sdk/go: Creates a wrapper script to use thegoappcommand from the SDK. -
.sdk/gpm: Downloadsgpm, a Go dependency manager, to the.sdkdirectory.
3. Dependency Management
depstarget: Ensures all Go and JS/CSS dependencies are installed.deps-assets: Runsnpm updateto update JS/CSS dependencies.deps-go: Installs Go dependencies usinggpmfrom theGodepsfile.
4. Environment Configuration
-
The
gae_development,gae_staging,gae_production, andgae_sandboxvariables hold different configurations (YAML files) for deploying the app to various environments. -
project_env,project_id,gae_config: Select the appropriate environment based on Makefile options (production,sandbox, etc.).
5. Building the Project
-
buildtarget: Builds the Go modules listed undermodulesusinggoappfrom the App Engine SDK. -
installtarget: Installs the Go application and all dependencies.
6. Asset Compilation
-
JavaScript: Files are compiled and minified using
requisite,coffee, anduglifyjs.compile-js: Compiles CoffeeScript files and aggregates JavaScript withrequisite.compile-js-min: Minifies the compiled JavaScript files.
-
CSS: Files are compiled and autoprefixed using
stylusandautoprefixer.compile-css: Compiles Stylus files into CSS.compile-css-min: Minifies CSS and applies prefixes for cross-browser compatibility.
7. Testing and Linting
-
testtarget: Runs unit tests usingginkgo, with options for verbose and focused tests. -
benchtarget: Runs benchmark tests. -
test-watch: Watches the files and runs the tests on changes.
8. Running the Development Server
servetarget: Starts the App Engine development server using thedev_appserver.pycommand from the SDK.serve-clear-datastore: Clears the local datastore before starting the server.serve-public: Starts the server with a public-facing IP (0.0.0.0).
9. Deployment
-
deploytarget: Deploys the app to the selected environment (staging,production, etc.).rollbacktarget: Rolls back the deployment if needed.
-
deploy-apptarget: Updates the environment configuration and deploys each module usingappcfg.py(App Engine deployment tool). -
datastore-export,datastore-import: Commands for exporting and importing Google Cloud Datastore data.
Local Setup Steps
- Download Dependencies: Run
make depsto install all Go, JS, and CSS dependencies. - Build the Project: Use
make buildto build the Go application. - Run Development Server: Use
make serveto start the local App Engine server.
Staging and Production Setup
-
Staging: Run
make deployto deploy the app to the staging environment.- Make sure the environment variables are set to the correct staging project ID (
project_id).
- Make sure the environment variables are set to the correct staging project ID (
-
Production: Set the
production=1flag when callingmake deployto deploy to the production environment. -
Rolling Back: Use
make rollbackto revert to a previous version if needed.
Tools
Various Go tools are included in the tools target to assist with development (linting, formatting, etc.). These tools are installed using the goapp get and goapp install commands.
Documentation
¶
Overview ¶
Package commerce provides the main application framework for Hanzo Commerce.
Commerce is a multi-tenant e-commerce platform that runs as a standalone binary with embedded SQLite for per-user/org data and optional analytics via ClickHouse.
Architecture:
┌─────────────────────────────────────────────────────────────┐ │ Commerce App │ ├─────────────────────────────────────────────────────────────┤ │ HTTP Server (Gin) │ Hooks System │ Background Tasks │ ├─────────────────────────────────────────────────────────────┤ │ User SQLite │ Org SQLite │ Analytics (CH) │ │ + sqlite-vec │ + sqlite-vec │ (parallel queries) │ └─────────────────────────────────────────────────────────────┘
Index ¶
Constants ¶
const Version = "1.33.0"
Version is the current version of Commerce
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
// Root command
RootCmd *cobra.Command
// Database manager
DB *db.Manager
// Infrastructure manager
Infra *infra.Manager
// Hook system
Hooks *hooks.Registry
// Events client (sends to analytics-collector via HTTP)
Events *events.Client
// KMS client for secret management
KMS *kms.CachedClient
// HTTP router
Router *gin.Engine
// contains filtered or unexported fields
}
App is the main Commerce application
func NewWithConfig ¶
NewWithConfig creates a new Commerce application with the given configuration
type Config ¶
type Config struct {
// DataDir is the base directory for all data
DataDir string
// Dev enables development mode
Dev bool
// Secret for encryption and sessions
Secret string
// HTTP server address
HTTPAddr string
// HTTPS server address (optional)
HTTPSAddr string
// TLS certificate paths
TLSCert string
TLSKey string
// CORS allowed origins
AllowedOrigins []string
// Database configuration
Database db.Config
// Analytics collector endpoint (optional)
AnalyticsEndpoint string
// Analytics DSN (optional, for direct ClickHouse queries)
DatastoreDSN string
// Infrastructure configuration
Infra infra.Config
// Query timeout
QueryTimeout time.Duration
// KMS configuration for secret management
KMS kms.Config
// IAM configuration for hanzo.id JWT validation
IAM struct {
Enabled bool `json:"enabled"`
Issuer string `json:"issuer"`
ClientID string `json:"clientId"`
ClientSecret string `json:"clientSecret"`
} `json:"iam"`
}
Config holds application configuration
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ai provides AI-powered product recommendations and embeddings via Hanzo Cloud-Backend (Rust inference API) and Hanzo Cloud (Go API).
|
Package ai provides AI-powered product recommendations and embeddings via Hanzo Cloud-Backend (Rust inference API) and Hanzo Cloud (Go API). |
|
Package auth provides authentication utilities including IAM OAuth2/OIDC integration.
|
Package auth provides authentication utilities including IAM OAuth2/OIDC integration. |
|
billing
|
|
|
engine
Package engine provides core billing business logic: usage aggregation, payment collection, and subscription lifecycle management.
|
Package engine provides core billing business logic: usage aggregation, payment collection, and subscription lifecycle management. |
|
ledger
Package ledger implements a double-entry accounting ledger for the billing engine.
|
Package ledger implements a double-entry accounting ledger for the billing engine. |
|
workflows
Package workflows provides Temporal workflow definitions for automated recurring billing, subscription lifecycle management, and dunning retry logic.
|
Package workflows provides Temporal workflow definitions for automated recurring billing, subscription lifecycle management, and dunning retry logic. |
|
cmd
|
|
|
commerce
command
Package main is the entry point for the Commerce standalone binary.
|
Package main is the entry point for the Commerce standalone binary. |
|
development
command
|
|
|
production
command
|
|
|
sandbox
command
|
|
|
staging
command
|
|
|
test
command
|
|
|
cron
|
|
|
Package db provides a multi-layer database abstraction supporting: - User-level SQLite with sqlite-vec for personal data and vector search - Organization-level SQLite for shared tenant data - Hanzo Datastore (DATASTORE_URL) for deep analytics and parallel queries
|
Package db provides a multi-layer database abstraction supporting: - User-level SQLite with sqlite-vec for personal data and vector search - Organization-level SQLite for shared tenant data - Hanzo Datastore (DATASTORE_URL) for deep analytics and parallel queries |
|
Package delay provides a task queue abstraction for background job execution.
|
Package delay provides a task queue abstraction for background job execution. |
|
demo
|
|
|
Package events provides a thin HTTP client for the analytics collector.
|
Package events provides a thin HTTP client for the analytics collector. |
|
Package hooks provides event types for the hook system.
|
Package hooks provides event types for the hook system. |
|
Package infra provides unified infrastructure clients for Commerce.
|
Package infra provides unified infrastructure clients for Commerce. |
|
iammiddleware
Package iammiddleware provides Gin middleware for validating Hanzo IAM (hanzo.id) JWT tokens.
|
Package iammiddleware provides Gin middleware for validating Hanzo IAM (hanzo.id) JWT tokens. |
|
models
|
|
|
order
Package order provides the Order model with support for the new db.DB interface.
|
Package order provides the Order model with support for the new db.DB interface. |
|
product
Package product provides model initialization and query helpers for the v2 Product model.
|
Package product provides model initialization and query helpers for the v2 Product model. |
|
user/v2
Package user provides the User model using the new db.DB interface.
|
Package user provides the User model using the new db.DB interface. |
|
payment
|
|
|
providers
Package providers is a convenience package that imports all payment provider packages, ensuring they are available for the processor registry.
|
Package providers is a convenience package that imports all payment provider packages, ensuring they are available for the processor registry. |
|
router
Package router provides an intelligent multi-processor payment routing layer.
|
Package router provides an intelligent multi-processor payment routing layer. |
|
test
|
|
|
test-integration
|
|
|
thirdparty
|
|
|
kms
Package kms provides a thin HTTP client for KMS (Infisical-compatible) secret management.
|
Package kms provides a thin HTTP client for KMS (Infisical-compatible) secret management. |
|
paypal/ipn
Reference: https://developer.paypal.com/webapps/developer/docs/classic/ipn/integration-guide/IPNIntro/
|
Reference: https://developer.paypal.com/webapps/developer/docs/classic/ipn/integration-guide/IPNIntro/ |
|
util
|
|
|
cache
Package cache (memcache.go) provides a caching abstraction layer that can work with different backends (in-memory, Redis, etc.) to replace appengine/memcache.
|
Package cache (memcache.go) provides a caching abstraction layer that can work with different backends (in-memory, Redis, etc.) to replace appengine/memcache. |
|
nscontext
Package nscontext provides namespace context functionality that replaces google.golang.org/appengine.Namespace.
|
Package nscontext provides namespace context functionality that replaces google.golang.org/appengine.Namespace. |
|
search
Package search provides a search abstraction layer with pluggable backends.
|
Package search provides a search abstraction layer with pluggable backends. |
|
slug
Package slug transforms strings into a normalized form well suited for use in URLs.
|
Package slug transforms strings into a normalized form well suited for use in URLs. |