Aisphere Kernel Layout

Standalone full-feature service layout for github.com/aisphereio/kernel/cmd/kernel.

Default mode is full: config, logging, metrics, DB/cache/object storage wiring, audit, DTM, HTTP/gRPC transports, proto-first Todo CRUD, governance code generation examples, and deploy manifest generation.

Use MVP when you want the smallest runnable service skeleton:

kernel new skill-service --mvp

Use feature disable when you want to remove optional layout parts:

kernel new skill-service --disable iam
kernel new skill-service --disable gateway,dtmx

Use

go install github.com/aisphereio/kernel/cmd/kernel@latest
kernel new skill-service
cd skill-service
make tools
make api
make deploy
make proto-check
make test
make run

Included defaults

• Features: __KERNEL_FEATURES__
• Disabled features: __KERNEL_DISABLED_FEATURES__
• Profile: __KERNEL_PROFILE__
• DB: dbx with __KERNEL_DB_DRIVER__
• Cache: cachex with __KERNEL_CACHE_DRIVER__
• Object storage: objectstorex with __KERNEL_OBJECTSTORE_DRIVER__
• Authn: __KERNEL_AUTHN_PROVIDER__
• Authz: __KERNEL_AUTHZ_PROVIDER__
• Audit: auditx memory recorder by default
• Logging: logx console output for local development
• Metrics: shared metricsx.Manager, optional admin /metrics server
• DTM: optional dtmx.Manager
• Config: configx file source
• Transports: Kernel HTTP and gRPC servers with access log and metrics hooks
• API example: protobuf-first Todo CRUD with HTTP binding and optional governance annotations
• Deploy routes: Gateway API HTTPRoute manifests generated under deploy/generated/gateway
• Kernel version for generated Makefile tools: __KERNEL_VERSION__

External dependencies are present in configs/config.yaml, but DB, cache, object storage, authn, authz, and DTM are disabled by default so the service starts without local Postgres, Redis, Minio, Casdoor, SpiceDB, or DTM.

Layout

api/                 Protobuf APIs and kernel HTTP/gRPC bindings
cmd/server/          Application entrypoint, renamed to cmd/<service> by kernel new
configs/             Local config with IAM module defaults
deploy/generated/    Generated Gateway API HTTPRoute manifests split by exposure
internal/conf/        Config DTOs scanned by kernel
internal/server/      Kernel HTTP and gRPC server construction
internal/service/     Transport-facing Todo service
internal/biz/         Use cases, domain contracts, errorx errors
internal/data/        Repositories and Kernel resource initialization
.kernel/              Layout config/feature overlays consumed by kernel new

Module Usage Guides

Detailed usage guides for each Kernel module, with real code examples from production services:

Module	Guide	Key Package
Config	docs/modules/config.md	configx
Log	docs/modules/log.md	logx
Metrics	docs/modules/metrics.md	metricsx
Error	docs/modules/error.md	errorx
AuthN	docs/modules/authn.md	authn
AuthZ / Access	docs/modules/authz.md	authz / accessx
DTM	docs/modules/dtm.md	dtmx
Audit	docs/modules/audit.md	auditx

Deploy route generation

make deploy runs buf.gen.deploy.yaml, which calls protoc-gen-go-deploy and writes Kubernetes Gateway API route manifests from protobuf annotations:

PUBLIC                         -> deploy/generated/gateway/public/
AUTHENTICATED / AUTHORIZED     -> deploy/generated/gateway/authenticated/
INTERNAL / SYSTEM              -> deploy/generated/gateway/internal/

The generator reads both google.api.http and aisphere.access.v1.policy, so the generated route contains the HTTP method/path, upstream gRPC operation, exposure level, edge authn mode, and authz action/resource headers. This keeps route publication driven by proto contract rather than hand-written YAML.

Typical workflow:

make tools
make api
make deploy
make proto-check

Use local Kernel generator changes with:

make tools-local KERNEL_LOCAL=../kernel
make api
make deploy
make proto-check
make test

The layout must keep generated services on the Kernel path: proto contract -> generated request info/access/gateway/deploy metadata -> HTTP/gRPC middleware -> business service.

Local Kernel generator workflow

When the Kernel generator is being changed together with this layout, install tools from the local Kernel checkout instead of a released module version:

make tools-local KERNEL_LOCAL=../kernel
make api
make deploy
make proto-check
make test

Generate

make tools
make api
make deploy
make proto-check

Verify

make verify