# kimpearce888/supportos-plusplus architecture

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

- Interactive diagram: https://gitdiagram.com/kimpearce888/supportos-plusplus
- Repository: https://github.com/kimpearce888/supportos-plusplus

## Overview

SupportOS++ is a local-first support-desk desktop application. Users work in the Leptos UI to manage conversations, customers, search, reporting, and AI assistance; the UI reaches the Rust core through a loopback HTTP API, while the core synchronizes Help Scout data into SQLite and runs background jobs. The graph preserves README capabilities and major indexed modules. Some feature routes and implementations were not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`crates/core/src/workers.rs`](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/workers.rs) (Background workers), [`crates/core/src/db.rs`](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/db.rs) (SQLite database), [`crates/core/src/sync_engine.rs`](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/sync_engine.rs) (Help Scout sync), [`crates/core/src/http/server.rs`](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/http/server.rs) (Loopback API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and UI"]
  node_shell["Tauri shell<br/>[lib.rs]"]
  node_ui["Leptos frontend<br/>[lib.rs]"]
  node_ui_api["UI API client<br/>[api.rs]"]
end

subgraph group_api["Local API"]
  node_server["Loopback API server<br/>[server.rs]"]
  node_routes["HTTP routes"]
end

subgraph group_support["Support workflows"]
  node_sync["Help Scout sync<br/>[sync_engine.rs]"]
  node_helpscout["Help Scout adapter<br/>[helpscout.rs]"]
  node_conversation["Inbox and conversations"]
  node_customer_events["Customer timeline<br/>[customer_events.rs]"]
  node_catalog["Shared domain types"]
end

subgraph group_intelligence["Search and AI"]
  node_search["Full-text search<br/>[search.rs]"]
  node_embeddings["Embedding pipeline<br/>[embeddings.rs]"]
  node_vector["Embedded vector store"]
  node_ai_pipeline["AI workflow<br/>[ai_pipeline.rs]"]
  node_ai_center["AI center<br/>[ai_center.rs]"]
end

subgraph group_runtime["Data and background runtime"]
  node_database[("SQLite database<br/>[db.rs]")]
  node_migrations["Schema migrations<br/>[migrations.rs]"]
  node_workers["Background workers<br/>[workers.rs]"]
  node_jobs["Persistent job queue<br/>[jobs.rs]"]
  node_webhooks["Webhook processing<br/>[webhook_handler.rs]"]
  node_settings["Settings and secrets<br/>[settings.rs]"]
  node_backup["Encrypted backups<br/>[backup_service.rs]"]
end

node_user(("Support agent"))
node_local_ai["Local AI service"]

node_user -->|"uses"| node_ui
node_ui -->|"requests data"| node_ui_api
node_ui_api -->|"calls loopback API"| node_server
node_shell -->|"bridges to core"| node_server
node_server -->|"routes requests"| node_routes
node_routes -.->|"exposes sync API"| node_sync
node_sync -->|"fetches remote data"| node_helpscout
node_sync -->|"updates local mirror"| node_database
node_sync -->|"records activity"| node_customer_events
node_conversation -.->|"reads and writes"| node_database
node_customer_events -->|"stores timeline"| node_database
node_catalog -->|"provides shared types"| node_ui
node_search -->|"queries SQLite"| node_database
node_embeddings -->|"stores vectors"| node_vector
node_embeddings -->|"requests embeddings"| node_local_ai
node_ai_pipeline -->|"uses AI services"| node_ai_center
node_ai_pipeline -.->|"runs model stages"| node_local_ai
node_server -->|"starts background work"| node_workers
node_workers -->|"claims jobs"| node_jobs
node_workers -->|"runs sync jobs"| node_sync
node_workers -->|"dispatches processing"| node_webhooks
node_webhooks -->|"enqueues work"| node_jobs
node_workers -->|"runs backup"| node_backup
node_settings -->|"stores configuration"| node_database
node_database -->|"applies schema"| node_migrations
node_workers -->|"runs embedding work"| node_embeddings

click node_shell "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/app/src-tauri/src/lib.rs"
click node_ui "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/ui/src/lib.rs"
click node_ui_api "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/ui/src/api.rs"
click node_server "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/http/server.rs"
click node_routes "https://github.com/kimpearce888/supportos-plusplus/tree/main/crates/core/src/http/routes"
click node_sync "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/sync_engine.rs"
click node_helpscout "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/helpscout.rs"
click node_conversation "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/conversation_ops.rs"
click node_customer_events "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/customer_events.rs"
click node_catalog "https://github.com/kimpearce888/supportos-plusplus/tree/main/crates/catalog/src"
click node_search "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/search.rs"
click node_embeddings "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/embeddings.rs"
click node_vector "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/vectorstore_qdrant.rs"
click node_ai_pipeline "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/ai_pipeline.rs"
click node_ai_center "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/ai_center.rs"
click node_database "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/db.rs"
click node_migrations "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/migrations.rs"
click node_workers "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/workers.rs"
click node_jobs "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/jobs.rs"
click node_webhooks "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/webhook_handler.rs"
click node_settings "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/settings.rs"
click node_backup "https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/backup_service.rs"

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_shell,node_ui,node_ui_api toneBlue
class node_server,node_routes toneAmber
class node_sync,node_helpscout,node_conversation,node_customer_events,node_catalog toneMint
class node_search,node_embeddings,node_vector,node_ai_pipeline,node_ai_center toneRose
class node_database,node_migrations,node_workers,node_jobs,node_webhooks,node_settings,node_backup,node_user,node_local_ai toneIndigo
```

## Components

### Desktop and UI

- [Tauri shell](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/app/src-tauri/src/lib.rs): `crates/app/src-tauri/src/lib.rs`
- [Leptos frontend](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/ui/src/lib.rs): `crates/ui/src/lib.rs`
- [UI API client](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/ui/src/api.rs): `crates/ui/src/api.rs`

### Local API

- [Loopback API server](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/http/server.rs): `crates/core/src/http/server.rs`
- [HTTP routes](https://github.com/kimpearce888/supportos-plusplus/tree/main/crates/core/src/http/routes): `crates/core/src/http/routes`

### Support workflows

- [Help Scout sync](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/sync_engine.rs): `crates/core/src/sync_engine.rs`
- [Help Scout adapter](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/helpscout.rs): `crates/core/src/helpscout.rs`
- [Inbox and conversations](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/conversation_ops.rs): `crates/core/src/conversation_ops.rs`
- [Customer timeline](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/customer_events.rs): `crates/core/src/customer_events.rs`
- [Shared domain types](https://github.com/kimpearce888/supportos-plusplus/tree/main/crates/catalog/src): `crates/catalog/src`

### Search and AI

- [Full-text search](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/search.rs): `crates/core/src/search.rs`
- [Embedding pipeline](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/embeddings.rs): `crates/core/src/embeddings.rs`
- [Embedded vector store](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/vectorstore_qdrant.rs): `crates/core/src/vectorstore_qdrant.rs`
- [AI workflow](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/ai_pipeline.rs): `crates/core/src/ai_pipeline.rs`
- [AI center](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/ai_center.rs): `crates/core/src/ai_center.rs`

### Data and background runtime

- [SQLite database](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/db.rs): `crates/core/src/db.rs`
- [Schema migrations](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/migrations.rs): `crates/core/src/migrations.rs`
- [Background workers](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/workers.rs): `crates/core/src/workers.rs`
- [Persistent job queue](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/jobs.rs): `crates/core/src/jobs.rs`
- [Webhook processing](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/webhook_handler.rs): `crates/core/src/webhook_handler.rs`
- [Settings and secrets](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/settings.rs): `crates/core/src/settings.rs`
- [Encrypted backups](https://github.com/kimpearce888/supportos-plusplus/blob/main/crates/core/src/backup_service.rs): `crates/core/src/backup_service.rs`

### Other components

- **Support agent**
- **Local AI service**

## Connections

- Support agent → Leptos frontend: uses (evidence: `README.md`)
- Leptos frontend → UI API client: requests data (evidence: `crates/ui/src/lib.rs`)
- UI API client → Loopback API server: calls loopback API (evidence: `README.md`)
- Tauri shell → Loopback API server: bridges to core (evidence: `README.md`)
- Loopback API server → HTTP routes: routes requests (evidence: `crates/core/src/http/server.rs`)
- HTTP routes → Help Scout sync: exposes sync API
- Help Scout sync → Help Scout adapter: fetches remote data (evidence: `crates/core/src/sync_engine.rs`)
- Help Scout sync → SQLite database: updates local mirror (evidence: `crates/core/src/sync_engine.rs`)
- Help Scout sync → Customer timeline: records activity (evidence: `crates/core/src/sync_engine.rs`)
- Inbox and conversations → SQLite database: reads and writes
- Customer timeline → SQLite database: stores timeline (evidence: `crates/core/src/customer_events.rs`)
- Shared domain types → Leptos frontend: provides shared types (evidence: `README.md`)
- Full-text search → SQLite database: queries SQLite (evidence: `crates/core/src/search.rs`)
- Embedding pipeline → Embedded vector store: stores vectors (evidence: `crates/core/src/embeddings.rs`)
- Embedding pipeline → Local AI service: requests embeddings (evidence: `crates/core/src/embeddings.rs`)
- AI workflow → AI center: uses AI services (evidence: `crates/core/src/ai_pipeline.rs`)
- AI workflow → Local AI service: runs model stages
- Loopback API server → Background workers: starts background work (evidence: `crates/core/src/http/server.rs`)
- Background workers → Persistent job queue: claims jobs (evidence: `crates/core/src/workers.rs`)
- Background workers → Help Scout sync: runs sync jobs (evidence: `crates/core/src/workers.rs`)
- Background workers → Webhook processing: dispatches processing (evidence: `crates/core/src/workers.rs`)
- Webhook processing → Persistent job queue: enqueues work (evidence: `crates/core/src/webhook_handler.rs`)
- Background workers → Encrypted backups: runs backup (evidence: `crates/core/src/workers.rs`)
- Settings and secrets → SQLite database: stores configuration (evidence: `crates/core/src/settings.rs`)
- SQLite database → Schema migrations: applies schema (evidence: `crates/core/src/db.rs`)
- Background workers → Embedding pipeline: runs embedding work (evidence: `crates/core/src/workers.rs`)
