# ahmedalbarghouti/soluna architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedalbarghouti/soluna
- Repository: https://github.com/ahmedalbarghouti/soluna

## Overview

Soluna is a single-process Visual Studio Code extension. Its runtime boundary is the VS Code extension host: it does not appear to ship a separate backend, service, or local daemon. All behavior is driven by VS Code commands, status bar actions, and extension configuration.

1. Core purpose  
The extension automates theme switching between a user-selected light theme and dark theme, either manually or on a schedule. The main user-facing outputs are theme changes in VS Code and a status bar entry that exposes the controls.

2. Main entrypoint and lifecycle  
`src/extension.ts` is the extension activation point. This is where the extension would register commands, initialize state, create the status bar UI, and start or stop any automatic switching logic when the extension is enabled or disabled.

3. Command-driven control plane  
The repo is organized around named commands exposed to VS Code, such as switching to light/dark themes, setting preferred themes, enabling/disabling automatic switching, and setting switch times. These commands form the primary control plane for both manual operation and configuration.

4. Automatic switching subsystem  
Automatic theme switching is governed by user-defined times for day and night. The README describes a 24-hour split into two periods, so the architecture likely centers on comparing the current time with configured thresholds and applying the corresponding theme when the schedule changes.

5. Theme state and configuration  
`src/configUtils.ts` is the configuration boundary. This module likely reads and writes extension settings such as:
- preferred light theme
- preferred dark theme
- automatic switching enabled/disabled
- light switch time
- dark switch time  
This is the persistence layer for user preferences, probably backed by VS Code settings.

6. Time and schedule logic  
`src/timeUtils.ts` isolates time calculations. This is the natural place for parsing times like `08:00` and `20:00`, comparing times, and deciding whether the current moment is in the light or dark period. This separation keeps scheduling logic independent from UI and settings access.

7. User interface surface  
The extension has a compact UI surface: a status bar item and a commands menu. The status bar button is the quick access path for switching themes or opening the command list, while the command palette exposes the full set of actions.

8. Asset boundary  
`src/assets/soluna-demo.gif` is documentation-only media used in the README. It is not part of the runtime architecture, but it supports user-facing documentation and onboarding.

9. Test boundary  
`src/test/suite/extension.test.ts` indicates integration-style extension tests using the VS Code test harness. This suggests the repository validates extension activation and command behavior in a VS Code-like environment rather than through isolated unit tests alone.

10. Tooling and development environment  
The project is TypeScript-based and uses standard VS Code extension tooling: `tsconfig.json` for compilation, ESLint/Prettier for code quality, and `vscode-test.mjs` / `.vscode-test.mjs` for test execution. These tools shape development and validation, but they do not add runtime dependencies.

11. External dependency surface  
The only external platform dependency that materially affects architecture is the VS Code API itself. Theme switching likely works by invoking VS Code’s configuration/theme APIs, and the extension’s lifecycle, commands, status bar, and settings are all mediated by VS Code.

12. Overall data flow  
User action or timer event → extension command/activation logic → config/time helpers determine target theme → VS Code theme setting is updated → UI reflects the new mode. The key architectural boundary is between user preferences stored in VS Code configuration and the logic that decides when and what to switch.

In short, Soluna is a small, command-centric VS Code extension with three main subsystems: extension activation/UI, configuration persistence, and time-based theme selection.

