Skip to content

Add PlantUML high-level functional architecture diagram for AReaL system#3

Draft
zhshgmail with Copilot wants to merge 3 commits into
mainfrom
copilot/fix-53345257-7107-4321-b0a6-d3422f7c707c
Draft

Add PlantUML high-level functional architecture diagram for AReaL system#3
zhshgmail with Copilot wants to merge 3 commits into
mainfrom
copilot/fix-53345257-7107-4321-b0a6-d3422f7c707c

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 AReaL (Ant Reasoning RL) system, addressing the request for a functional view similar to a component diagram but organized by functional layers.

What's Added

🏗️ Architecture Diagram (AReaL_architecture.puml)

  • 7-layer functional architecture showing the system's hierarchical design
  • 33 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 (AReaL_architecture_README.md)

  • Comprehensive Chinese documentation explaining each layer and component
  • Usage instructions for viewing the PlantUML diagram
  • System design highlights including asynchronous RL capabilities
  • Clear explanation of the layer hierarchy and relationships

Architecture Overview

The diagram organizes AReaL into 7 functional layers:

  1. 应用层 (Application Layer) - User interaction entry points
  2. API层 (API Layer) - Core interface definitions and abstractions
  3. 调度层 (Scheduler Layer) - Resource management and task scheduling
  4. 系统层 (System Layer) - Distributed computing framework core
  5. 实现层 (Implementation Layer) - Concrete functional implementations
  6. 训练层 (Training Layer) - Training algorithms and workflows
  7. 评估层 (Evaluation Layer) - Model evaluation and benchmarking

Key Features

  • Functional organization: Components are grouped by logical function rather than strict code structure
  • Asynchronous RL focus: Highlights AReaL's core strength in asynchronous reinforcement learning
  • Scalability representation: Shows support from single-node to 1000+ GPU distributed training
  • Chinese localization: All names and comments are in Chinese as requested
  • Cross-layer dependencies: Notes where components have direct dependencies despite the layered design

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

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@zhshgmail
Add PlantUML architecture diagram and documentation for AReaL system
16c4f34 
Co-authored-by: zhshgmail <126103537+zhshgmail@users.noreply.github.com>
Copilot AI changed the title [WIP] 我需要一个platuml绘制的AReal main branch的高层功能视图，功能试图类似component diagram，不过是按照功能逻辑将系统分层，并在每层中用component的方式绘制出这一层的主要功能，一个主要功能一个co... Add PlantUML high-level functional architecture diagram for AReaL system Jul 29, 2025
Copilot AI requested a review from zhshgmail July 29, 2025 04:53
Copilot AI mentioned this pull request Jul 29, 2025
Draft
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>
zhshgmail pushed a commit that referenced this pull request Oct 29, 2025
@claude
refactor: Implement propagator pattern for event-driven architecture
8002c1a 
This commit addresses Issue #3 from the user's feedback by implementing the
proper propagator pattern where Queue and Cache own their event handlers.

Key Changes:
1. Created ProximalRecomputeLogic - Shared recomputation logic
2. Created QueueProximalRecomputer - Queue-specific handler
3. Created CacheProximalRecomputer - Cache-specific handler
4. Created EventPropagator - Propagates global events to queue/cache
5. Updated LocalQueue with event propagation support:
   - Added register_event_handler() method
   - Added on_event() method that creates QueueEventContext
   - Added process_all_items() for safe item iteration
6. Updated LocalCache with event propagation support:
   - Added register_event_handler() method
   - Added on_event() method that creates CacheEventContext
   - Added process_all_items() for safe item iteration
7. Updated event_factory to wire components with propagator pattern
8. Fixed circular imports by moving RolloutWorkflow to TYPE_CHECKING
9. Updated test imports to match new architecture

Architecture:
- EventRegistry fires global event (BEFORE_POLICY_UPDATE)
- EventPropagator receives event and calls queue.on_event() and cache.on_event()
- LocalQueue/LocalCache create QueueEventContext/CacheEventContext with metadata
- Queue/Cache-specific handlers receive events and process items via process_items()
- Maintains encapsulation - handlers don't access internal queue.Queue or list

This design enables:
- Future distributed implementations (ZeroMQ, Redis, Etcd)
- Clean separation of concerns
- No exposure of internal data structures
- Extensible event handling per queue/cache

🤖 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