# Architecture

GenesisLab follows a **manager-based architecture** where different aspects of the robot learning problem are handled by specialized manager components.

## Overview

```
┌────────────────────────────────────────────────────────────┐
│                     GenesisEnv (Gymnasium)                  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                      LabScene                         │  │
│  │                                                       │  │
│  │  ┌─────────────────┐         ┌──────────────────┐   │  │
│  │  │ SceneBuilder    │────────▶│ Genesis Scene    │   │  │
│  │  └─────────────────┘         └──────────────────┘   │  │
│  │                                      │               │  │
│  │  ┌─────────────────┐                │               │  │
│  │  │ SceneController │◀───────────────┘               │  │
│  │  └─────────────────┘                                │  │
│  │           │                                          │  │
│  │  ┌─────────────────┐                                │  │
│  │  │ SceneQuerier    │                                │  │
│  │  └─────────────────┘                                │  │
│  │                                                       │  │
│  │  ┌──────────────────────────────────────────────┐   │  │
│  │  │             Manager System                    │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ ObservationManager                     │  │   │  │
│  │  │  │  ├─ base_pos, base_lin_vel, ...       │  │   │  │
│  │  │  │  ├─ joint_pos, joint_vel, ...          │  │   │  │
│  │  │  │  └─ [ObservationTerm, ...]             │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ ActionManager                          │  │   │  │
│  │  │  │  └─ Processes and applies actions      │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ RewardManager                          │  │   │  │
│  │  │  │  ├─ forward_velocity                   │  │   │  │
│  │  │  │  ├─ energy_penalty                     │  │   │  │
│  │  │  │  └─ [RewardTerm, ...]                  │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ CommandManager                         │  │   │  │
│  │  │  │  └─ Generates command targets          │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ TerminationManager                     │  │   │  │
│  │  │  │  └─ Checks termination conditions      │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ CurriculumManager                      │  │   │  │
│  │  │  │  └─ Manages training curriculum        │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  │  ┌────────────────────────────────────────┐  │   │  │
│  │  │  │ EventManager                           │  │   │  │
│  │  │  │  └─ Domain randomization events        │  │   │  │
│  │  │  └────────────────────────────────────────┘  │   │  │
│  │  └──────────────────────────────────────────────┘   │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘
```

## Core Components

### 1. LabScene

`LabScene` is the central orchestrator that:
- Manages the Genesis scene lifecycle
- Coordinates all managers
- Implements MDP (Markov Decision Process) functions
- Provides the interface between Gymnasium and Genesis

**Key Responsibilities**:
```python
class LabScene:
    def reset(self) -> Observations
    def step(self, actions) -> tuple[Observations, Rewards, Terminated, Truncated, Info]
    def compute_observations(self) -> dict[str, torch.Tensor]
    def compute_rewards(self) -> torch.Tensor
    def compute_terminations(self) -> tuple[torch.Tensor, torch.Tensor]
```

### 2. Scene Patterns

Three key patterns for interacting with the Genesis scene:

#### SceneBuilder
Constructs the initial scene:
```python
class SceneBuilder:
    def build_terrain(self) -> None
    def build_robot(self) -> None
    def build_sensors(self) -> None
    def build_objects(self) -> None
```

#### SceneController
Modifies scene state during simulation:
```python
class SceneController:
    def apply_actions(self, actions: torch.Tensor) -> None
    def reset_robots(self, env_ids: torch.Tensor) -> None
    def randomize_dynamics(self) -> None
```

#### SceneQuerier
Reads data from the scene:
```python
class SceneQuerier:
    def get_robot_state(self) -> dict[str, torch.Tensor]
    def get_sensor_data(self) -> dict[str, torch.Tensor]
    def get_contact_forces(self) -> torch.Tensor
```

### 3. Manager System

Managers are specialized components handling specific aspects:

#### ObservationManager
- Computes observation tensors from individual observation terms
- Supports policy observations and privileged (critic) observations
- Handles observation noise and normalization

#### ActionManager
- Processes raw actions from the policy
- Applies action scaling and clipping
- Converts actions to motor commands (e.g., PD targets)

