Astron Agent Platform Overview

Relevant source files

• README.md
• console/backend/hub/src/main/resources/application.yml
• console/frontend/index.html
• console/frontend/public/runtime-config.js
• docker/astronAgent/.env.example
• docker/astronAgent/docker-compose.yaml
• docker/astronAgent/nginx/nginx.conf
• docker/ragflow/docker-compose-macos.yml
• docs/CONFIGURATION.md
• docs/CONFIGURATION_zh.md
• docs/CONTRIBUTING_CN.md
• docs/DEPLOYMENT_GUIDE.md
• docs/DEPLOYMENT_GUIDE_WITH_AUTH.md
• docs/DEPLOYMENT_GUIDE_WITH_AUTH_zh.md
• docs/DEPLOYMENT_GUIDE_zh.md
• docs/README-zh.md
• docs/imgs/Astron_Readme.png
• docs/imgs/structure-zh.png
• docs/logo.svg
• docs/xinghuo_rag_tool.html

Purpose and Scope

This document provides a comprehensive overview of the Astron Agent platform architecture, covering its purpose, core components, technology stack, and deployment model. Astron Agent is an enterprise-grade Agentic Workflow development platform that integrates AI workflow orchestration, model management, AI and MCP tool integration, RPA automation, and team collaboration features.

For detailed deployment instructions, see Getting Started. For specific service documentation, refer to Core Services Architecture. For workflow orchestration details, see Workflow Engine.

Sources: README.md13-22 docs/README-zh.md13-28

---

Platform Architecture

Astron Agent follows a multi-layered microservices architecture with clear separation of concerns across frontend, backend API gateway, core business services, infrastructure, and external integrations.

High-Level Architecture Diagram

Sources: docker/astronAgent/docker-compose.yaml1-658 docker/astronAgent/.env.example88-102

Service Routing and Network Configuration

All services communicate within the astron-agent-network Docker bridge network. Nginx serves as the entry point, routing requests based on path prefixes:

