# Architecture overview

> See how Optics is built, from the systems around it down to the layers inside it, and where to read about each part.

Optics is built from modules. Each module has an interface, so you can replace one part without a change to the others. This page gives the high-level design, the principles behind it, and how the components connect. It uses the levels of the C4 model: level 1 shows the system context, level 2 shows the containers and layers, and the pages linked at the end show level 3, the components.

## Design principles

Optics follows these principles:

1. **Modularity**: Components are in clear, independent modules with clear interfaces.
2. **Extensibility**: You can add new drivers, element sources, vision models and LLM engines without a change to the core code.
3. **Resilience**: Fallback mechanisms let a test continue when the primary method fails.
4. **Separation of concerns**: Action execution, element detection and vision processing are separate.
5. **Interface-based design**: Components communicate through interfaces, so you can replace one with another.

## Level 1 – system context

At the system level, Optics is between the people who write tests and the external automation infrastructure. It gives several entry points (CLI, REST API, Python library). Under them, it controls drivers, vision models and device farms.

`Optics and the systems around it`:

```mermaid
graph TB
    actorTester["Tester or QA Engineer"]
    actorIntegrator["Framework Integrator or Tooling Engineer"]
    actorCi["CI or Orchestration System"]

    systemOptics["Optics Framework"]

    extAutomation["Automation Backends (Appium, Selenium, Playwright, BLE)"]
    extDevices["Real Devices or Device Farms"]
    extVision["Vision and OCR Services"]
    extLLM["LLM Providers (Gemini, OpenAI, Anthropic)"]

    actorTester --> systemOptics
    actorIntegrator --> systemOptics
    actorCi --> systemOptics

    systemOptics --> extAutomation
    systemOptics --> extDevices
    systemOptics --> extVision
    systemOptics --> extLLM
```