#### RewardManager
- Computes total reward from weighted reward terms
- Supports per-term logging
- Handles reward scaling and clipping

#### CommandManager
- Generates command targets for the robot
- Supports resampling commands on reset
- Examples: velocity commands, pose targets

#### TerminationManager
- Checks termination conditions
- Distinguishes between truncation and termination
- Examples: timeout, falling, out-of-bounds

#### CurriculumManager
- Implements training curricula
- Adjusts difficulty over training
- Examples: terrain difficulty, disturbance magnitude

#### EventManager
- Handles episodic events and randomization
- Domain randomization for sim-to-real transfer
- Examples: dynamics randomization, robot state randomization

#### ObjectManager
- Manages dynamic objects in the scene
- Object spawning and tracking
- Object interaction rewards

## Term-Based Composition

Managers use a **term-based composition** pattern:

```python
@configclass
class ObservationManagerCfg:
    # Each term is a configuration for an observation computation
    base_lin_vel = ObservationTermCfg(
        func=observations.base_lin_vel,
        noise=UniformNoiseCfg(min=-0.1, max=0.1)
    )
    
    joint_pos = ObservationTermCfg(
        func=observations.joint_pos,
        scale=1.0
    )
```

**Benefits**:
- **Modularity**: Each term is independent
- **Reusability**: Terms can be shared across tasks
- **Configurability**: Easy to add/remove terms
- **Clarity**: Clear separation of concerns

## Data Flow

### During `reset()`:

```
1. EventManager.reset()      → Apply randomization events
2. SceneController.reset()    → Reset robot states
3. CommandManager.reset()     → Sample new commands  
4. ObservationManager.reset() → Compute initial observations
   └─ SceneQuerier.query()    → Read robot/sensor state
```

### During `step(actions)`:

```
1. ActionManager.process(actions)
   └─ SceneController.apply_actions()
2. Genesis.step()              → Physics step
3. ObservationManager.compute()
   └─ SceneQuerier.query()
4. RewardManager.compute()
5. TerminationManager.check()
```

## Configuration System

GenesisLab uses `@configclass` decorators for all configurations:

```python
from genesislab.utils.configclass import configclass

@configclass
class MyTaskCfg:
    # Scene configuration
    scene: LabSceneCfg = LabSceneCfg(
        num_envs=4096,
        env_spacing=4.0
    )
    
    # Manager configurations
    observations: ObservationManagerCfg = ObservationManagerCfg(...)
    actions: ActionManagerCfg = ActionManagerCfg(...)
    rewards: RewardManagerCfg = RewardManagerCfg(...)
```

**Critical Rule**: Always use `@configclass`, never `@dataclass`.

## Execution Flow

```mermaid
sequenceDiagram
    participant Gym as Gymnasium
    participant Scene as LabScene
    participant Mgrs as Managers
    participant GS as Genesis

    Gym->>Scene: reset()
    Scene->>Mgrs: reset()
    Mgrs->>GS: reset states
    GS-->>Mgrs: 
    Mgrs-->>Scene: observations
    Scene-->>Gym: obs, info

    loop Training
        Gym->>Scene: step(actions)
        Scene->>Mgrs: process(actions)
        Mgrs->>GS: apply actions
        GS->>GS: simulate
        Scene->>Mgrs: compute()
        Mgrs->>GS: query state
        GS-->>Mgrs: state data
        Mgrs-->>Scene: obs, rew, term
        Scene-->>Gym: obs, rew, term, trunc, info
    end
```

## Extension Points

GenesisLab is designed to be extended:

1. **Custom Observation Terms**: Add new observation functions
2. **Custom Reward Terms**: Define new reward calculations
3. **Custom Managers**: Implement specialized managers
4. **Custom Tasks**: Compose managers for new tasks
5. **Custom Robots**: Add new robot configurations

## Next Steps

- Learn about [core concepts](concepts.md)
- Understand [manager terms](../../api_reference/managers/index.md)
- See [task structure](../tutorials/creating_tasks.md) tutorial