# motoingit/plus-ultra architecture

> Architecture diagram of the GitHub repository motoingit/plus-ultra, 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/motoingit/plus-ultra
- Repository: https://github.com/motoingit/plus-ultra

## Overview

PLUS-ULTRA is a floating desktop assistant for task/reminder management and related learning and opportunity tracking. The main workflow starts at the application entry point, initializes persistence and domain services, then opens the floating widget and dashboard; users manage workspace records through views and services backed by SQLite. Reminder scheduling and desktop alerts are a separate runtime branch. Additional documented capabilities include single-instance locking, persistent widget position, and JSON settings. Some subsystem connections are based on README documentation because their source was not sampled.

Main entry points: [`src/plus_ultra/main.py`](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/main.py) (App entry), [`src/plus_ultra/ui/views/tasks_view.py`](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/views/tasks_view.py) (Tasks workspace), [`src/plus_ultra/services`](https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/services) (Domain services), [`src/plus_ultra/repositories/task_repository.py`](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/repositories/task_repository.py) (Task repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main["App entry<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_instance["Instance lock<br/>[desktop.py]"]
  node_scheduler["Reminder scheduler<br/>[scheduler.py]"]
  node_notify["Desktop notifications<br/>[notifications.py]"]
end

subgraph group_ui["Desktop interface"]
  node_widget["Floating widget<br/>[floating.py]"]
  node_panel["Dashboard panel<br/>[panel.py]"]
  node_tasksview["Tasks workspace<br/>[tasks_view.py]"]
  node_taskcard["Task cards<br/>[task_card.py]"]
  node_scroll["Scrollable frame<br/>[scrollable.py]"]
  node_icons["UI icons<br/>[icons.py]"]
  node_theme["UI theme<br/>[theme.py]"]
  node_otherviews["Other workspace views"]
end

subgraph group_domain["Workspace domains"]
  node_services["Domain services"]
  node_models["Domain models<br/>[models.py]"]
end

subgraph group_storage["Persistence"]
  node_repos["Workspace repositories"]
  node_taskrepo["Task repository<br/>[task_repository.py]"]
  node_connection["SQLite connection<br/>[connection.py]"]
  node_database[("SQLite database")]
  node_settings["JSON settings<br/>[settings.py]"]
  node_state["Widget position state"]
end

node_user(("Desktop user"))

node_user -->|"uses"| node_widget
node_main -->|"loads settings"| node_config
node_main -->|"acquires lock"| node_instance
node_main -->|"initializes database"| node_connection
node_main -->|"constructs repositories"| node_repos
node_main -->|"constructs services"| node_services
node_main -->|"creates widget"| node_widget
node_main -->|"creates dashboard"| node_panel
node_main -->|"starts scheduler"| node_scheduler
node_main -->|"loads and saves position"| node_state
node_widget -->|"opens dashboard"| node_panel
node_panel -.->|"hosts workspace"| node_tasksview
node_tasksview -->|"requests task operations"| node_services
node_tasksview -->|"renders tasks"| node_taskcard
node_tasksview -->|"uses scroll container"| node_scroll
node_tasksview -->|"loads icons"| node_icons
node_tasksview -->|"uses theme"| node_theme
node_services -.->|"delegates data access"| node_repos
node_taskrepo -->|"uses transactions"| node_connection
node_taskrepo -->|"reads and writes tasks"| node_database
node_taskrepo -->|"creates task models"| node_models
node_scheduler -.->|"checks reminders"| node_services
node_main -.->|"enables alerts"| node_notify
node_otherviews -.->|"manages workspace domains"| node_services
node_settings -.->|"stores preferences"| node_user
node_connection -->|"connects SQLite"| node_database

click node_main "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/main.py"
click node_config "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/config.py"
click node_instance "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/desktop.py"
click node_scheduler "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/scheduler.py"
click node_notify "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/notifications.py"
click node_widget "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/floating.py"
click node_panel "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/panel.py"
click node_tasksview "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/views/tasks_view.py"
click node_taskcard "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/components/task_card.py"
click node_scroll "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/components/scrollable.py"
click node_icons "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/icons.py"
click node_theme "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/theme.py"
click node_otherviews "https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/ui/views"
click node_services "https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/services"
click node_models "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/models.py"
click node_repos "https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/repositories"
click node_taskrepo "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/repositories/task_repository.py"
click node_connection "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/database/connection.py"
click node_settings "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/settings.py"
click node_state "https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/repositories/app_state_repository.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_config,node_instance,node_scheduler,node_notify,node_user toneBlue
class node_widget,node_panel,node_tasksview,node_taskcard,node_scroll,node_icons,node_theme,node_otherviews toneAmber
class node_services,node_models toneMint
class node_repos,node_taskrepo,node_connection,node_database,node_settings,node_state toneRose
```

## Components

### Application runtime

- [App entry](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/main.py): `src/plus_ultra/main.py`
- [Runtime configuration](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/config.py): `src/plus_ultra/config.py`
- [Instance lock](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/desktop.py): `src/plus_ultra/desktop.py`
- [Reminder scheduler](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/scheduler.py): `src/plus_ultra/scheduler.py`
- [Desktop notifications](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/notifications.py): `src/plus_ultra/notifications.py`

### Desktop interface

- [Floating widget](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/floating.py): `src/plus_ultra/ui/floating.py`
- [Dashboard panel](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/panel.py): `src/plus_ultra/ui/panel.py`
- [Tasks workspace](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/views/tasks_view.py): `src/plus_ultra/ui/views/tasks_view.py`
- [Task cards](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/components/task_card.py): `src/plus_ultra/ui/components/task_card.py`
- [Scrollable frame](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/components/scrollable.py): `src/plus_ultra/ui/components/scrollable.py`
- [UI icons](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/icons.py): `src/plus_ultra/ui/icons.py`
- [UI theme](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/ui/theme.py): `src/plus_ultra/ui/theme.py`
- [Other workspace views](https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/ui/views): `src/plus_ultra/ui/views`

### Workspace domains

- [Domain services](https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/services): `src/plus_ultra/services`
- [Domain models](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/models.py): `src/plus_ultra/models.py`

### Persistence

- [Workspace repositories](https://github.com/motoingit/plus-ultra/tree/main/src/plus_ultra/repositories): `src/plus_ultra/repositories`
- [Task repository](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/repositories/task_repository.py): `src/plus_ultra/repositories/task_repository.py`
- [SQLite connection](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/database/connection.py): `src/plus_ultra/database/connection.py`
- **SQLite database**
- [JSON settings](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/settings.py): `src/plus_ultra/settings.py`
- [Widget position state](https://github.com/motoingit/plus-ultra/blob/main/src/plus_ultra/repositories/app_state_repository.py): `src/plus_ultra/repositories/app_state_repository.py`

### Other components

- **Desktop user**

## Connections

- Desktop user → Floating widget: uses (evidence: `README.md`)
- App entry → Runtime configuration: loads settings (evidence: `src/plus_ultra/main.py`)
- App entry → Instance lock: acquires lock (evidence: `src/plus_ultra/main.py`)
- App entry → SQLite connection: initializes database (evidence: `src/plus_ultra/main.py`)
- App entry → Workspace repositories: constructs repositories (evidence: `src/plus_ultra/main.py`)
- App entry → Domain services: constructs services (evidence: `src/plus_ultra/main.py`)
- App entry → Floating widget: creates widget (evidence: `src/plus_ultra/main.py`)
- App entry → Dashboard panel: creates dashboard (evidence: `src/plus_ultra/main.py`)
- App entry → Reminder scheduler: starts scheduler (evidence: `src/plus_ultra/main.py`)
- App entry → Widget position state: loads and saves position (evidence: `src/plus_ultra/main.py`)
- Floating widget → Dashboard panel: opens dashboard (evidence: `src/plus_ultra/main.py`)
- Dashboard panel → Tasks workspace: hosts workspace
- Tasks workspace → Domain services: requests task operations (evidence: `src/plus_ultra/ui/views/tasks_view.py`)
- Tasks workspace → Task cards: renders tasks (evidence: `src/plus_ultra/ui/views/tasks_view.py`)
- Tasks workspace → Scrollable frame: uses scroll container (evidence: `src/plus_ultra/ui/views/tasks_view.py`)
- Tasks workspace → UI icons: loads icons (evidence: `src/plus_ultra/ui/views/tasks_view.py`)
- Tasks workspace → UI theme: uses theme (evidence: `src/plus_ultra/ui/views/tasks_view.py`)
- Domain services → Workspace repositories: delegates data access (evidence: `src/plus_ultra/services/course_service.py`)
- Task repository → SQLite connection: uses transactions (evidence: `src/plus_ultra/repositories/task_repository.py`)
- Task repository → SQLite database: reads and writes tasks (evidence: `src/plus_ultra/repositories/task_repository.py`)
- Task repository → Domain models: creates task models (evidence: `src/plus_ultra/repositories/task_repository.py`)
- Reminder scheduler → Domain services: checks reminders
- App entry → Desktop notifications: enables alerts (evidence: `src/plus_ultra/main.py`)
- Other workspace views → Domain services: manages workspace domains (evidence: `src/plus_ultra/ui/views/tasks_view.py`)
- JSON settings → Desktop user: stores preferences (evidence: `README.md`)
- SQLite connection → SQLite database: connects SQLite (evidence: `README.md`)