# caelestia-dots/caelestia architecture

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

- Interactive diagram: https://gitdiagram.com/caelestia-dots/caelestia
- Repository: https://github.com/caelestia-dots/caelestia

## Overview

Caelestia is a collection of desktop and application configurations, with Hyprland as a central configurable environment and theme integrations for Firefox and VS Code. The documented user workflow is to invoke the external CLI to install selected manifest components, then use the configured applications. The README and tree establish those capabilities; sampled source confirms the VS Code scheme watcher and Firefox native-messaging/theme updates, but not the internals of the CLI or most configuration loading links.

Main entry points: [`hypr/hyprland.lua`](https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland.lua) (Hyprland config), [`vscode/caelestia-vscode-integration/src/extension.ts`](https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/src/extension.ts) (VS Code integration), [`firefox/caelestia-firefox-integration/src/extension.ts`](https://github.com/caelestia-dots/caelestia/blob/main/firefox/caelestia-firefox-integration/src/extension.ts) (Firefox integration), [`firefox/native_app/app.fish`](https://github.com/caelestia-dots/caelestia/blob/main/firefox/native_app/app.fish) (Firefox native host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_install["Installation"]
  node_cli["Caelestia CLI"]
  node_manifest["Component manifest<br/>[manifest.toml]"]
end

subgraph group_desktop["Desktop environment"]
  node_hypr["Hyprland config<br/>[hyprland.lua]"]
  node_hyprvars["Hyprland defaults<br/>[variables.lua]"]
  node_hyprbinds["Keybindings<br/>[keybinds.lua]"]
  node_hyprutils["Hyprland utilities<br/>[functions.lua]"]
  node_uwsm["Session environment"]
end

subgraph group_apps["Application configs"]
  node_fish["Fish shell config<br/>[config.fish]"]
  node_foot["Foot terminal config<br/>[foot.ini]"]
  node_starship["Starship prompt<br/>[starship.toml]"]
  node_fastfetch["Fastfetch config<br/>[config.jsonc]"]
  node_firefoxconfig["Firefox profile config<br/>[user.js]"]
end

subgraph group_themes["Theme integrations"]
  node_firefoxhost["Firefox native host<br/>[app.fish]"]
  node_firefoxext["Firefox integration<br/>[extension.ts]"]
  node_vscodeext["VS Code integration<br/>[extension.ts]"]
  node_vscodetheme["Theme generator<br/>[theme.ts]"]
  node_vscodethemefile["VS Code theme<br/>[caelestia.json]"]
end

node_user(("User"))
node_firefox(("Firefox"))
node_darkreader(("Dark Reader"))
node_scheme["Current color scheme"]
node_vscode(("VS Code"))

node_user -->|"runs install"| node_cli
node_cli -->|"reads components"| node_manifest
node_cli -->|"installs config"| node_hypr
node_cli -->|"installs config"| node_fish
node_cli -->|"installs config"| node_firefoxconfig
node_hypr -->|"uses defaults"| node_hyprvars
node_hypr -->|"configures bindings"| node_hyprbinds
node_hypr -->|"uses utilities"| node_hyprutils
node_hypr -->|"uses environment"| node_uwsm
node_firefoxhost -->|"sends messages"| node_firefoxext
node_firefoxext -->|"updates theme"| node_firefox
node_firefoxext -.->|"sends theme"| node_darkreader
node_vscodeext -->|"watches and reads"| node_scheme
node_vscodeext -->|"generates colors"| node_vscodetheme
node_vscodeext -->|"writes theme"| node_vscodethemefile
node_vscode -->|"activates extension"| node_vscodeext

click node_manifest "https://github.com/caelestia-dots/caelestia/blob/main/manifest.toml"
click node_hypr "https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland.lua"
click node_hyprvars "https://github.com/caelestia-dots/caelestia/blob/main/hypr/variables.lua"
click node_hyprbinds "https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland/keybinds.lua"
click node_hyprutils "https://github.com/caelestia-dots/caelestia/blob/main/hypr/utils/functions.lua"
click node_uwsm "https://github.com/caelestia-dots/caelestia/blob/main/uwsm/env-hyprland"
click node_fish "https://github.com/caelestia-dots/caelestia/blob/main/fish/config.fish"
click node_foot "https://github.com/caelestia-dots/caelestia/blob/main/foot/foot.ini"
click node_starship "https://github.com/caelestia-dots/caelestia/blob/main/starship.toml"
click node_fastfetch "https://github.com/caelestia-dots/caelestia/blob/main/fastfetch/config.jsonc"
click node_firefoxconfig "https://github.com/caelestia-dots/caelestia/blob/main/firefox/user.js"
click node_firefoxhost "https://github.com/caelestia-dots/caelestia/blob/main/firefox/native_app/app.fish"
click node_firefoxext "https://github.com/caelestia-dots/caelestia/blob/main/firefox/caelestia-firefox-integration/src/extension.ts"
click node_vscodeext "https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/src/extension.ts"
click node_vscodetheme "https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/src/theme.ts"
click node_vscodethemefile "https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/themes/caelestia.json"

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_cli,node_manifest,node_user toneBlue
class node_hypr,node_hyprvars,node_hyprbinds,node_hyprutils,node_uwsm toneAmber
class node_fish,node_foot,node_starship,node_fastfetch,node_firefoxconfig toneMint
class node_firefoxhost,node_firefoxext,node_vscodeext,node_vscodetheme,node_vscodethemefile toneRose
class node_firefox,node_darkreader,node_scheme,node_vscode toneIndigo
```

## Components

### Installation

- **Caelestia CLI**
- [Component manifest](https://github.com/caelestia-dots/caelestia/blob/main/manifest.toml): `manifest.toml`

### Desktop environment

- [Hyprland config](https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland.lua): `hypr/hyprland.lua`
- [Hyprland defaults](https://github.com/caelestia-dots/caelestia/blob/main/hypr/variables.lua): `hypr/variables.lua`
- [Keybindings](https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland/keybinds.lua): `hypr/hyprland/keybinds.lua`
- [Hyprland utilities](https://github.com/caelestia-dots/caelestia/blob/main/hypr/utils/functions.lua): `hypr/utils/functions.lua`
- [Session environment](https://github.com/caelestia-dots/caelestia/blob/main/uwsm/env-hyprland): `uwsm/env-hyprland`

### Application configs

- [Fish shell config](https://github.com/caelestia-dots/caelestia/blob/main/fish/config.fish): `fish/config.fish`
- [Foot terminal config](https://github.com/caelestia-dots/caelestia/blob/main/foot/foot.ini): `foot/foot.ini`
- [Starship prompt](https://github.com/caelestia-dots/caelestia/blob/main/starship.toml): `starship.toml`
- [Fastfetch config](https://github.com/caelestia-dots/caelestia/blob/main/fastfetch/config.jsonc): `fastfetch/config.jsonc`
- [Firefox profile config](https://github.com/caelestia-dots/caelestia/blob/main/firefox/user.js): `firefox/user.js`

### Theme integrations

- [Firefox native host](https://github.com/caelestia-dots/caelestia/blob/main/firefox/native_app/app.fish): `firefox/native_app/app.fish`
- [Firefox integration](https://github.com/caelestia-dots/caelestia/blob/main/firefox/caelestia-firefox-integration/src/extension.ts): `firefox/caelestia-firefox-integration/src/extension.ts`
- [VS Code integration](https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/src/extension.ts): `vscode/caelestia-vscode-integration/src/extension.ts`
- [Theme generator](https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/src/theme.ts): `vscode/caelestia-vscode-integration/src/theme.ts`
- [VS Code theme](https://github.com/caelestia-dots/caelestia/blob/main/vscode/caelestia-vscode-integration/themes/caelestia.json): `vscode/caelestia-vscode-integration/themes/caelestia.json`

### Other components

- **User**
- **Firefox**
- **Dark Reader**
- **Current color scheme**
- **VS Code**

## Connections

- User → Caelestia CLI: runs install
- Caelestia CLI → Component manifest: reads components
- Caelestia CLI → Hyprland config: installs config
- Caelestia CLI → Fish shell config: installs config
- Caelestia CLI → Firefox profile config: installs config
- Hyprland config → Hyprland defaults: uses defaults
- Hyprland config → Keybindings: configures bindings
- Hyprland config → Hyprland utilities: uses utilities
- Hyprland config → Session environment: uses environment
- Firefox native host → Firefox integration: sends messages
- Firefox integration → Firefox: updates theme
- Firefox integration → Dark Reader: sends theme
- VS Code integration → Current color scheme: watches and reads
- VS Code integration → Theme generator: generates colors
- VS Code integration → VS Code theme: writes theme
- VS Code → VS Code integration: activates extension