Skip to content

Add PlantUML high-level functional architecture diagram for AReaLite system#4

Draft
zhshgmail with Copilot wants to merge 2 commits into
litefrom
copilot/fix-1da2230a-8147-4c5a-af90-286766d182b4
Draft

Add PlantUML high-level functional architecture diagram for AReaLite system#4
zhshgmail with Copilot wants to merge 2 commits into
litefrom
copilot/fix-1da2230a-8147-4c5a-af90-286766d182b4

Conversation

Copilot AI commented Jul 29, 2025 •
edited
Loading

Copy link
Copy Markdown

This PR adds a comprehensive PlantUML diagram that visualizes the high-level functional architecture of the AReaLite system, following the same approach as PR #3 but specifically focused on the lite branch components.

What's Added

🏗️ Architecture Diagram (AReaLite_architecture.puml)

  • 6-layer functional architecture showing AReaLite's simplified hierarchical design
  • 26 functional components organized by their logical responsibilities
  • Chinese documentation with detailed comments explaining each component's purpose
  • Layer dependencies showing how different parts of the system interact

📚 Documentation (AReaLite_architecture_README.md)

  • Comprehensive Chinese documentation explaining each layer and component
  • Usage instructions for viewing the PlantUML diagram
  • Comparison with the main AReaL system architecture
  • Clear explanation of AReaLite's design principles and philosophy

Architecture Overview

The diagram organizes AReaLite into 6 functional layers:

  1. 应用层 (Application Layer) - User entry points and training examples
  2. 工作流层 (Workflow Layer) - Core innovation for flexible RL data collection workflows
  3. API层 (API Layer) - Abstract interfaces and data structures
  4. 引擎层 (Engine Layer) - Training and inference engine implementations
  5. 启动器层 (Launcher Layer) - Distributed deployment and scheduling
  6. 工具层 (Utils Layer) - Supporting utilities and tools

Key Features

  • Simplified architecture: Reduced from main AReaL's 7 layers to 6, removing complex scheduler and system layers
  • Workflow-centric design: Introduces dedicated workflow layer for flexible RL data collection
  • AI researcher friendly: Emphasizes SPMD mode over worker-based patterns
  • Single-file customization: Supports algorithm modifications within single files
  • Chinese localization: All names and comments are in Chinese as requested
  • PyTorch native: Uses raw PyTorch types without unnecessary abstractions

Comparison with Main AReaL

Unlike the main AReaL system's complex worker-based architecture, AReaLite focuses on:

  • AI-centric design minimizing system concept exposure
  • Transparent algorithm orchestration with clear operation flows
  • Developer-friendly navigation enabling easy IDE-based code exploration
  • Ecosystem compatibility with existing ML/RL tools
  • Reduced complexity while maintaining 90% of AReaL's functionality

The diagram can be viewed using online PlantUML editors, local PlantUML tools, or IDE extensions that support PlantUML rendering.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

@zhshgmail
Add AReaLite architecture PlantUML diagram and documentation
a916d27 
Co-authored-by: zhshgmail <126103537+zhshgmail@users.noreply.github.com>
Copilot AI changed the title [WIP] 参考@zhshgmail/AReaL/pull/3的做法，为lite分支也进行类似的分析并生成一样的plantuml，用于描述lite分支的高层功能视图。并将这个plantuml加入到当前的pr中 以下是提示词 我需要一个platuml绘制的AReal... Add PlantUML high-level functional architecture diagram for AReaLite system Jul 29, 2025
Copilot AI requested a review from zhshgmail July 29, 2025 05:48
zhshgmail pushed a commit that referenced this pull request Oct 29, 2025
@claude
refactor: Move all interface protocols to api module
1547d58 
This commit addresses design issues #1-#4 by reorganizing interfaces:

## Changes

**1. Moved to api module (proper location for interfaces):**
- `QueueAPI` → `areal/api/queue_api.py`
- `CacheAPI` → `areal/api/cache_api.py`
- `EventType`, `EventContext`, `EventHandler` → `areal/api/event_api.py`
- `QueueFilter` → `Filter` in `areal/api/filter_api.py`

**2. Created separate queue/cache event handler protocols:**
- `QueueEventHandler` + `QueueEventContext` in `areal/api/queue_event_handler.py`
- `CacheEventHandler` + `CacheEventContext` in `areal/api/cache_event_handler.py`

**3. Simplified event_system.py:**
- Now only contains `EventRegistry` class
- Imports interfaces from api module
- No longer defines protocols

**4. Renamed QueueFilter → Filter:**
- Generic name since it applies to both queue and cache
- Located in api module as proper interface
- StalenessFilter now implements Filter protocol

## Why Protocol as superclass? (Answer to #4)

Protocol enables **structural subtyping** (duck typing with types):

```python
from typing import Protocol

class QueueAPI(Protocol):
    def put(self, item): ...

# No need to inherit!
class MyQueue:
    def put(self, item):
        pass

# Type checker accepts this ✓
def foo(q: QueueAPI):
    q.put(1)

foo(MyQueue())  # Works! Structural typing
```

vs ABC (requires inheritance):
```python
from abc import ABC

class QueueAPI(ABC):
    ...

class MyQueue:  # Must inherit from QueueAPI
    ...
```

**Protocol = Interface without inheritance requirement**

## Remaining Work

Still TODO (per user feedback):
- Redesign ProximalRecomputer with propagator pattern (#3)
- Fix AsyncTaskRunner to require QueueAPI/CacheAPI (#5)
- Remove executor._filter_context (#6)
- Add CacheFilter or apply Filter to all operations (areal-project#7, areal-project#8)
- Fix RemoteInfEngine to not expose queue/cache (areal-project#9)
- Merge event_factory into workflow_factory (areal-project#10)
- Add vLLM recompute support (areal-project#11)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zhshgmail zhshgmail Awaiting requested review from zhshgmail

Assignees

@zhshgmail zhshgmail

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@zhshgmail