# minad/vertico architecture

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

- Interactive diagram: https://gitdiagram.com/minad/vertico
- Repository: https://github.com/minad/vertico

## Overview

##### Main Components

The system should be divided into these key components:

a) Core Component (vertico.el):
- Minibuffer UI Manager
- Completion State Handler
- Engine
- Keybinding Manager

b) Extensions Layer:
- Variants (buffer, flat, grid, reverse, unobtrusive)
- Navigation Enhancements (directory, indexed, mouse, quick)
- Session Management (repeat, suspend)
- Configuration Manager (multiform)

##### Relationships and Data Flow

**Emacs Core <-> Vertico Core <-> Extensions**
- ^               ^

- v               v
**Completion      User Input**
- System

##### Detailed Component Breakdown

Core (vertico.el):

- Vertico Core      |

- Completion UI       |
- Candidate Filtering |
- Selection Handling  |
- History Management  |

Extensions:

- Display Extensions   |
- Buffer             |
- Grid               |
- Flat               |
- Reverse            |

- Function Extensions   |
- Directory          |
- Quick              |
- Mouse              |
- Indexed            |

- Control Extensions   |
- Multiform          |
- Repeat             |
- Suspend            |

##### Integration Points

Connections with:
- Emacs completion system
- User input handling
- Extension loading system
- Configuration management

##### Key Features to Highlight

- Candidate index and total count
- History-based sorting
- Lazy highlighting
- Annotation support
- Functionality

##### Implementation Notes

- Minimal core (~600 lines)
- Extension modularity
- Configuration points
- Compatibility layers

This design captures Vertico's philosophy of being minimal yet extensible, while maintaining full compatibility with Emacs' built-in completion system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Emacs
        EC[Emacs Core]
        CS[Completion System]
    end

    subgraph Core
        VC["Vertico Core"]:::core
        MBM["Minibuffer UI Manager"]:::core
        CSH["Completion State Handler"]:::core
        DE["Display Engine"]:::core
        KBM["Keybinding Manager"]:::core
    end

    subgraph "Display Extensions"
        BD["Buffer Display"]:::display
        FD["Flat Display"]:::display
        GD["Grid Display"]:::display
        RD["Reverse Display"]:::display
        UD["Unobtrusive Display"]:::display
    end

    subgraph "Navigation Extensions"
        DN["Directory Navigation"]:::nav
        IN["Indexed Navigation"]:::nav
        MN["Mouse Navigation"]:::nav
        QN["Quick Navigation"]:::nav
    end

    subgraph "Session Extensions"
        RF["Repeat Functionality"]:::session
        SF["Suspend Functionality"]:::session
    end

    subgraph "Configuration"
        MC["Multiform Configuration"]:::config
    end

    UI((User Input))
    
    %% Core Connections
    EC <--> CS
    CS <--> VC
    VC --> MBM
    VC --> CSH
    VC --> DE
    VC --> KBM
    UI --> VC

    %% Extension Connections
    DE --> BD
    DE --> FD
    DE --> GD
    DE --> RD
    DE --> UD

    KBM --> DN
    KBM --> IN
    KBM --> MN
    KBM --> QN

    CSH --> RF
    CSH --> SF

    MC --> BD
    MC --> FD
    MC --> GD
    MC --> RD
    MC --> UD

    %% Click Events
    click VC "https://github.com/minad/vertico/blob/main/vertico.el"
    click BD "https://github.com/minad/vertico/blob/main/extensions/vertico-buffer.el"
    click FD "https://github.com/minad/vertico/blob/main/extensions/vertico-flat.el"
    click GD "https://github.com/minad/vertico/blob/main/extensions/vertico-grid.el"
    click RD "https://github.com/minad/vertico/blob/main/extensions/vertico-reverse.el"
    click UD "https://github.com/minad/vertico/blob/main/extensions/vertico-unobtrusive.el"
    click DN "https://github.com/minad/vertico/blob/main/extensions/vertico-directory.el"
    click IN "https://github.com/minad/vertico/blob/main/extensions/vertico-indexed.el"
    click MN "https://github.com/minad/vertico/blob/main/extensions/vertico-mouse.el"
    click QN "https://github.com/minad/vertico/blob/main/extensions/vertico-quick.el"
    click RF "https://github.com/minad/vertico/blob/main/extensions/vertico-repeat.el"
    click SF "https://github.com/minad/vertico/blob/main/extensions/vertico-suspend.el"
    click MC "https://github.com/minad/vertico/blob/main/extensions/vertico-multiform.el"

    %% Styling
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef display fill:#4CAF50,stroke:#2E7D32,color:white
    classDef nav fill:#FF9800,stroke:#EF6C00,color:white
    classDef session fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef config fill:#795548,stroke:#4E342E,color:white
    classDef default fill:#78909C,stroke:#546E7A,color:white

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Display Extensions]:::display
        L3[Navigation Extensions]:::nav
        L4[Session Extensions]:::session
        L5[Configuration]:::config
        L6[Emacs Components]:::default
    end
```
