Architectural Layers

1. Application Layer (engine.go, engine/domain/application.go)

The entry point that initializes the application and coordinates all components.

type Application struct {
    EngineName      string
    Env             *Environment
    EmbedFS         embed.FS
    EmbedFSRootPath string
}

Responsibilities:

• Initialize dependency injection
• Fetch environment configuration
• Provide application-wide context

2. Bootstrap Layer (boot/)

Handles system initialization, environment setup, and dependency injection configuration.

File	Purpose
bootstrap.go	Main DI container initialization
env.go	Environment and configuration loading
services.go	Service registration
entities.go	Entity configuration
transitions.go	Transition handlers
helpers.go	Bootstrap utilities
enable.go	Feature enablement

Key Functions:

• DependencyInjection(): Initializes the DI container
• InitializeEnvironment(): Loads configuration from .env and INI files
• LoadConfig(): Parses configuration files

3. Core Layer (engine/)

Contains domain models, helpers, and foundational services.

Domain Models (engine/domain/)

Model	Description
Flow	Represents a workflow execution context
FlowState	Individual state in a workflow
FlowTransition	Transition between states
FlowStepResult	Result of a state transition
Config	Application configuration
Workflow	Workflow definition

Helpers (engine/helpers/)

Utility functions for common operations:

• String manipulation
• Map merging
• Type assertions
• File operations
• Memory management
• Logging

Services (engine/services/)

• atomic/: Atomic operations
• caches/: Caching implementations

4. Workflow Engine Layer (engine/workflow/)

The heart of the engine that executes workflows.

Component	Description
engine.go	Main workflow engine implementation
worker.go	Worker that processes workflow states
worker_context.go	Context management for workers
worker_session_context.go	Session-scoped context
handle_workflow.go	Workflow handling logic
run_sync.go	Synchronous execution
run_async.go	Asynchronous execution
wsl_integration.go	WSL to engine integration

5. WSL Layer (internal/wsl/)

The Workflow Specification Language compiler and runtime.

Component	Description
lexer.go	Tokenizes WSL source code
tokens.go	Token definitions
parser.go	Parses tokens into CST
cst.go	Concrete Syntax Tree
build_ast.go	Builds Abstract Syntax Tree
ast.go	AST node definitions
ir.go	Intermediate Representation (Graph)
api.go	Public API for parsing
errors.go	Error handling

6. Module System (modules/)

Extensible plugin architecture for custom functionality.

modules/
├── di.go              # Dependency injection for modules
├── modules.go         # Module registration
├── meta.go            # Module metadata
├── converse/          # Example: conversation module
│   └── transitions/   # Transition handlers
└── services/          # Service modules
    └── common/        # Common services
        └── transitions/

7. Event System (event/)

Event-driven communication using an event bus pattern.

// event/bus.go
var Bus EventBus.Bus

func init() {
    Bus = EventBus.New()
}