# How Voice-Pro's Three-Layer Application Architecture Works: UI, Controller, and Core Separation

> Explore Voice-Pros three-layer application architecture UI controller and core separation. Learn how this design enhances maintainability and testability for AI voice processing.

- Repository: [ABUS/voice-pro](https://github.com/abus-aikorea/voice-pro)
- Tags: architecture
- Published: 2026-08-03

---

**Voice-Pro implements a strict three-layer application architecture that separates Gradio UI components (`tab_*.py`), controller logic (`gradio_*.py`), and core processing modules (`abus_*.py`) to create a maintainable, testable AI voice processing pipeline.**

Voice-Pro (from the abus-aikorea repository) organizes its codebase using a **three-layer application architecture** that clearly delineates interface concerns from business logic. This pattern enables the dubbing studio, TTS tools, and ASR features to evolve independently while keeping the heavy AI processing decoupled from the Gradio frontend.

## The Three Architecture Layers Explained

Voice-Pro divides every feature into three distinct responsibility zones. Each layer has a specific file naming pattern and architectural role.

### UI Layer: Gradio Interface Components (tab_*.py)

The **UI layer** handles all visual presentation and widget definitions. Files matching the `tab_*.py` pattern define Gradio layouts, input components, and event bindings for specific functional areas.

For example, [`app/tab_gulliver.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/tab_gulliver.py) constructs the "Dubbing Studio" interface, while [`app/tab_tts_cosyvoice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/tab_tts_cosyvoice.py) builds the CosyVoice TTS tab. These files contain no processing logic—they only declare buttons, sliders, and text inputs, then wire them to controller methods via `.click()` and `.change()` handlers.

### Controller Layer: Event Orchestration (gradio_*.py)

The **controller layer** contains `GradioXxx` classes that act as intermediaries between the UI and core logic. Defined in files like [`app/gradio_gulliver.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/gradio_gulliver.py) and [`app/gradio_tts_cosyvoice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/gradio_tts_cosyvoice.py), these classes maintain UI state and implement handler functions that the UI layer invokes.

Controllers translate user inputs into the data structures required by core modules. For instance, `GradioGulliver` keeps track of selected ASR models, target languages, and file paths, then formats these into arguments for the processing pipeline.

### Core Processing Layer: Business Logic (abus_*.py)

The **core layer** implements all heavy processing without any Gradio dependencies. Files prefixed with `abus_` (such as [`app/abus_asr_faster_whisper.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_asr_faster_whisper.py) and [`app/abus_tts_cosyvoice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_tts_cosyvoice.py)) contain the actual AI inference, audio processing, file I/O, and model management.

This layer handles Faster-Whisper ASR inference, CosyVoice synthesis, translation services, FFmpeg operations, and path management via [`app/abus_path.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_path.py). Because these modules import no Gradio libraries, they can run in standalone scripts, unit tests, or alternative frontends.

## How the Layers Interact in Practice

The **three-layer application architecture** follows a strict top-down communication pattern with bottom-up result propagation:

1. **User triggers UI event** – A button click in a `tab_*.py` file calls a handler method.
2. **Controller processes input** – The `GradioXxx` class validates inputs, manages state, and prepares arguments.
3. **Core executes logic** – The controller delegates to `abus_*.py` functions for model inference and audio processing.
4. **Results return to UI** – Core modules return data (file paths, transcripts, audio arrays) to the controller, which updates Gradio components.

```python

# UI Layer (tab_gulliver.py): Event binding

def on_start_dubbing(self):
    self.controller.start_dubbing(
        self.input_video_path, 
        self.selected_asr, 
        self.selected_tts
    )

# Controller Layer (gradio_gulliver.py): Pipeline orchestration

class GradioGulliver:
    def start_dubbing(self, video_path, asr_name, tts_name):
        # Delegate to core layer

        transcript = abus_asr_faster_whisper.run_asr(video_path, model=asr_name)
        translated = abus_translate_deep.translate(transcript, target_lang='en')
        audio = abus_tts_cosyvoice.synthesize(translated, model=tts_name)
        return audio, transcript, translated

# Core Layer (abus_asr_faster_whisper.py): Heavy processing

def run_asr(video_path, model):
    # Load Faster-Whisper, extract audio, run inference

    return transcript_text

```

## Key Benefits of the Three-Layer Design

**Modularity** – Swapping ASR engines (e.g., switching from Faster-Whisper to Whisper-Timestamped) requires changes only in `abus_asr_*.py` files. The UI and controller remain unchanged because they interact through generic interfaces.

**Testability** – The core layer's lack of Gradio dependencies means you can unit test `abus_tts_cosyvoice.synthesize()` or `abus_asr_faster_whisper.run_asr()` without initializing a web interface. Controllers can be mocked to verify UI-to-core interactions in isolation.

**Maintainability** – UI layout adjustments stay confined to `tab_*.py` files, while algorithmic improvements live in `abus_*.py`. This separation prevents presentation changes from breaking processing logic and vice versa.

**Extensibility** – Adding a new TTS model requires only three new files: a [`tab_newmodel.py`](https://github.com/abus-aikorea/voice-pro/blob/main/tab_newmodel.py) for the interface, a [`gradio_newmodel.py`](https://github.com/abus-aikorea/voice-pro/blob/main/gradio_newmodel.py) for the controller, and an [`abus_tts_newmodel.py`](https://github.com/abus-aikorea/voice-pro/blob/main/abus_tts_newmodel.py) for the implementation. Existing features remain untouched.

## Summary

- Voice-Pro's **three-layer application architecture** strictly separates UI (`tab_*.py`), controllers (`gradio_*.py`), and core logic (`abus_*.py`).
- **UI layers** handle only Gradio widget definitions and event binding.
- **Controller layers** manage state translation and orchestrate calls to core modules.
- **Core layers** contain all AI inference, audio processing, and file operations with zero Gradio dependencies.
- This design enables independent testing, easy model swapping, and frontend-agnostic processing modules.

## Frequently Asked Questions

### What file naming conventions identify each architectural layer?

Voice-Pro uses consistent prefixes: `tab_*.py` files contain UI layer code, `gradio_*.py` files house controller classes (like `GradioGulliver`), and `abus_*.py` files implement the core processing layer. For example, [`app/tab_tts_cosyvoice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/tab_tts_cosyvoice.py) defines the interface, while [`app/abus_tts_cosyvoice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_tts_cosyvoice.py) contains the synthesis logic.

### Why does the core processing layer avoid Gradio imports?

The core layer (`abus_*.py`) deliberately excludes Gradio dependencies to ensure **portability and testability**. This allows the heavy AI processing modules to run in batch scripts, Jupyter notebooks, or alternative web frameworks without pulling in the Gradio stack. It also enables fast unit testing without initializing a web server.

### How does this architecture improve code maintenance?

By isolating UI changes in `tab_*.py` files and algorithmic updates in `abus_*.py`, developers can modify the presentation layer (e.g., rearranging buttons in the dubbing studio) without risking regression in the ASR or TTS pipelines. Similarly, upgrading the Faster-Whisper implementation in [`app/abus_asr_faster_whisper.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_asr_faster_whisper.py) requires no changes to the Gradio interface code.

### Can I use Voice-Pro's core modules in my own application?

Yes. Because the **core processing layer** has no Gradio dependencies, you can import functions directly from `abus_*.py` files into your own Python scripts. For example, `from abus_tts_cosyvoice import synthesize` allows you to generate speech using Voice-Pro's CosyVoice integration without launching the web interface.