Overview

Relevant source files

• LICENSE
• README.md
• README.zh-CN.md
• assets/logo.svg
• package.json
• website/components/Hero.tsx

Purpose and Scope

This document provides a high-level introduction to the AStack framework, covering its core purpose, design philosophy, and architectural structure. It serves as the entry point for understanding how AStack enables the construction of composable AI applications.

For detailed information on specific aspects of the framework:

• Design philosophy and principles: see Framework Philosophy
• Installation and first steps: see Getting Started
• Core terminology and concepts: see Key Concepts
• In-depth architectural details: see Core Architecture

What is AStack?

AStack is a TypeScript-based framework for building AI applications through component composition. It implements a "everything is a component" design where complex AI systems are constructed by connecting simple, reusable components without intermediate adaptation layers.

The framework is built on the @hlang-org/runtime package, inheriting flow-based programming paradigms and monadic functional programming concepts. AStack provides a technically independent implementation with its own architecture while maintaining conceptual compatibility with Hlang principles.

Current Status: Beta version released. Active development with production-ready core features.

License: MIT (LICENSE1-21)

Repository: https://github.com/astack-tech/astack

Sources: README.md21-26 README.zh-CN.md21-26 package.json1-11 LICENSE1-21

Core Design Philosophy

AStack is built on three fundamental principles that guide all architectural decisions:

Principle	Description	Implementation
Everything is a Component	All functionality, from simple tools to complex agents, is expressed as a component with uniform interfaces	Base Component class with port system
Zero-Adaptation Layer	Components connect directly without intermediate adapters or middleware	Type-safe port connections via $i/$o patterns
Minimalism Over Complexity	Simple, intuitive APIs preferred over complex abstractions	Minimal boilerplate, declarative workflow definitions

These principles enable:

• Direct integration between AI models, tools, and business logic
• Seamless composition of components into complex workflows
• Minimal learning curve through consistent, predictable interfaces

Sources: README.md37-51 README.zh-CN.md37-51

Framework Architecture

High-Level Structure

AStack is organized as a pnpm monorepo with four core packages, example applications, and a documentation website.

Monorepo Architecture Diagram

Sources: package.json9-11 README.md450-458 High-Level Diagram 1

Three-Layer Architecture

Framework Layers Diagram

Sources: High-Level Diagram 2, README.md282-304

Package Structure

AStack consists of four npm packages under the @astack-tech scope:

Package	Purpose	Key Exports	Dependencies
@astack-tech/core	Foundation: Component base class, Pipeline orchestration, port system	Component, Pipeline, port utilities	@hlang-org/runtime
@astack-tech/components	Reusable AI components	Agent, StreamingAgent, TextSplitter, DefaultMemory	@astack-tech/core, @astack-tech/tools
@astack-tech/tools	Tool definition interface	createTool(), Tool type	None
@astack-tech/integrations	External service connections	ModelProvider interface, Deepseek class	@astack-tech/core, openai npm package

Dependency Graph:

• @astack-tech/components → @astack-tech/core → @hlang-org/runtime
• @astack-tech/components → @astack-tech/tools
• @astack-tech/integrations → @astack-tech/core

For detailed package documentation, see:

• Core Package: Core Package (@astack-tech/core)
• Components Package: Components Package (@astack-tech/components)
• Integrations Package: Integrations Package (@astack-tech/integrations)
• Tools Package: Tools Package (@astack-tech/tools)

Sources: README.md450-458 package.json9-11 High-Level Diagram 1

Computation Model

AStack implements four computation patterns that can be combined to create sophisticated AI workflows:

Four Core Patterns

Pattern	Description	Use Case
Operator Composition	Linear chaining of transformation components	Data processing pipelines, ETL workflows
Workflow Orchestration	Branching, joining, conditional routing	Complex decision trees, parallel processing
Reactive Data Flow	Event-driven asynchronous processing	Streaming data, real-time updates
Agent-to-Agent Events	Multi-agent communication with context preservation	Multi-agent systems, tool coordination

Pattern Implementation Diagram

The patterns are built on a monadic design where:

• Each component encapsulates its own state
• Operations are chainable through port connections
• Transformations compose from simple units
• Errors propagate through the chain in a controlled manner

For detailed pattern documentation, see Computation Patterns and Monadic Design Pattern.

Sources: README.md306-448 README.zh-CN.md306-448 High-Level Diagram 3

Key Components and Classes

Core Classes

Component System Structure

Key Class Locations

Class	Package	Primary Purpose
Component	@astack-tech/core	Base class for all components; provides port system and run() method
Pipeline	@astack-tech/core	Orchestrates component connections and execution flow
Agent	@astack-tech/components	Implements multi-round ReAct pattern with tool execution
StreamingAgent	@astack-tech/components	Extends Agent with streaming capabilities for real-time updates
TextSplitter	@astack-tech/components	Chunks text with configurable size and overlap
DefaultMemory	@astack-tech/components	Manages conversation history and context
Deepseek	@astack-tech/integrations	ModelProvider implementation for Deepseek API
Tool (type)	@astack-tech/tools	Interface for tool definitions

For detailed class documentation:

• Component and Pipeline: see Core Architecture
• Agent system: see Agent System
• Model providers: see Model Provider Interface
• Tools: see Tool Integration

Sources: High-Level Diagram 2, High-Level Diagram 4, README.md228-280

Execution Modes

AStack components support dual run modes:

1. Standalone Execution: Components can be executed independently via their run() method
2. Pipeline Execution: Components can be connected in a pipeline where data flows through port connections

Standalone Example:

Pipeline Example:

This dual-mode design enables flexible component reuse across different architectural patterns without code modifications.

Sources: README.md228-280 website/components/Hero.tsx50-78

Example Applications

The repository includes four example applications demonstrating progressive complexity:

Example	Location	Demonstrates	Complexity
Text Splitter	examples/text-splitter	Basic pipeline with single component	Simple
Agent with Tools	examples/agent-with-tools	Multi-round tool execution, zero-adaptation	Intermediate
Deep Research	examples/simple-deep-research	Multi-component workflow with feedback loops	Advanced
Chat Application	examples/serve-astack	Production architecture with streaming, frontend/backend	Production

For detailed example walkthroughs, see Example Applications.

Sources: README.md145-225 High-Level Diagram 5

Development Infrastructure

AStack uses modern TypeScript tooling:

• Package Manager: pnpm with workspaces
• Build System: Turbo for parallel builds and caching
• Bundler: tsup for TypeScript compilation
• Testing: Vitest
• Linting: ESLint with TypeScript parser
• Versioning: Changesets for version management and changelogs

For contribution guidelines and development workflow, see Development Guide.

Sources: package.json12-29 package.json38-50 High-Level Diagram 6

Requirements

• Runtime: Node.js >= 18.0.0 (package.json6-8)
• Language: TypeScript ^5.8 (package.json49)
• Package Manager: pnpm 10.24.0+ (package.json37)

Sources: package.json6-8 package.json37 package.json49 README.md126-130