Path Pattern	Target Service	Purpose
/	console-frontend:1881	Frontend application
/runtime-config.js	console-frontend:1881	Dynamic configuration (no cache)
/console-api/*	console-hub:8080	Backend API gateway
/workflow/v1/chat/completions	core-workflow:7880	Workflow SSE streaming
/console-api/chat-message/*	console-hub:8080	Chat SSE streaming

Sources: docker/astronAgent/nginx/nginx.conf45-163

---

Technology Stack

Astron Agent is built on a polyglot microservices architecture leveraging multiple programming languages and frameworks optimized for different service characteristics.

Programming Languages and Frameworks

Technology Distribution:

Component	Language/Framework	Purpose
console-frontend	React, TypeScript, Vite	User interface SPA
console-hub	Spring Boot 3.x, Java 21	API gateway, request routing
core-tenant	Go 1.21+, Fiber	High-performance multi-tenancy service
core-agent	Python 3.9+, FastAPI	Agent orchestration and execution
core-workflow	Python 3.9+, FastAPI	Workflow engine with SSE support
core-knowledge	Python 3.9+, FastAPI	RAG system integration
core-link	Python 3.9+, FastAPI	HTTP and MCP tool management
core-database	Python 3.9+, FastAPI	Dynamic memory database
core-rpa	Python 3.9+, FastAPI	RPA task automation
core-aitools	Python 3.9+, FastAPI	AI capabilities (TTS, OCR, etc.)

Sources: docker/astronAgent/docker-compose.yaml164-632 console/frontend/index.html1-80 console/backend/hub/src/main/resources/application.yml1-233

Infrastructure and Middleware

The platform uses a database-per-service pattern for data isolation:

Database	Owner Services	Purpose
sparkdb_manager (PostgreSQL)	core-database	User-specific dynamic schemas for memory operations
tenant (MySQL)	core-tenant	Application and user management
agent (MySQL)	core-agent	Bot definitions and chat history
workflow (MySQL)	core-workflow	Workflow versions and execution state
spark-link (MySQL)	core-link	Tool definitions and versions
astron_console (MySQL)	console-hub	Bot marketplace and publishing

Sources: docker/astronAgent/.env.example15-67 docker/astronAgent/docker-compose.yaml7-147

---

Core Components

Console Frontend Application

The frontend is a React single-page application built with TypeScript and Vite, featuring runtime configuration injection for deployment flexibility.

Key characteristics:

• Runtime Configuration: window.__APP_CONFIG__ object loaded via /runtime-config.js
• Dynamic Configuration Priority: Runtime config overrides build-time VITE_* environment variables
• OAuth2/PKCE Flow: Integrated with Casdoor SDK for authentication
• State Management: Zustand for global state
• Deployment: Served via nginx with cache control policies

Sources: console/frontend/index.html14-17 console/frontend/public/runtime-config.js1-3 docker/astronAgent/nginx/nginx.conf54-78

Console Hub API Gateway

The console-hub service is a Spring Boot application acting as the primary API gateway with OAuth2 resource server capabilities.

Key responsibilities:

• JWT validation against Casdoor JWK Set
• Space-based authorization with @SpacePreAuth annotations
• Request routing to core services with header injection
• Multi-channel bot publishing (Market, API, WeChat, MCP, Feishu)
• Internationalization via ResponseEnum and MessageSource

Configuration classes:

• OAuth2 configuration: OAUTH2_ISSUER_URI, OAUTH2_JWK_SET_URI, OAUTH2_AUDIENCE
• Database: HikariCP connection pooling with max 10 connections
• Redis: Lettuce client with optimized pool settings (max-active: 8)
• Flyway: Database migration with baseline-on-migrate enabled

Sources: console/backend/hub/src/main/resources/application.yml1-233 docker/astronAgent/docker-compose.yaml529-632

Core Service Architecture

The core services are Python FastAPI applications implementing specific business capabilities:

Sources: docker/astronAgent/.env.example146-189 docker/astronAgent/docker-compose.yaml164-481

---

Authentication and Authorization

Astron Agent implements OAuth2/OIDC with PKCE through Casdoor as the identity provider, with dual-layer authentication separating user and service contexts.

Authentication Flow

Key configuration:

• Frontend Casdoor Config: CONSOLE_CASDOOR_URL, CONSOLE_CASDOOR_ID, CONSOLE_CASDOOR_APP, CONSOLE_CASDOOR_ORG
• Backend OAuth2 Config: OAUTH2_ISSUER_URI, OAUTH2_JWK_SET_URI, OAUTH2_AUDIENCE
• Service Authentication: APP_AUTH_API_KEY, TENANT_KEY (not user JWT)
• Token Refresh: Automatic refresh 30 seconds before expiration

Sources: docker/astronAgent/.env.example104-112 console/backend/hub/src/main/resources/application.yml53-60 docker/astronAgent/.env.example172-176

Multi-Tenancy and Authorization

The platform implements space-based multi-tenancy with three space types:

Space Type	Description	User Limit
Personal	Individual workspace	1 user
Team	Collaborative workspace	100 users
Enterprise	Organization-wide workspace	500 users

Authorization enforcement:

• Row-level security: SQL queries automatically filtered by uid and app_id
• Space validation: @SpacePreAuth triggers membership check via core-tenant
• Header propagation: uid, space-id, enterprise-id injected into service calls

Sources: console/backend/hub/src/main/resources/application.yml201-214 docker/astronAgent/.env.example255-259

---

External Integrations

Astron Agent integrates with multiple external platforms to provide comprehensive AI capabilities.

iFLYTEK Spark Platform Integration

The platform uses unified credentials for multiple iFLYTEK services:

Required configuration:

• PLATFORM_APP_ID, PLATFORM_API_KEY, PLATFORM_API_SECRET - Shared credentials
• SPARK_API_PASSWORD - Additional password for LLM API
• SPARK_RTASR_API_KEY - Real-time ASR service key
• SPARK_VIRTUAL_MAN_APP_ID, SPARK_VIRTUAL_MAN_API_KEY, SPARK_VIRTUAL_MAN_API_SECRET - Virtual human service

Sources: docker/astronAgent/.env.example210-242 console/backend/hub/src/main/resources/application.yml127-139

Custom LLM Provider Support

The platform supports OpenAI-compatible API endpoints for flexibility:

Configuration	Purpose	Example
AI_ABILITY_CHAT_BASE_URL	Base URL (without /chat/completions)	https://spark-api-open.xf-yun.com/v1
AI_ABILITY_CHAT_MODEL	Model identifier	generalv3.5
AI_ABILITY_CHAT_API_KEY	Authentication key	your-api-key

Sources: docker/astronAgent/.env.example216-219 console/backend/hub/src/main/resources/application.yml142-149

RagFlow Knowledge Base Integration

Optional integration with RagFlow for document processing and vector search:

• Configuration: RAGFLOW_BASE_URL, RAGFLOW_API_TOKEN, RAGFLOW_DEFAULT_GROUP
• Alternative: Xinghuo RAG cloud service via XINGHUO_DATASET_ID
• Service: core-knowledge abstracts backend selection behind unified API

Sources: docker/astronAgent/.env.example179-183 docker/astronAgent/docker-compose.yaml389-419

RPA Platform Integration

Integration with iFLYTEK RPA cloud service for automation tasks:

• Default URL: https://newapi.iflyrpa.com (configurable via RPA_URL)
• Task Creation: XIAOWU_RPA_TASK_CREATE_URL endpoint
• Status Polling: XIAOWU_RPA_TASK_QUERY_URL endpoint
• Service: core-rpa manages task lifecycle

Sources: docker/astronAgent/.env.example136-141

---

Infrastructure and Data Layer

Database Architecture

The platform uses a polyglot persistence approach with database-per-service isolation:

PostgreSQL (Memory Database):

• Purpose: Dynamic user-specific schemas for memory operations
• Schema format: {RUNTIME_ENV}_{uid}_{database_id}
• Managed by: core-database service
• Connection: POSTGRES_HOST:POSTGRES_PORT/sparkdb_manager

MySQL (Business Data):

• Isolation: Each service owns its database
• Connection pooling: HikariCP with service-specific tuning
• Migration: Flyway for schema versioning (console-hub)

Sources: docker/astronAgent/.env.example15-29 docker/astronAgent/docker-compose.yaml7-43 console/backend/hub/src/main/resources/application.yml13-39

Object Storage (MinIO)

MinIO provides S3-compatible object storage with bucket-per-service isolation:

Bucket	Owner Service	Content Type
workflow	core-workflow	Workflow execution artifacts
console-oss	console-hub	Console uploads and assets
General	core-aitools	AI-generated content (images, audio)

Configuration:

• Endpoint: OSS_ENDPOINT (internal: minio:9000)
• Remote endpoint: OSS_REMOTE_ENDPOINT (external access)
• Credentials: OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET
• TTL: OSS_TTL (default: 157788000 seconds ≈ 5 years)
• Presigned URL expiry: Service-specific (e.g., 600s for console)

Sources: docker/astronAgent/.env.example54-67 docker/astronAgent/docker-compose.yaml126-147 console/backend/hub/src/main/resources/application.yml117-124

Redis Cache Layer

Redis provides caching and distributed operations with database partitioning:

Database Index	Owner Services	Purpose
0	core-agent, Default	General caching, default database
1	console-hub	Console-specific cache
Others	Various	Service-specific isolation

Configuration:

• Standalone mode: REDIS_ADDR=redis:6379
• Cluster mode: REDIS_IS_CLUSTER=true, REDIS_CLUSTER_ADDR
• Password: REDIS_PASSWORD (optional)
• Expiry: REDIS_EXPIRE (default: 3600s)

Sources: docker/astronAgent/.env.example31-40 docker/astronAgent/docker-compose.yaml46-59

Event Streaming (Kafka - Optional)

Apache Kafka provides event-driven architecture capabilities:

• Enable flag: KAFKA_ENABLE=0 (disabled by default)
• Topic: spark-agent-builder (used by core-agent and core-workflow)
• Purpose: Telemetry data, event streaming, observability
• Configuration: KAFKA_SERVERS, KAFKA_TIMEOUT, KAFKA_REPLICATION_FACTOR

Sources: docker/astronAgent/.env.example46-52 docker/astronAgent/docker-compose.yaml98-124

---

Deployment Model

Docker Compose Orchestration

The platform uses Docker Compose with strict health-check based dependency ordering:

Health check configuration:

• Interval: HEALTH_CHECK_INTERVAL=30s
• Timeout: HEALTH_CHECK_TIMEOUT=10s
• Retries: HEALTH_CHECK_RETRIES=60 (30 minutes total wait)
• Condition: condition: service_healthy enforces startup order

Example health check:

Sources: docker/astronAgent/docker-compose.yaml1-658 docker/astronAgent/.env.example311-314

Environment Configuration

The platform uses a comprehensive .env file with 200+ configuration variables:

Configuration categories:

1. Middleware: PostgreSQL, MySQL, Redis, Kafka, MinIO connection settings
2. Service Ports: All 8 core services + console services
3. Authentication: Casdoor OAuth2 configuration
4. External APIs: iFLYTEK Spark platform credentials
5. Optional Services: RagFlow, Kafka, OTLP observability
6. Feature Flags: KAFKA_ENABLE, OTLP_ENABLE, WORKFLOW_ENABLED

Priority order:

1. Environment variables (highest)
2. .env file values
3. Service default values (lowest)

Sources: docker/astronAgent/.env.example1-317

CI/CD Pipeline

The platform uses GitHub Actions with three automated workflows:

Workflow	Trigger	Actions
CI	PR/push to main/master	Quality checks, tests, coverage reports
Build & Push	Merge to main/master	Multi-arch Docker builds (amd64, arm64), push to GHCR
Release	Tag push (v*..)	Changelog generation, GitHub releases

Image registry:

• Registry: GitHub Container Registry (GHCR)
• Namespace: ghcr.io/iflytek/astron-agent/*
• Version tag: ASTRON_AGENT_VERSION (default: latest)

Sources: docker/astronAgent/.env.example8-9

Network Architecture

All services communicate within a single Docker bridge network:

• Network name: astron-agent-network
• DNS resolution: Container names resolve to internal IPs
• External access: Only nginx port (EXPOSE_NGINX_PORT=80) is exposed by default
• Optional ports: MinIO console (EXPOSE_MINIO_CONSOLE_PORT=18999)

Sources: docker/astronAgent/docker-compose.yaml636-638

---

Key Features and Capabilities

Bot Lifecycle Management

The platform supports complete bot lifecycle from creation to multi-channel publishing:

1. Bot Creation: Template-based or AI-assisted (sentence-to-bot)
2. Configuration: Model selection, dataset association, personality settings
3. Publishing Strategies: Market, API, WeChat, MCP, Feishu (strategy pattern)
4. Versioning: MaaS integration for workflow version management

Sources: console/backend/hub/src/main/resources/application.yml176-195

Workflow Orchestration

The core-workflow service provides node-based workflow execution with:

• SSE Streaming: Real-time execution updates via Server-Sent Events
• Node Types: LLM, Tool, Knowledge, Database, RPA, AITools
• State Management: MySQL persistence with Redis caching
• MinIO Storage: Workflow artifacts and execution results
• Debugging: Separate debug endpoint (WORKFLOW_DEBUG_URL)

Sources: docker/astronAgent/.env.example251-253 docker/astronAgent/nginx/nginx.conf81-106

Tool Management System

The core-link service manages HTTP and MCP tools:

• HTTP Tools: Custom API integrations with OpenAPI schema validation
• MCP Tools: Model Context Protocol support for advanced LLM interactions
• Versioning: Tool version tracking in spark-link database
• Authentication: Tool-specific auth credentials stored in Redis
• Security: SSRF protection via URL validation and IP blacklisting

Sources: docker/astronAgent/.env.example143-144

Knowledge Base and RAG

The core-knowledge service abstracts RAG backends:

• RagFlow Integration: Self-hosted document processing and vector search
• Xinghuo RAG: Cloud-based RAG service alternative
• Chunk Retrieval: Unified API endpoint /knowledge/v1/chunk/query
• Context Enhancement: Retrieved chunks wrapped in I18n prompt templates

Sources: docker/astronAgent/.env.example179-183

Memory Database Operations

The core-database service provides dynamic SQL capabilities:

• Dynamic Schemas: User-specific PostgreSQL schemas created on demand
• DML Execution: Automatic uid and app_id injection for row-level security
• DDL Operations: AST reconstruction for safe schema modifications
• Query Limits: Configurable result set limits to prevent resource exhaustion
• SQL Injection Prevention: Parameterized query enforcement

Sources: docker/astronAgent/.env.example133-134 docker/astronAgent/docker-compose.yaml196-226

---

Observability and Monitoring

OpenTelemetry Integration

The platform supports distributed tracing and metrics via OTLP:

• Enable flag: OTLP_ENABLE=0 (disabled by default)
• Endpoint: OTLP_ENDPOINT=127.0.0.1:4317
• Instrumented services: Python services (core-agent, core-workflow, core-link, core-database, core-aitools)
• Metrics export: Configurable intervals and batch sizes
• Trace export: Queue-based with timeout management

Configuration:

• OTLP_METRIC_EXPORT_INTERVAL_MILLIS=3000
• OTLP_TRACE_MAX_QUEUE_SIZE=2048
• OTLP_TRACE_MAX_EXPORT_BATCH_SIZE=2048

Sources: docker/astronAgent/.env.example69-80

Logging and Service Health

Each service maintains its own logging:

• Console services: ./config/{service}/logs/
• Log format: Service-specific (JSON for structured logging in Python services)
• Health endpoints: All services expose health check endpoints
• Nginx access logs: /var/log/nginx/access.log (mounted volume)

Sources: docker/astronAgent/docker-compose.yaml188-477

---

Summary

Astron Agent is a production-ready, enterprise-grade AI agent platform with:

• Multi-language microservices: Java, Python, Go, React/TypeScript
• 8 core services: Tenant, Database, RPA, Link, AITools, Agent, Knowledge, Workflow
• OAuth2/OIDC authentication: Via Casdoor with PKCE flow
• Polyglot persistence: PostgreSQL, MySQL (database-per-service), Redis, MinIO
• External integrations: iFLYTEK Spark platform, optional RagFlow, RPA cloud
• Docker Compose deployment: Health-check based orchestration
• Apache 2.0 License: Commercial-friendly open source

The platform is designed for scalability, reliability, and extensibility, supporting both rapid API-based prototyping and production-grade enterprise deployments.

Sources: README.md1-132 docker/astronAgent/docker-compose.yaml1-658