Main entry points: [`src/extension.ts`](https://github.com/ahmedalbarghouti/soluna/blob/main/src/extension.ts) (Extension entry), [`README.md`](https://github.com/ahmedalbarghouti/soluna/blob/main/README.md) (README), [`src/configUtils.ts`](https://github.com/ahmedalbarghouti/soluna/blob/main/src/configUtils.ts) (Config utils), [`src/timeUtils.ts`](https://github.com/ahmedalbarghouti/soluna/blob/main/src/timeUtils.ts) (Time utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_package_manifest["Package manifest<br/>extension manifest<br/>[package.json]"]
  node_extension_entry["Extension entry<br/>activation<br/>[extension.ts]"]
  node_command_surface{{"Commands<br/>control plane"}}
  node_status_bar_ui(("Status bar<br/>ui surface"))
  node_auto_switcher{{"Auto switcher<br/>scheduler"}}
  node_theme_applier["Theme apply<br/>theme action"]
  node_config_utils["Config utils<br/>settings boundary<br/>[configUtils.ts]"]
  node_time_utils["Time utils<br/>schedule logic<br/>[timeUtils.ts]"]
  node_vscode_api[("VS Code API<br/>platform API")]
end

subgraph group_validation["Validation"]
  node_test_suite["Test suite<br/>integration tests<br/>[extension.test.ts]"]
  node_test_host[("Test host<br/>vscode harness")]
end

subgraph group_tooling["Tooling"]
  node_tsconfig["TS config<br/>build config<br/>[tsconfig.json]"]
  node_test_runners["Test runners<br/>dev scripts<br/>[vscode-test.mjs]"]
end

subgraph group_docs["Docs"]
  node_docs_readme["README<br/>documentation<br/>[README.md]"]
  node_demo_asset["Demo GIF<br/>doc asset"]
end

node_package_manifest -->|"activates"| node_extension_entry
node_package_manifest -->|"contributes"| node_command_surface
node_extension_entry -->|"uses"| node_vscode_api
node_extension_entry -->|"implements"| node_command_surface
node_extension_entry -->|"creates"| node_status_bar_ui
node_extension_entry -->|"starts"| node_auto_switcher
node_extension_entry -->|"reads/writes"| node_config_utils
node_extension_entry -->|"evaluates"| node_time_utils
node_command_surface -->|"triggers"| node_theme_applier
node_command_surface -->|"updates"| node_config_utils
node_auto_switcher -->|"checks"| node_time_utils
node_auto_switcher -->|"applies"| node_theme_applier
node_config_utils -->|"persists via"| node_vscode_api
node_time_utils -.->|"supports"| node_vscode_api
node_status_bar_ui -->|"routes to"| node_command_surface
node_test_suite -->|"runs in"| node_test_host
node_test_suite -->|"verifies"| node_extension_entry
node_test_runners -->|"launches"| node_test_host
node_tsconfig -.->|"compiles"| node_extension_entry
node_docs_readme -->|"shows"| node_demo_asset
node_docs_readme -->|"describes"| node_command_surface
node_docs_readme -->|"explains"| node_auto_switcher

click node_package_manifest "https://github.com/ahmedalbarghouti/soluna/blob/main/package.json"
click node_extension_entry "https://github.com/ahmedalbarghouti/soluna/blob/main/src/extension.ts"
click node_config_utils "https://github.com/ahmedalbarghouti/soluna/blob/main/src/configUtils.ts"
click node_time_utils "https://github.com/ahmedalbarghouti/soluna/blob/main/src/timeUtils.ts"
click node_test_suite "https://github.com/ahmedalbarghouti/soluna/blob/main/src/test/suite/extension.test.ts"
click node_tsconfig "https://github.com/ahmedalbarghouti/soluna/blob/main/tsconfig.json"
click node_test_runners "https://github.com/ahmedalbarghouti/soluna/blob/main/vscode-test.mjs"
click node_docs_readme "https://github.com/ahmedalbarghouti/soluna/blob/main/README.md"

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_package_manifest,node_extension_entry,node_command_surface,node_status_bar_ui,node_auto_switcher,node_theme_applier,node_config_utils,node_time_utils,node_vscode_api toneBlue
class node_test_suite,node_test_host toneAmber
class node_tsconfig,node_test_runners toneMint
class node_docs_readme,node_demo_asset toneRose
```

## Components

### Runtime

VS Code extension host behavior and theme switching flow

- [Package manifest](https://github.com/ahmedalbarghouti/soluna/blob/main/package.json): extension manifest · Declares activation, commands, and extension metadata · `package.json`
- [Extension entry](https://github.com/ahmedalbarghouti/soluna/blob/main/src/extension.ts): activation · Activates the extension, wires commands, UI, and switching lifecycle · `src/extension.ts`
- **Commands**: control plane · Manual theme switching and preference commands exposed to VS Code
- **Status bar**: ui surface · Quick-access entry point for switching and opening controls
- **Auto switcher**: scheduler · Coordinates scheduled light/dark theme changes
- **Theme apply**: theme action · Updates the active VS Code theme
- [Config utils](https://github.com/ahmedalbarghouti/soluna/blob/main/src/configUtils.ts): settings boundary · Reads and writes stored preferences and scheduling settings · `src/configUtils.ts`
- [Time utils](https://github.com/ahmedalbarghouti/soluna/blob/main/src/timeUtils.ts): schedule logic · Parses times and decides whether the current period is light or dark · `src/timeUtils.ts`
- **VS Code API**: platform API · Host APIs for commands, configuration, status bar, and theme control

### Validation

Tests and harness used to exercise the extension

- [Test suite](https://github.com/ahmedalbarghouti/soluna/blob/main/src/test/suite/extension.test.ts): integration tests · Exercises extension activation and command behavior in the VS Code test host · `src/test/suite/extension.test.ts`
- **Test host**: vscode harness · Runs the extension inside a VS Code-like test environment

### Tooling

Build and development support files

- [TS config](https://github.com/ahmedalbarghouti/soluna/blob/main/tsconfig.json): build config · TypeScript compilation settings · `tsconfig.json`
- [Test runners](https://github.com/ahmedalbarghouti/soluna/blob/main/vscode-test.mjs): dev scripts · Local and VS Code test execution entry points · `vscode-test.mjs`

### Docs

User-facing documentation and demo assets

- [README](https://github.com/ahmedalbarghouti/soluna/blob/main/README.md): documentation · Explains features, usage, and theme-switching workflow · `README.md`
- **Demo GIF**: doc asset · Animated demo used in the documentation

## Connections

- Package manifest → Extension entry: activates · Defines when and how the extension loads
- Package manifest → Commands: contributes · Publishes commands and extension metadata
- Extension entry → VS Code API: uses · Registers commands, status bar items, and configuration access
- Extension entry → Commands: implements · Binds command handlers to extension behavior
- Extension entry → Status bar: creates · Initializes the quick-access UI entry
- Extension entry → Auto switcher: starts · Turns scheduled switching on and off with extension lifecycle
- Extension entry → Config utils: reads/writes · Loads user preferences and persists updates
- Extension entry → Time utils: evaluates · Uses schedule logic to decide the active theme period
- Commands → Theme apply: triggers · Manual commands request theme changes
- Commands → Config utils: updates · Preference commands store selected themes and times
- Auto switcher → Time utils: checks · Compares the current time against configured thresholds
- Auto switcher → Theme apply: applies · Switches to light or dark theme when the schedule changes
- Config utils → VS Code API: persists via · Uses VS Code settings as the storage boundary
- Time utils → VS Code API: supports · Relies on runtime time source and extension context only indirectly
- Status bar → Commands: routes to · Offers quick access to the command-driven control plane
- Test suite → Test host: runs in · Executes inside the VS Code extension test harness
- Test suite → Extension entry: verifies · Covers activation and command behavior
- Test runners → Test host: launches · Starts the VS Code-based test environment
- TS config → Extension entry: compiles · Configures TypeScript build output
- README → Demo GIF: shows · Uses the GIF as a usage illustration
- README → Commands: describes · Documents the available controls and switching flow
- README → Auto switcher: explains · Describes scheduled day/night switching behavior
