website·Indexed 30 days ago
https://elysia-admin.topA full-stack admin management solution based on ElysiaJS and Vue 3. The documentation covers architectural design, database operations with DrizzleORM and PostgreSQL, Redis caching, BullMQ queue systems, and deployment strategies via Docker or PM2. It includes guides on payment integration (Alipay, WeChat, PayPal), file storage with S3/RustFS, and AI-assisted development workflows.
Elysia Admin uses BullMQ Sandboxed Processors to handle asynchronous tasks (e.g., emails, order timeouts, batch exports) without blocking the HTTP event loop.
Process Isolation Layers:
Key Directory Structure:
infrastructure/queue/queues/*/queue.ts: Queue registration (loaded by main process).infrastructure/queue/queues/*/worker.ts: Worker registration (loaded by worker process).infrastructure/queue/queues/*/processor.ts: Child process entry point (built to dist/processors/).worker-sandbox/*-tasks.ts: Business function registration; can import modules.runtime/app.ts / runtime/worker.ts: Aggregated imports for all queues.PUT request to the object storage provider. This reduces backend bandwidth usage, supports larger files, and improves scalability. The system supports any S3-compatible storage service.To effectively build business modules with AI, Elysia Admin utilizes two complementary MCP servers to provide 'source facts' and 'runtime facts'.
handle.ts access PostgreSQL via @/core/database/repository. This layer wraps Drizzle ORM to provide high-level functions for common database tasks. When passing ctx (AppContext) to these functions, the system automatically populates createBy and updateBy fields if they exist in the schema. For custom data without context, set ctx to null.// Common repository functions from @/core/database/repository
InsertOne: Insert record, no return
InsertOneAndRes: Insert record, returns new record
InsertMany: Batch insert
FindOneByKey: Find single record by primary key
FindAll: Find all records (no pagination)
FindPage: Paginated query
FindAllWithJoin: Join query (no pagination)
FindPageWithJoin: Paginated join query
UpdateByKey: Update by primary key, no return
UpdateByKeyAndRes: Update by primary key, returns record
SoftDeleteByKeys: Soft delete (sets delFlag = true)
HardDelete: Hard delete by where condition
HardDeleteByKeys: Hard delete by primary key array
CreateQueryBuilder: Chainable where condition builderThe Elysia Admin backend is built with the Elysia.js framework and follows a layered architecture. The project is organized into the following primary directories:
database/: Contains database definitions, including business table schemas, initialization SQL, and common field definitions in base-schema.ts.src/config/: Environment configurations.src/constants/: Enums and dictionary constants.src/core/database/: Core infrastructure for PostgreSQL, Redis, Repositories, and transaction management.src/infrastructure/: External integrations including:clients/: Third-party clients (e.g., payment providers like Alipay, PayPal, WeChat, Crypto).cron/: In-process scheduled tasks.queue/: BullMQ queue management (e.g., flow-buffer, system-cron, trade-order).storage/: Object storage providers (e.g., COS, Kodo, OSS, RustFS).src/middleware/guards/: Authentication, authorization, IP blacklisting, and rate limiting.src/modules/: Business logic modules (e.g., auth, business-merchant, system-user, system-role). Note that dev-sql is only registered in development environments.src/worker-sandbox/: Registration for queue sandbox tasks.src/shared/: Shared utility functions.src/types/: Type definitions.src/app.ts & src/index.ts: Application and main entry points.├── database # 数据库定义
│ ├── schema # 业务表 Schema
│ ├── sql # 初始化 SQL、模块 handoff SQL
│ └── base-schema.ts # 公共字段定义
├── src
│ ├── config # 环境配置
│ ├── constants # 枚举与字典常量
│ ├── core # 核心基础设施
│ │ └── database # PG / Redis / Repository / 事务
│ ├── infrastructure # 外部集成
│ │ ├── clients # 第三方客户端
│ │ ├── cron # 进程内定时任务
│ │ ├── queue # BullMQ 队列
│ │ └── storage # 对象存储
│ ├── middleware # 中间件
│ │ └── guards # 认证 / 权限 / IP 黑名单 / 限流
│ ├── modules # 业务模块
│ ├── worker-sandbox # 队列沙箱任务注册
│ ├── shared # 共享工具函数
│ ├── types # 类型定义
│ ├── app.ts # 应用入口
│ └── index.ts # 总入口AI_CODE_EXAMPLES.md before submitting requirements.# elysia-admin Constraint Summary
- Architecture: Decoupled Vue3 + Elysia/Bun; Modules at server/src/modules/{group}-{name}/ (dto/handle/route/task)
- Templates: Follow AI_CODE_EXAMPLES.md; handles must NOT use try/catch (use BaseResultData.fail(4xx, msg) for business errors)
- Frontend: Use useTable + ArtSearchBar + ArtForm; art-full-height; useDictStore for business enums
- Fullstack Flow: Schema → Code → server/database/sql/{module}-init.sql; request permission before changing tables
- SQL Execution: AI only generates the .sql file; developer must execute it manually. AI is forbidden from using scripts/psql/MCP to run SQL
- Database Queries: Use Postgres MCP for read-only access to dict/menu; do NOT read server/database/sql/pg.sql (outdated backup)
- Schema Push: AI may ask to run `db:push` after schema changes; if agreed, preference is saved to .ai/dev-preferences.local.md
- Output: Follow the delivery format in AI_MODULE_WORKFLOWElysia Admin uses the following technology stack for its data layer:
postgres (lightweight PG driver)bun run db:push or db:pull)BullMQ for queue management and scheduled tasks. To avoid circular dependencies and coupling, sandbox tasks are centrally registered, ensuring the infrastructure layer does not directly reference business logic code.Elysia Admin processes requests through a specific sequence of hooks. If any guard in the onBeforeHandle chain returns an error response, the subsequent business logic (handle.ts) is skipped and the error is returned immediately.
Lifecycle flow:
onRequest: Records the request start time.onBeforeHandle: Executes a chain of guards (IP blacklist, API switch, Route analysis, Auth, Rate limiting, Permissions).handle.ts: Executes the core business logic.onAfterResponse: Performs side effects like writing operation logs and updating rate limit counters..ai/ directory to ensure AI-generated code follows the project's directory structure and style. The workflow typically follows: User Prompt $\rightarrow$ IDE loads rules $\rightarrow$ AI reads .ai/ specs $\rightarrow$ AI generates code and SQL files $\rightarrow$ User manually executes handoff SQL or db:push.src directory is organized by function to separate business logic, core system components, and configuration.src/
├── api/ # API interface definitions (auth, system-manage)
├── assets/ # Static resources (images, styles, svg)
├── components/ # Vue components (core system components vs business components)
├── config/ # Project configuration (assets, modules, settings)
├── directives/ # Custom Vue directives (auth, roles, ripple, highlight)
├── enums/ # TypeScript enums (app, form)
├── hooks/ # Vue 3 Composables (auth, theme, table, layout)
├── locales/ # i18n resources (en, zh)
├── main.ts # Application entry point
├── mock/ # Mock data (JSON and TS files)
├── plugins/ # Plugin configurations (e.g., ECharts)
├── router/ # Vue Router setup (guards, modules, static/async routes)
├── store/ # Pinia state management (user, menu, setting, table)
└── types/ # TypeScript type definitions (api, common, component, router)