astraengine

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: MIT Imports: 6 Imported by: 0

README

AstraEngine Go

AstraEngine is a modular Go engine for building multi-platform bots, community systems and platform automation products.

It is not just a single bot template. AstraEngine is designed as a reusable runtime core: it provides the event loop, routing, middleware pipeline, platform abstraction, storage contracts, plugin lifecycle and integration boundaries that concrete bots and automation apps can be built on top of.

Purpose

AstraEngine is intended to be the foundation for products that need one shared backend logic layer across multiple platforms, such as Telegram, VK, Discord and future adapters.

The engine focuses on:

  • keeping business logic independent from platform SDKs;
  • providing a unified event and context model;
  • supporting plugins and reusable modules;
  • allowing different storage/cache implementations;
  • keeping platform adapters isolated from the core;
  • making it easier to build bots, admin tools and automation services on one architecture.

Install

go get github.com/andrewkydev/astraengine

Project layout

AstraEngine is designed as:

  • core — engine runtime, events, context, router, middleware and platform interfaces.
  • keyboard — unified keyboard and button builder for supported platforms.
  • payload — callback payload model, codec and helpers.
  • storage — database/session interfaces and basic memory implementation.
  • cache — cache interfaces and basic memory implementation.
  • admin — basic Admin HTTP API skeleton for engine management.
  • platform — Telegram/VK/Discord platform adapters.
  • plugin — plugin lifecycle, contracts and registry.
  • plugins — example built-in engine plugins.
  • examples — runnable examples built on top of AstraEngine.
  • docs/PROJECT_STRUCTURE.md — current module map and dependency boundaries.

Run examples

go mod tidy
go run ./examples/multi-platform

Environment:

cp .env.example .env
# fill TELEGRAM_TOKEN / VK_TOKEN / VK_GROUP_ID

Adapters use real SDKs:

  • Telegram: github.com/go-telegram/bot
  • VK: github.com/SevereCloud/vksdk/v3
  • Discord: github.com/bwmarrin/discordgo

For a complete setup, routing, FSM, attachments and Admin API walkthrough, see Getting Started.

Release readiness

CLI migrations

go run ./cmd/astraengine migrate up
go run ./cmd/astraengine migrate status
go run ./cmd/astraengine migrate down 1

Key env vars:

  • ASTRAENGINE_STORAGE_DRIVER=memory|postgres
  • ASTRAENGINE_DATABASE_URL=postgres://... — PostgreSQL connection string for the postgres driver.
  • ASTRAENGINE_PG_AUTO_SCHEMA=true — auto-create engine tables, for example system_users and astra_sessions.
  • ASTRAENGINE_MIGRATIONS_STORE=file|session — migrations state storage, default: file.
  • ASTRAENGINE_MIGRATIONS_FILE=.astraengine/migrations.json — file-based migrations state path.

Architecture rule

The engine core must not import Telegram/VK/Discord SDKs directly. Platform SDKs must live only inside adapters.

This keeps AstraEngine reusable: the same core can run with different platform adapters, while business logic and plugins remain platform-independent.

License

MIT. See LICENSE.

Documentation

Overview

Package astraengine exposes the public convenience API for building bots and automation apps on top of the AstraEngine runtime.

Most concrete implementations still live in subpackages such as core/app, platform/telegram, storage/postgres and plugin. The root package intentionally stays small so application code can start from astraengine.New while importing only the adapters and storage backends it actually needs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App 

type App = app.App

App is the main AstraEngine runtime type.

func New 

func New(name string) *App

New creates a new AstraEngine app runtime.

type Cache 

type Cache = cache.Cache

Cache is the engine cache contract.

type Group 

type Group = app.Group

Group is a route group with its own middleware chain.

type Handler 

type Handler = middleware.Handler

Handler processes a single normalized engine event.

type Middleware 

type Middleware = middleware.Middleware

Middleware wraps a Handler with cross-cutting behavior.

type Platform 

type Platform = platform.Platform

Platform is implemented by concrete adapters such as Telegram, VK and Discord.

type Plugin 

type Plugin = plugin.Plugin

Plugin is the engine plugin contract.

type Store 

type Store = storage.Store

Store is the engine storage contract.

Source Files

View all Source files

Directories

Path Synopsis
Package admin exposes convenient constructors for the extensible Admin API.
 Package admin exposes convenient constructors for the extensible Admin API.
api
Package api provides the extensible HTTP Admin API server.
 Package api provides the extensible HTTP Admin API server.
