# 2allen/carla-rl-project architecture

> Architecture diagram of the GitHub repository 2allen/carla-rl-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/2allen/carla-rl-project
- Repository: https://github.com/2allen/carla-rl-project

## Overview

##### Project type and purpose
- This is a reinforcement-learning (RL) based autonomous-driving research project built on the CARLA simulator.
- Its goal is to train and evaluate a PPO (Proximal Policy Optimization) agent to drive a virtual car in CARLA.

##### File structure
- Top-level scripts:
- train.py – orchestrates the training loop, checkpoints, tensorboard logging.
- test.py – loads a saved model, runs evaluation episodes, optionally renders or records video.
- src/ directory:
- environment.py – wraps the CARLA simulator as a Gymnasium-style environment.
- agent.py – implements the RL agent (policy, learning update) using Stable-Baselines3’s PPO.
- utils.py – shared helpers (e.g., video recorder, seeding, logging utilities).
- requirements.txt – lists Python and ML dependencies.
- test.py & train.py integrate src/ components and external services (CARLA server, Tensorboard).

##### Extract architecture insights from the README
- Core loop: environment ↔ agent ↔ training engine.
- External services:
- CARLA Simulator (Town04, vehicle models, rendering/video).
- Tensorboard for monitoring.
- File system for checkpoint & video storage.
- Data flows: observations, actions, rewards, logs, checkpoints, recorded videos.

##### Main components
a. CARLA Simulator Server
- Hosts the virtual world, physics, sensors.
- Exposes a socket/API to environment.py.
b. Environment Wrapper (environment.py)
- Translates CARLA data → Gym observations.
- Sends actions → CARLA control API.
- Computes reward.
c. RL Agent (agent.py)
- Implements PPO policy/value networks.
- Receives observations, outputs actions.
- Performs gradient updates.
d. Training Orchestrator (train.py)
- Instantiates agent & environment.
- Runs episodes, collects trajectories.
- Saves checkpoints every N steps.
- Logs metrics to Tensorboard.
e. Evaluation/Test Harness (test.py)
- Loads checkpoints.
- Runs episodes in environment.
- Optionally renders or records video → ./videos.
- Collects evaluation metrics.
f. Auxiliary services
- Tensorboard server (reads logs folder).
- File system (stores logs, checkpoints, videos).

##### Relationships and interactions
- Agent pulls observations from the wrapper, pushes actions back.
- Training Orchestrator links agent ↔ environment in a loop.
- Orchestrator writes logs → Tensorboard and saves model → disk.
- Test Harness reads model from disk, interacts same as training loop.
- Video Recorder (in utils.py) taps into the environment wrapper when render=False.

##### Architectural patterns and design principles
- Separation of concerns:
- Simulation (CARLA) vs. RL logic (agent, training).
- Core RL loop vs. evaluation loop.
- Modular wrappers (Gym API) to keep agent agnostic of simulator internals.
- Pluggable components: you could swap PPO for another algorithm by replacing agent.py.
- Clear data-flow channels for reproducibility (deterministic seeding, checkpointing).

##### Checklist for the engineer
- Clear component labels.
- Technologies: CARLA, Stable-Baselines3, Gymnasium, Tensorboard.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation Layer
    subgraph "Simulation Layer"
        CARLA["CARLA Simulator Server"]:::sim
    end

    %% Core RL Components
    subgraph "RL Core"
        ENV["Environment Wrapper"]:::core
        AGENT["RL Agent (PPO)"]:::core
        ORCH["Training Orchestrator"]:::core
        TEST["Evaluation/Test Harness"]:::core
        UTILS["Shared Utilities"]:::core
    end

    %% Services & Storage
    subgraph "Services & Storage"
        TENSOR["Tensorboard Server"]:::svc
        CKPT["Checkpoints Folder"]:::storage
        VIDF["Videos Folder"]:::storage
        DEP["requirements.txt"]:::svc
        DOC["README.md"]:::svc
    end

    %% Data Flows & Interactions
    CARLA -->|"sensor data"| ENV
    ENV -->|"control commands"| CARLA
    ENV -->|"observations"| AGENT
    AGENT -->|"actions"| ENV
    ORCH -->|"train() calls"| AGENT
    ORCH -->|"env.step(action)"| ENV
    ORCH -->|"metrics logging"| TENSOR
    ORCH -->|"model.save()"| CKPT
    TEST -->|"load model"| CKPT
    TEST -->|"run episodes"| ENV
    TEST -->|"video.save()"| VIDF

    %% Click Events
    click ENV "https://github.com/2allen/carla-rl-project/blob/main/src/environment.py"
    click AGENT "https://github.com/2allen/carla-rl-project/blob/main/src/agent.py"
    click UTILS "https://github.com/2allen/carla-rl-project/blob/main/src/utils.py"
    click ORCH "https://github.com/2allen/carla-rl-project/blob/main/train.py"
    click TEST "https://github.com/2allen/carla-rl-project/blob/main/test.py"
    click DEP "https://github.com/2allen/carla-rl-project/blob/main/requirements.txt"
    click DOC "https://github.com/2allen/carla-rl-project/blob/main/README.md"

    %% Styles
    classDef sim fill:#AED6F1,stroke:#2980B9,color:#1B4F72;
    classDef core fill:#ABEBC6,stroke:#27AE60,color:#145A32;
    classDef svc fill:#D5DBDB,stroke:#566573,color:#1C2833;
    classDef storage fill:#F9E79F,stroke:#B7950B,color:#7D6608;
```