The LLM providers are optional. Optics calls them only for AI self-heal and for the plain-English mode of `optics live`, and only when an entry in `llm_models` is enabled. See [Configuration](https://optics-framework.org/docs/reference/config).

## Level 2 – containers and layers

The rest of this page shows the containers and layers inside Optics (C4 level 2), and how they work together at run time.

Optics has these layers:

`The layers inside Optics`:

```mermaid
graph TB
    subgraph "User Interface Layer"
        CLI[CLI Commands]
        API[REST API]
        Library[Python Library]
    end

    subgraph "Core Layer"
        Optics[Optics Class]
        SessionMgr[SessionManager]
        Config[ConfigHandler]
    end

    subgraph "Builder Layer"
        Builder[OpticsBuilder]
        Factories[Factories]
    end

    subgraph "API Layer"
        ActionKW[ActionKeyword]
        AppMgmt[AppManagement]
        Verifier[Verifier]
        FlowCtrl[FlowControl]
    end

    subgraph "Strategy Layer"
        StrategyMgr[StrategyManager]
        Strategies[Location Strategies]
    end

    subgraph "Engine Layer"
        Drivers[Drivers]
        ElementSources[Element Sources]
        VisionModels[Vision Models]
        LLMModels[LLM Models]
    end

    subgraph "Execution Layer"
        ExecEngine[ExecutionEngine]
        TestRunner[TestRunner]
        EventSys[Event System]
    end

    CLI --> Optics
    API --> Optics
    Library --> Optics
    Optics --> SessionMgr
    SessionMgr --> Builder
    Builder --> Factories
    Factories --> Drivers
    Factories --> ElementSources
    Factories --> VisionModels
    Factories --> LLMModels
    Builder --> ActionKW
    Builder --> AppMgmt
    Builder --> Verifier
    Builder --> FlowCtrl
    ActionKW --> StrategyMgr
    StrategyMgr --> Strategies
    Strategies --> ElementSources
    Strategies --> VisionModels
    ExecEngine --> TestRunner
    TestRunner --> ActionKW
    TestRunner --> AppMgmt
    TestRunner --> Verifier
    TestRunner --> FlowCtrl
    ExecEngine --> EventSys
```

Each layer has these responsibilities:

- **User Interface Layer**:
  - The entry points for people and tools: CLI commands, the REST API and the Python library.
  - Changes what the user wants into high-level operations. It does not speak to drivers or vision models directly.
  - See [CLI layer](https://optics-framework.org/docs/contribute/cli-layer), [REST API layer](https://optics-framework.org/docs/contribute/api-layer) and [Library layer](https://optics-framework.org/docs/contribute/library-layer).
- **Core Layer**:
  - Holds the `Optics` facade, `SessionManager` and `ConfigHandler`.
  - Owns the configuration and the session lifecycle. It sends calls from the interface layer to the builder and the execution pipeline.
  - See [Components](https://optics-framework.org/docs/contribute/components) for the core components.
- **Builder Layer**:
  - `OpticsBuilder` and the factories change the configuration into driver, element source, vision model and LLM instances.
  - The one place where Optics connects dependencies and builds the fallback chains between engines.
  - See [Components](https://optics-framework.org/docs/contribute/components) and [Engines](https://optics-framework.org/docs/contribute/engines).
- **API Layer**:
  - Gives the high-level keywords for actions, app management, verification and flow control.
  - Holds the orchestration logic, and sends the low-level work to strategies and engines.
  - See [Components](https://optics-framework.org/docs/contribute/components) and [Strategies](https://optics-framework.org/docs/contribute/strategies).
- **Strategy Layer**:
  - Holds the self-healing location strategies, which use DOM, text and image methods.
  - Selects which element or vision strategy to use, and in which order.
  - See [Strategies](https://optics-framework.org/docs/contribute/strategies).
- **Engine Layer**:
  - Holds the automation backends (drivers), element sources, vision models and LLM models.
  - Speaks to external systems such as Appium, Selenium and Playwright, device farms, OCR and image services, and LLM providers.
  - See [Engines](https://optics-framework.org/docs/contribute/engines).
- **Execution Layer**:
  - Controls test execution, collects results and publishes events.
  - Gives the runners and the event system that run the API-layer keywords over time.
  - See [Execution](https://optics-framework.org/docs/contribute/execution) and [Events](https://optics-framework.org/docs/contribute/events).

For the component level (C4 level 3) and the design patterns in Optics, read:

- **Components**: [Components](https://optics-framework.org/docs/contribute/components) for `Optics`, `SessionManager`, the builder, the factories and the interfaces.
- **Strategies and engines**: [Strategies](https://optics-framework.org/docs/contribute/strategies) and [Engines](https://optics-framework.org/docs/contribute/engines) for the self-healing strategies and the engine implementations.
- **Architecture decisions**: [Decisions](https://optics-framework.org/docs/contribute/decisions) for the reasons behind the large design choices.

## Data flow

### Session creation flow

`How setup creates a session`:

```mermaid
sequenceDiagram
    participant User
    participant Optics
    participant SessionMgr
    participant Session
    participant Builder
    participant Factory

    User->>Optics: setup(config)
    Optics->>SessionMgr: create_session()
    SessionMgr->>Session: new Session()
    Session->>Builder: new OpticsBuilder()
    Builder->>Factory: get_driver(config)
    Factory->>Factory: load module & instantiate
    Factory-->>Builder: driver instance
    Builder-->>Session: configured builder
    Session-->>SessionMgr: session created
    SessionMgr-->>Optics: session_id
```

### Element location flow

`How a keyword finds an element`:

```mermaid
sequenceDiagram
    participant ActionKW
    participant StrategyMgr
    participant Strategy
    participant ElementSource
    participant VisionModel

    ActionKW->>StrategyMgr: locate(element)
    StrategyMgr->>Strategy: try XPathStrategy
    Strategy->>ElementSource: locate(element)
    ElementSource-->>Strategy: result or None
    alt XPath fails
        StrategyMgr->>Strategy: try TextDetectionStrategy
        Strategy->>ElementSource: capture()
        ElementSource-->>Strategy: screenshot
        Strategy->>VisionModel: detect_text(screenshot)
        VisionModel-->>Strategy: text locations
    end
    Strategy-->>StrategyMgr: coordinates
    StrategyMgr-->>ActionKW: element location
```

## Cross-cutting concerns

These concerns go across many layers and containers. Together they set how Optics behaves at run time and its quality.

### Self-healing mechanism

Optics heals a step at many levels:

1. **Parameter fallback**: If a keyword gets a list of values for a parameter, it tries each combination of values. It moves to the next combination only when the element was not found.
2. **Strategy fallback**: If one location strategy fails, Optics tries the next.
3. **Driver fallback**: If one driver fails, Optics tries the next configured driver.
4. **Element source fallback**: If one element source fails, Optics tries the next.
5. **Vision model fallback**: If one OCR or image model fails, Optics tries the next.
6. **AI self-heal**: If all strategies fail and `ai_self_heal` is on, an LLM gets one chance to do the step. It is off by default. See [AI self-heal](https://optics-framework.org/docs/elements/self-heal).

Because each level has a fallback, a test continues through more failures.

### Configuration structure

The configuration has levels. It supports:

- Multiple drivers in priority order
- Multiple element sources with fallback chains
- Multiple vision models for redundancy
- Settings for each component

See [Configuration](https://optics-framework.org/docs/reference/config) for every key.

### Extension points

You can extend Optics at these points:

1. **New drivers**: Implement `DriverInterface` in `engines/drivers/`.
2. **New element sources**: Implement `ElementSourceInterface` in `engines/elementsources/`.
3. **New vision models**: Implement `ImageInterface` in `engines/vision_models/image_models/` or `TextInterface` in `engines/vision_models/ocr_models/`.
4. **New LLM engines**: Implement `LLMInterface` in `engines/llm_models/`.
5. **New strategies**: Extend `LocatorStrategy` in `common/strategies.py`.
6. **New keywords**: Add a public method to an API class. `KeywordRegistry` registers it by name. To use it from Python or Robot Framework, also add a method with the `@keyword` decorator to the `Optics` class.

See [Extending Optics](https://optics-framework.org/docs/contribute/extending) for step-by-step recipes.

## Related documentation

- [REST API reference](https://optics-framework.org/docs/reference/http-api): all REST API endpoints.
- [Keyword reference](https://optics-framework.org/docs/reference/keywords/): every keyword and its parameters.
- [Use Optics from Python](https://optics-framework.org/docs/create/python): the Python API.
- [Configuration](https://optics-framework.org/docs/reference/config): the configuration keys.
- [Quickstart](https://optics-framework.org/docs/get-started/quickstart): install Optics, make a first project and run it.
- [Reference](https://optics-framework.org/docs/reference/): usage examples and patterns.

## Next steps

From here, go from the level 1 and level 2 views on this page to the level 3 components and systems.

- [Components](https://optics-framework.org/docs/contribute/components): `Optics`, `SessionManager`, the builder, the factories and the interfaces.
- [Engines](https://optics-framework.org/docs/contribute/engines): Driver, element source, vision model and LLM implementations.
- [Strategies](https://optics-framework.org/docs/contribute/strategies): The strategy pattern and the self-healing mechanisms.
- [Execution](https://optics-framework.org/docs/contribute/execution): The test execution flow.
- [Events](https://optics-framework.org/docs/contribute/events): `EventSDK` and event tracking.
- [Errors](https://optics-framework.org/docs/contribute/errors): Error codes and how Optics handles errors.
- [Logging](https://optics-framework.org/docs/contribute/logging): The logging system and its configuration.
- [CLI layer](https://optics-framework.org/docs/contribute/cli-layer): How the command-line interface is built.
- [REST API layer](https://optics-framework.org/docs/contribute/api-layer): How the REST API is built and connects to the core.
- [Library layer](https://optics-framework.org/docs/contribute/library-layer): The Python library and its programmatic interface.
