# odoo/owl architecture

> Architecture diagram of the GitHub repository odoo/owl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/odoo/owl
- Repository: https://github.com/odoo/owl

## Overview

##### Main Components

a) Core Framework Components:
- Compiler System
- Runtime System
- Component System
- Reactivity System
- Template Engine (QWeb)
- Virtual DOM (BlockDOM)

b) Development Tools:
- DevTools Extension
- Playground
- VSCode Extension (owl-vision)

##### Architecture Layers (from bottom to top)

Layer 1: Core Foundation
- Common Utils & Types
- Error Handling
- Event System

Layer 2: Runtime Engine
- BlockDOM (Virtual DOM Implementation)
- Fiber System (Concurrent Mode)
- Scheduler
- Reactivity System

Layer 3: Component System
- Component Base
- Lifecycle Management
- Props System
- Hooks System
- Portal Management

Layer 4: Template System
- Template Compiler
- Code Generator
- Expression Parser
- Template Helpers

##### Key Relationships to Highlight

- Component → BlockDOM: Rendering pipeline
- Template Compiler → Runtime: Template compilation flow
- Reactivity System → Component: State management
- Hooks → Component: Component enhancement
- Event System → Component: Event handling
- DevTools → Runtime: Debugging interface

##### Implementation Details

**[External Tools Layer]**
**DevTools Extension <-> VSCode Extension <-> Playground**

**[Application Layer]**
**Component System <-> Template Engine**

**[Core Layer]**
**Reactivity System <-> Virtual DOM <-> Runtime Engine**

**[Foundation Layer]**
**Common Utils <-> Error Handling <-> Event System**

##### Additional Elements

- Version information (current: 2.x)
- Entry points for different use cases (script tag, npm)
- Test coverage integration points

##### Notes for Implementation

- Use clear labeling for all components
- Brief descriptions for main components
- Both synchronous and asynchronous flows

Remember to maintain a balance between detail and clarity, focusing on the architectural decisions that make Owl unique, such as its fine-grained reactivity system and asynchronous rendering capabilities.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef core fill:#2196F3,color:white
    classDef component fill:#4CAF50,color:white
    classDef compiler fill:#FF9800,color:white
    classDef devtools fill:#9C27B0,color:white
    classDef utils fill:#757575,color:white

    %% Foundation Layer
    subgraph Foundation
        Utils["Common Utils"]:::utils
        Types["Types"]:::utils
        ErrorHandling["Error Handling"]:::utils
        EventSystem["Event System"]:::utils
    end

    %% Runtime Layer
    subgraph Runtime
        BlockDOM["BlockDOM (Virtual DOM)"]:::core
        FiberSystem["Fiber System"]:::core
        Scheduler["Scheduler"]:::core
        Reactivity["Reactivity System"]:::core
    end

    %% Component Layer
    subgraph Components
        CompBase["Component Base"]:::component
        LifecycleHooks["Lifecycle Management"]:::component
        EventHandling["Event Handling"]:::component
        TemplateHelpers["Template Helpers"]:::component
    end

    %% Template Layer
    subgraph TemplateSystem
        Compiler["Template Compiler"]:::compiler
        CodeGen["Code Generator"]:::compiler
        Parser["Parser"]:::compiler
    end

    %% Development Tools
    subgraph DevTools
        DevToolsExt["DevTools Extension"]:::devtools
        VSCode["VSCode Extension"]:::devtools
        Playground["Playground"]:::devtools
    end

    %% Relationships
    Utils --> BlockDOM
    Utils --> Reactivity
    ErrorHandling --> CompBase
    EventSystem --> EventHandling
    
    BlockDOM --> CompBase
    FiberSystem --> Scheduler
    Scheduler --> CompBase
    Reactivity --> CompBase
    
    CompBase --> LifecycleHooks
    CompBase --> EventHandling
    CompBase --> TemplateHelpers
    
    Parser --> CodeGen
    CodeGen --> Compiler
    Compiler --> CompBase
    
    DevToolsExt --> BlockDOM
    DevToolsExt --> Reactivity
    VSCode --> DevToolsExt
    Playground --> DevToolsExt

    %% Click events
    click Utils "https://github.com/odoo/owl/blob/master/src/common/utils.ts"
    click Types "https://github.com/odoo/owl/blob/master/src/common/types.ts"
    click ErrorHandling "https://github.com/odoo/owl/blob/master/src/common/owl_error.ts"
    click EventSystem "https://github.com/odoo/owl/blob/master/src/runtime/event_handling.ts"
    click BlockDOM "https://github.com/odoo/owl/blob/master/src/runtime/blockdom/index.ts"
    click FiberSystem "https://github.com/odoo/owl/blob/master/src/runtime/fibers.ts"
    click Scheduler "https://github.com/odoo/owl/blob/master/src/runtime/scheduler.ts"
    click Reactivity "https://github.com/odoo/owl/blob/master/src/runtime/reactivity.ts"
    click CompBase "https://github.com/odoo/owl/blob/master/src/runtime/component.ts"
    click LifecycleHooks "https://github.com/odoo/owl/blob/master/src/runtime/lifecycle_hooks.ts"
    click TemplateHelpers "https://github.com/odoo/owl/blob/master/src/runtime/template_helpers.ts"
    click Compiler "https://github.com/odoo/owl/tree/master/src/compiler/"
    click CodeGen "https://github.com/odoo/owl/blob/master/src/compiler/code_generator.ts"
    click Parser "https://github.com/odoo/owl/blob/master/src/compiler/parser.ts"
    click DevToolsExt "https://github.com/odoo/owl/tree/master/tools/devtools/"
    click VSCode "https://github.com/odoo/owl/tree/master/tools/owl-vision/"
    click Playground "https://github.com/odoo/owl/tree/master/docs/playground/"

    %% Legend
    subgraph Legend
        CoreL["Core Runtime"]:::core
        CompL["Component System"]:::component
        CompilerL["Compiler System"]:::compiler
        DevL["Development Tools"]:::devtools
        UtilsL["Utilities"]:::utils
    end
```
