Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
314 lines (242 loc) · 11.7 KB

ARCHITECTURE.md

File metadata and controls

314 lines (242 loc) · 11.7 KB

AIWF Architecture

A comprehensive overview of the AI Workflow Framework's system architecture

한국어 | English

Table of Contents

  1. System Overview
  2. Architecture Layers
  3. Core Components
  4. Data Flow
  5. Plugin Architecture
  6. Security Considerations
  7. Performance Architecture
  8. Scalability and Future Extensions

System Overview

AIWF (AI Workflow Framework) is built on a modular, layered architecture designed to provide a flexible and extensible platform for AI-assisted software development workflows.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                      CLI Interface Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │   aiwf CLI   │  │ aiwf-lang   │  │   Hooks     │            │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
└─────────┼─────────────────┼─────────────────┼──────────────────┘
          │                 │                 │
┌─────────┼─────────────────┼─────────────────┼──────────────────┐
│         │          Core Engine Layer        │                   │
│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
│  │   Command    │  │  Resource   │  │    State    │           │
│  │  Processor   │  │   Loader    │  │   Manager   │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
│         │                 │                 │                   │
│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
│  │  Template    │  │   Plugin    │  │    Token    │           │
│  │   Engine     │  │   System    │  │   Manager   │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘           │
└─────────┼─────────────────┼─────────────────┼──────────────────┘
          │                 │                 │
┌─────────┼─────────────────┼─────────────────┼──────────────────┐
│         │      Storage & Persistence Layer  │                   │
│  ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐           │
│  │    File      │  │    JSON     │  │    Git      │           │
│  │   System     │  │   Storage   │  │ Integration │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘
          │                 │                 │
┌─────────▼─────────────────▼─────────────────▼──────────────────┐
│                    AI Integration Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Persona    │  │ Compression │  │  Evaluation │           │
│  │   Manager    │  │   Engine    │  │   System    │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘

Architecture Layers

1. CLI Interface Layer

The entry point for all user interactions with AIWF.

  • aiwf CLI: Main command-line interface built with Commander.js
  • aiwf-lang: Language management CLI for internationalization
  • Hooks: Git hooks and system integration points

2. Core Engine Layer

The heart of AIWF's functionality.

  • Command Processor: Routes and executes commands
  • Resource Loader: Manages bundled and user resources
  • State Manager: Handles workflow state and transitions
  • Template Engine: Processes project templates
  • Plugin System: Enables extensibility
  • Token Manager: Tracks and optimizes AI token usage

3. Storage & Persistence Layer

Manages all data storage and retrieval.

  • File System: Direct file operations and caching
  • JSON Storage: Structured data persistence
  • Git Integration: Version control system integration

4. AI Integration Layer

Provides intelligent features and AI assistance.

  • Persona Manager: AI behavior customization
  • Compression Engine: Context optimization for AI models
  • Evaluation System: Code and response quality assessment

Core Components

Resource Loader

The Resource Loader is a critical component that manages resources in both development and production environments.

// Resource loading priority
1. User resources (~/.aiwf/)
2. Project resources (./.aiwf/)
3. Bundled resources (npm package)

Key features:

  • Dynamic resource discovery
  • Fallback mechanism
  • Template and persona management
  • Hot-reloading in development

State Manager

Implements a sophisticated workflow-based state management system.

// State structure
{
  "version": "1.0.0",
  "lastUpdated": "ISO-8601 timestamp",
  "workflow": {
    "currentPhase": "development",
    "currentTask": "task-id",
    "transitions": []
  },
  "tasks": {
    "task-id": {
      "status": "in-progress",
      "dependencies": [],
      "priority": 0.8
    }
  }
}

Features:

  • Dependency tracking
  • Priority calculation
  • Circular dependency detection
  • State validation
  • Transition management

Command Processor

Handles command routing and execution with a modular design.

// Command structure
export default async function commandName(options) {
  // Validation
  // Execution
  // State update
  // Result formatting
}

Template Engine

Provides project scaffolding with AIWF integration built-in.

Supported templates:

  • api-server: Express.js API with TypeScript
  • npm-library: NPM package with Rollup
  • web-app: React application with Vite

Plugin System

Enables extensibility through a hook-based architecture.

// Plugin interface
export interface AIWFPlugin {
  name: string;
  version: string;
  hooks: {
    beforeCommand?: (command: string, args: any) => void;
    afterCommand?: (command: string, result: any) => void;
    beforeStateChange?: (oldState: State, newState: State) => State;
    afterStateChange?: (state: State) => void;
  };
}

Data Flow

Command Execution Flow

User Input → CLI Parser → Command Processor → Command Implementation
     ↓                                                    ↓
Token Tracking ← State Update ← Result Processing ← Execution
     ↓
User Output

Resource Loading Flow

Resource Request → Check User Resources → Found? → Return
                           ↓ Not Found
                   Check Project Resources → Found? → Return
                           ↓ Not Found
                   Load Bundled Resources → Return

State Management Flow

Command Execution → Pre-validation → State Lock → Update State
                                                       ↓
                                              Post-validation
                                                       ↓
                                              Notify Subscribers
                                                       ↓
                                              Release Lock

Plugin Architecture

AIWF's plugin system allows for extending functionality without modifying core code.

Plugin Loading

  1. Scan for plugins in:

    • ~/.aiwf/plugins/
    • ./node_modules/aiwf-plugin-*/
    • Explicit plugin paths

  2. Validate plugin structure

  3. Register hooks

  4. Initialize plugin

Hook Points

  • Lifecycle Hooks: init, destroy
  • Command Hooks: beforeCommand, afterCommand
  • State Hooks: beforeStateChange, afterStateChange
  • Resource Hooks: beforeResourceLoad, afterResourceLoad

Security Considerations

Input Validation

All user inputs are validated before processing:

  • Command arguments sanitization
  • Path traversal prevention
  • Injection attack prevention

Resource Isolation

  • User resources are isolated from system resources
  • Sandboxed template execution
  • Limited file system access

Token Security

  • Token counts stored locally only
  • No sensitive data in token tracking
  • Configurable privacy settings

Performance Architecture

Optimization Strategies

  1. Lazy Loading: Commands and resources loaded on-demand
  2. Caching: Frequently accessed resources cached in memory
  3. Parallel Processing: Independent operations run concurrently
  4. Incremental Updates: Only changed state portions updated

Memory Management

  • Resource pooling for templates
  • Automatic cache eviction
  • Memory usage monitoring
  • Garbage collection optimization

Performance Monitoring

Built-in performance tracking:

  • Command execution time
  • Resource loading time
  • State operation metrics
  • Token usage efficiency

Scalability and Future Extensions

Planned Extensions

  1. Cloud Sync: Synchronize state across devices
  2. Team Collaboration: Shared workflows and states
  3. Custom AI Models: Support for self-hosted models
  4. Advanced Analytics: Detailed productivity metrics

Extension Points

  • Custom command development
  • New template types
  • Additional AI personas
  • Alternative storage backends
  • Custom compression strategies

API Stability

AIWF follows semantic versioning:

  • Core APIs stable from v1.0.0
  • Plugin APIs versioned separately
  • Deprecation notices for breaking changes
  • Migration guides for major versions

Conclusion

AIWF's architecture is designed to be modular, extensible, and performant. The layered approach ensures separation of concerns while the plugin system enables customization without compromising core stability. This architecture supports both current features and future expansions while maintaining backward compatibility.