auth
Package auth defines Admin API authentication claims and verification.
 Package auth defines Admin API authentication claims and verification.
observability
Package observability records handler events, audits and basic runtime metrics.
 Package observability records handler events, audits and basic runtime metrics.
resources
Package resources defines declarative Admin API resource metadata.
 Package resources defines declarative Admin API resource metadata.
Package attachments provides a shared attachment model and lightweight helpers.
 Package attachments provides a shared attachment model and lightweight helpers.
Package cache defines the storage-independent cache contract used by the engine.
 Package cache defines the storage-independent cache contract used by the engine.
memory
Package memory implements an in-process cache for tests and single-instance bots.
 Package memory implements an in-process cache for tests and single-instance bots.
nop
Package nop implements a cache that never stores values.
 Package nop implements a cache that never stores values.
cmd
astrabot command
configs
runtime
Package runtime loads example and CLI configuration from environment variables.
 Package runtime loads example and CLI configuration from environment variables.
core
app
Package app wires platforms, routing, middleware, plugins and storage into a runtime.
 Package app wires platforms, routing, middleware, plugins and storage into a runtime.
botcmd
Package botcmd parses commands and provides alias-aware command middleware.
 Package botcmd parses commands and provides alias-aware command middleware.
capability
Package capability describes optional features supported by platform adapters.
 Package capability describes optional features supported by platform adapters.
context
Package context provides the handler context and cross-platform message helpers.
 Package context provides the handler context and cross-platform message helpers.
event
Package event contains the platform-neutral event model dispatched by AstraEngine.
 Package event contains the platform-neutral event model dispatched by AstraEngine.
fsm
Package fsm provides lightweight mode-and-step state injection.
 Package fsm provides lightweight mode-and-step state injection.
middleware
Package middleware defines handlers and composable event middleware.
 Package middleware defines handlers and composable event middleware.
platform
Package platform defines adapter contracts and platform-neutral outbound messages.
 Package platform defines adapter contracts and platform-neutral outbound messages.
ratelimit
Package ratelimit provides in-memory fixed-window limits and routing middleware.
 Package ratelimit provides in-memory fixed-window limits and routing middleware.
router
Package router dispatches commands, callbacks and text events to handlers.
 Package router dispatches commands, callbacks and text events to handlers.
examples
echo-bot command
multi-platform command
multi-platform/commands
Package input normalizes message, command and callback input for handlers.
 Package input normalizes message, command and callback input for handlers.
Package keyboard builds platform-neutral inline and reply keyboards.
 Package keyboard builds platform-neutral inline and reply keyboards.
Package mentions extracts common Telegram, VK and Discord mention formats.
 Package mentions extracts common Telegram, VK and Discord mention formats.
Package navigation provides callback-based pagination helpers.
 Package navigation provides callback-based pagination helpers.
Package payload encodes portable callback button data.
 Package payload encodes portable callback button data.
platform
discord
Package discord provides the experimental Discord adapter.
 Package discord provides the experimental Discord adapter.
telegram
Package telegram implements AstraEngine's Telegram Bot API adapter.
 Package telegram implements AstraEngine's Telegram Bot API adapter.
vk
Package vk implements AstraEngine's VK community bot adapter.
 Package vk implements AstraEngine's VK community bot adapter.
Package plugin implements compile-time plugins, settings and migration metadata.
 Package plugin implements compile-time plugins, settings and migration metadata.
plugins
auth
Package auth contains the baseline compile-time auth plugin.
 Package auth contains the baseline compile-time auth plugin.
broadcast
Package broadcast contains the baseline compile-time broadcast plugin.
 Package broadcast contains the baseline compile-time broadcast plugin.
roles
Package roles contains the baseline compile-time roles plugin.
 Package roles contains the baseline compile-time roles plugin.
Package runtime contains optional lifecycle, scheduling and worker helpers.
 Package runtime contains optional lifecycle, scheduling and worker helpers.
Package state provides persistent sessions and conversational FSM scenes.
 Package state provides persistent sessions and conversational FSM scenes.
Package storage defines persistent models and repository contracts.
 Package storage defines persistent models and repository contracts.
memory
Package memory implements process-local AstraEngine repositories.
 Package memory implements process-local AstraEngine repositories.
postgres
Package postgres implements AstraEngine repositories using pgx and PostgreSQL.
 Package postgres implements AstraEngine repositories using pgx and PostgreSQL.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.