# pimutils/khal architecture

> Architecture diagram of the GitHub repository pimutils/khal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pimutils/khal
- Repository: https://github.com/pimutils/khal

## Overview

Khal is a standards-based CLI and terminal calendar for creating, browsing, editing, and listing events stored as vdir/iCalendar files; vdirsyncer can synchronize those files with CalDAV and other systems. The main workflow runs from a user command through CLI dispatch and controller operations into calendar/event handling and storage, with formatted terminal output or the interactive ikhal UI. The graph also preserves configuration, parsing, and plugin capabilities. Relationships are limited to README statements and SOURCE INDEX references; several subsystem internals were not sampled.

Main entry points: [`khal/controllers.py`](https://github.com/pimutils/khal/blob/master/khal/controllers.py) (Calendar workflows), [`khal/ui/__init__.py`](https://github.com/pimutils/khal/blob/master/khal/ui/__init__.py) (Interactive ikhal), [`khal/khalendar/khalendar.py`](https://github.com/pimutils/khal/blob/master/khal/khalendar/khalendar.py) (Calendar collection), [`khal/cli.py`](https://github.com/pimutils/khal/blob/master/khal/cli.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_main["Program entry<br/>[__main__.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_controllers["Calendar workflows<br/>[controllers.py]"]
  node_plugins["Plugin themes<br/>[plugins.py]"]
end

subgraph group_domain["Calendar domain"]
  node_datetime["Date parsing<br/>[parse_datetime.py]"]
  node_ical["iCalendar codec<br/>[icalendar.py]"]
  node_event["Event model<br/>[event.py]"]
end

subgraph group_storage["Calendar storage"]
  node_collection["Calendar collection<br/>[khalendar.py]"]
  node_backend[("Calendar backend<br/>[backend.py]")]
  node_vdir["vdir files<br/>[vdir.py]"]
end

subgraph group_experience["Terminal experience"]
  node_display["Calendar display"]
  node_terminal["Terminal formatting<br/>[terminal.py]"]
  node_interactive["Interactive ikhal<br/>[__init__.py]"]
  node_calendar_widget["Calendar widget<br/>[calendarwidget.py]"]
  node_event_editor["Event editor<br/>[editor.py]"]
  node_widgets["UI widgets<br/>[widgets.py]"]
end

subgraph group_config["Configuration"]
  node_settings["Settings loader<br/>[settings.py]"]
  node_settings_utils["Settings utilities<br/>[utils.py]"]
  node_configwizard["Config wizard<br/>[configwizard.py]"]
end

node_user(("User"))
node_sync["vdirsyncer / CalDAV"]

node_user -->|"runs"| node_main
node_main -->|"dispatches"| node_cli
node_cli -->|"invokes"| node_controllers
node_cli -->|"loads"| node_plugins
node_cli -->|"invokes"| node_configwizard
node_controllers -->|"operates on"| node_collection
node_controllers -->|"parses ranges"| node_datetime
node_controllers -->|"uses codec"| node_ical
node_controllers -->|"edits events"| node_event
node_controllers -->|"opens view"| node_interactive
node_controllers -->|"formats output"| node_terminal
node_collection -->|"uses backend"| node_backend
node_collection -->|"manages events"| node_event
node_collection -->|"uses files"| node_vdir
node_backend -->|"uses codec"| node_ical
node_sync -.->|"synchronizes"| node_vdir
node_settings -->|"uses utilities"| node_settings_utils
node_settings_utils -->|"uses parser"| node_datetime
node_settings_utils -->|"configures calendars"| node_vdir
node_configwizard -->|"uses utilities"| node_settings_utils
node_display -->|"formats display"| node_terminal
node_interactive -->|"uses widget"| node_calendar_widget
node_interactive -->|"uses editor"| node_event_editor
node_interactive -->|"uses widgets"| node_widgets
node_interactive -->|"resolves themes"| node_plugins
node_interactive -->|"accesses calendars"| node_collection
node_event_editor -->|"uses widget"| node_calendar_widget
node_event_editor -->|"edits model"| node_event

click node_main "https://github.com/pimutils/khal/blob/master/khal/__main__.py"
click node_cli "https://github.com/pimutils/khal/blob/master/khal/cli.py"
click node_controllers "https://github.com/pimutils/khal/blob/master/khal/controllers.py"
click node_plugins "https://github.com/pimutils/khal/blob/master/khal/plugins.py"
click node_datetime "https://github.com/pimutils/khal/blob/master/khal/parse_datetime.py"
click node_ical "https://github.com/pimutils/khal/blob/master/khal/icalendar.py"
click node_event "https://github.com/pimutils/khal/blob/master/khal/khalendar/event.py"
click node_collection "https://github.com/pimutils/khal/blob/master/khal/khalendar/khalendar.py"
click node_backend "https://github.com/pimutils/khal/blob/master/khal/khalendar/backend.py"
click node_vdir "https://github.com/pimutils/khal/blob/master/khal/khalendar/vdir.py"
click node_settings "https://github.com/pimutils/khal/blob/master/khal/settings/settings.py"
click node_settings_utils "https://github.com/pimutils/khal/blob/master/khal/settings/utils.py"
click node_configwizard "https://github.com/pimutils/khal/blob/master/khal/configwizard.py"
click node_display "https://github.com/pimutils/khal/blob/master/khal/calendar_display.py"
click node_terminal "https://github.com/pimutils/khal/blob/master/khal/terminal.py"
click node_interactive "https://github.com/pimutils/khal/blob/master/khal/ui/__init__.py"
click node_calendar_widget "https://github.com/pimutils/khal/blob/master/khal/ui/calendarwidget.py"
click node_event_editor "https://github.com/pimutils/khal/blob/master/khal/ui/editor.py"
click node_widgets "https://github.com/pimutils/khal/blob/master/khal/ui/widgets.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_controllers,node_plugins,node_user toneBlue
class node_datetime,node_ical,node_event toneAmber
class node_collection,node_backend,node_vdir toneMint
class node_display,node_terminal,node_interactive,node_calendar_widget,node_event_editor,node_widgets toneRose
class node_settings,node_settings_utils,node_configwizard,node_sync toneIndigo
```

## Components

### Command entry

- [Program entry](https://github.com/pimutils/khal/blob/master/khal/__main__.py): `khal/__main__.py`
- [CLI commands](https://github.com/pimutils/khal/blob/master/khal/cli.py): `khal/cli.py`
- [Calendar workflows](https://github.com/pimutils/khal/blob/master/khal/controllers.py): `khal/controllers.py`
- [Plugin themes](https://github.com/pimutils/khal/blob/master/khal/plugins.py): `khal/plugins.py`

### Calendar domain

- [Date parsing](https://github.com/pimutils/khal/blob/master/khal/parse_datetime.py): `khal/parse_datetime.py`
- [iCalendar codec](https://github.com/pimutils/khal/blob/master/khal/icalendar.py): `khal/icalendar.py`
- [Event model](https://github.com/pimutils/khal/blob/master/khal/khalendar/event.py): `khal/khalendar/event.py`

### Calendar storage

- [Calendar collection](https://github.com/pimutils/khal/blob/master/khal/khalendar/khalendar.py): `khal/khalendar/khalendar.py`
- [Calendar backend](https://github.com/pimutils/khal/blob/master/khal/khalendar/backend.py): `khal/khalendar/backend.py`
- [vdir files](https://github.com/pimutils/khal/blob/master/khal/khalendar/vdir.py): `khal/khalendar/vdir.py`

### Terminal experience

- [Calendar display](https://github.com/pimutils/khal/blob/master/khal/calendar_display.py): `khal/calendar_display.py`
- [Terminal formatting](https://github.com/pimutils/khal/blob/master/khal/terminal.py): `khal/terminal.py`
- [Interactive ikhal](https://github.com/pimutils/khal/blob/master/khal/ui/__init__.py): `khal/ui/__init__.py`
- [Calendar widget](https://github.com/pimutils/khal/blob/master/khal/ui/calendarwidget.py): `khal/ui/calendarwidget.py`
- [Event editor](https://github.com/pimutils/khal/blob/master/khal/ui/editor.py): `khal/ui/editor.py`
- [UI widgets](https://github.com/pimutils/khal/blob/master/khal/ui/widgets.py): `khal/ui/widgets.py`

### Configuration

- [Settings loader](https://github.com/pimutils/khal/blob/master/khal/settings/settings.py): `khal/settings/settings.py`
- [Settings utilities](https://github.com/pimutils/khal/blob/master/khal/settings/utils.py): `khal/settings/utils.py`
- [Config wizard](https://github.com/pimutils/khal/blob/master/khal/configwizard.py): `khal/configwizard.py`

### Other components

- **User**
- **vdirsyncer / CalDAV**

## Connections

- User → Program entry: runs (evidence: `khal/__main__.py`)
- Program entry → CLI commands: dispatches (evidence: `khal/__main__.py`)
- CLI commands → Calendar workflows: invokes (evidence: `khal/cli.py`)
- CLI commands → Plugin themes: loads (evidence: `khal/cli.py`)
- CLI commands → Config wizard: invokes (evidence: `khal/cli.py`)
- Calendar workflows → Calendar collection: operates on (evidence: `khal/controllers.py`)
- Calendar workflows → Date parsing: parses ranges (evidence: `khal/controllers.py`)
- Calendar workflows → iCalendar codec: uses codec (evidence: `khal/controllers.py`)
- Calendar workflows → Event model: edits events (evidence: `khal/controllers.py`)
- Calendar workflows → Interactive ikhal: opens view (evidence: `khal/controllers.py`)
- Calendar workflows → Terminal formatting: formats output (evidence: `khal/controllers.py`)
- Calendar collection → Calendar backend: uses backend (evidence: `khal/khalendar/khalendar.py`)
- Calendar collection → Event model: manages events (evidence: `khal/khalendar/khalendar.py`)
- Calendar collection → vdir files: uses files (evidence: `khal/khalendar/khalendar.py`)
- Calendar backend → iCalendar codec: uses codec (evidence: `khal/khalendar/backend.py`)
- vdirsyncer / CalDAV → vdir files: synchronizes (evidence: `README.rst`)
- Settings loader → Settings utilities: uses utilities (evidence: `khal/settings/settings.py`)
- Settings utilities → Date parsing: uses parser (evidence: `khal/settings/utils.py`)
- Settings utilities → vdir files: configures calendars (evidence: `khal/settings/utils.py`)
- Config wizard → Settings utilities: uses utilities (evidence: `khal/configwizard.py`)
- Calendar display → Terminal formatting: formats display (evidence: `khal/calendar_display.py`)
- Interactive ikhal → Calendar widget: uses widget (evidence: `khal/ui/__init__.py`)
- Interactive ikhal → Event editor: uses editor (evidence: `khal/ui/__init__.py`)
- Interactive ikhal → UI widgets: uses widgets (evidence: `khal/ui/__init__.py`)
- Interactive ikhal → Plugin themes: resolves themes (evidence: `khal/ui/__init__.py`)
- Interactive ikhal → Calendar collection: accesses calendars (evidence: `khal/ui/__init__.py`)
- Event editor → Calendar widget: uses widget (evidence: `khal/ui/editor.py`)
- Event editor → Event model: edits model (evidence: `khal/ui/editor.py`)