# chr1st1ank/context-switch architecture

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

- Interactive diagram: https://gitdiagram.com/chr1st1ank/context-switch
- Repository: https://github.com/chr1st1ank/context-switch

## Overview

context-switch is a single-user, multi-device time tracker with a shared synchronized logbook. The main workflow is to start, stop, or switch a timer; organize spans by project and tag; then review history and derived reports from the CLI or Android app. Both clients use the shared Rust domain and storage core, with local-filesystem and S3-compatible storage options. The graph preserves documented sync and offline behavior, but sampled source does not expose all Android binding and synchronization paths, so those links are documented or left unconnected rather than inferred.

Main entry points: [`android/app/src/main/java/dev/contextswitch/LogbookStore.kt`](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/LogbookStore.kt) (Android logbook store), [`cli/cosw/cli.py`](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/cli.py) (CLI commands), [`android/app/src/main/java/dev/contextswitch/MainActivity.kt`](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/MainActivity.kt) (Android app shell), [`libs/contextswitch-core/src/storage.rs`](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/storage.rs) (Conditional storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_cli_core["CLI transactions<br/>[core.py]"]
  node_cli_manage["Project and tag management<br/>[manage.py]"]
  node_cli_history["Span history<br/>[history.py]"]
  node_cli_reports["Reports<br/>[reporting.py]"]
  node_cli_config["CLI configuration<br/>[config.py]"]
  node_android_app["Android app shell<br/>[MainActivity.kt]"]
  node_android_timer["Timer screen<br/>[TimerScreen.kt]"]
  node_android_log["Log screen<br/>[LogScreen.kt]"]
  node_android_manage["Management screen<br/>[ManageScreen.kt]"]
  node_android_settings["Settings screen<br/>[SettingsScreen.kt]"]
  node_android_store["Android logbook store<br/>[LogbookStore.kt]"]
  node_timer_service["Foreground timer service<br/>[TimerService.kt]"]
end

subgraph group_domain["Domain and sync"]
  node_domain_model["Logbook domain<br/>[domain.rs]"]
  node_sync["Sync coordination<br/>[sync.rs]"]
  node_portable_config["Portable config<br/>[portable_config.rs]"]
end

subgraph group_storage["Storage backends"]
  node_provider["Provider abstraction<br/>[provider.rs]"]
  node_storage_impl["Conditional storage<br/>[storage.rs]"]
  node_blob["Blob stores<br/>[blob.rs]"]
  node_s3["S3-compatible backend<br/>[s3.rs]"]
  node_crypto["Envelope encryption<br/>[crypto.rs]"]
end

subgraph group_bindings["Language bindings"]
  node_python_bindings["Python bindings<br/>[__init__.py]"]
  node_uniffi["UniFFI interface<br/>[lib.rs]"]
end

node_user(("User"))
node_local_files[("Local filesystem")]
node_s3_service["S3 storage service"]

node_user -->|"runs commands"| node_cli
node_user -->|"uses app"| node_android_app
node_cli -->|"transacts"| node_cli_core
node_cli -->|"dispatches"| node_cli_manage
node_cli -->|"dispatches"| node_cli_history
node_cli -->|"loads config"| node_cli_config
node_cli_history -->|"reads and mutates"| node_cli_core
node_cli_manage -->|"uses transactions"| node_cli_core
node_cli_history -->|"uses reporting"| node_cli_reports
node_cli_reports -->|"queries logbook"| node_python_bindings
node_cli_core -->|"opens providers"| node_python_bindings
node_cli -->|"mutates logbook"| node_python_bindings
node_android_app -->|"shows"| node_android_timer
node_android_app -->|"shows"| node_android_log
node_android_app -->|"shows"| node_android_manage
node_android_app -->|"shows"| node_android_settings
node_android_app -->|"uses store"| node_android_store
node_android_app -->|"starts or stops"| node_timer_service
node_android_timer -->|"uses logbook"| node_android_store
node_android_log -->|"reads logbook"| node_android_store
node_android_manage -->|"manages records"| node_android_store
node_android_settings -->|"uses logbook"| node_android_store
node_timer_service -->|"restores snapshot"| node_android_store
node_cli -->|"applies timer rules"| node_domain_model
node_android_store -.->|"uses shared core"| node_uniffi
node_uniffi -.->|"exposes domain"| node_domain_model
node_python_bindings -.->|"exposes domain"| node_domain_model
node_cli_core -.->|"opens configured provider"| node_provider
node_provider -->|"uses storage contract"| node_storage_impl
node_storage_impl -->|"reads and writes blobs"| node_blob
node_storage_impl -->|"validates logbook"| node_domain_model
node_s3 -->|"implements blob store"| node_blob
node_s3 -->|"sends storage requests"| node_s3_service
node_storage_impl -->|"stores local data"| node_local_files
node_provider -->|"configures encryption"| node_crypto
node_provider -->|"supports remote backend"| node_s3
node_android_store -.->|"syncs cached logbook"| node_sync
node_sync -->|"uses versioned storage"| node_storage_impl

click node_cli "https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/cli.py"
click node_cli_core "https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/core.py"
click node_cli_manage "https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/manage.py"
click node_cli_history "https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/history.py"
click node_cli_reports "https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/reporting.py"
click node_cli_config "https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/config.py"
click node_android_app "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/MainActivity.kt"
click node_android_timer "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/TimerScreen.kt"
click node_android_log "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/LogScreen.kt"
click node_android_manage "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/ManageScreen.kt"
click node_android_settings "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/SettingsScreen.kt"
click node_android_store "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/LogbookStore.kt"
click node_timer_service "https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/TimerService.kt"
click node_domain_model "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/domain.rs"
click node_sync "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/sync.rs"
click node_provider "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/provider.rs"
click node_storage_impl "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/storage.rs"
click node_blob "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/blob.rs"
click node_s3 "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/s3.rs"
click node_crypto "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/crypto.rs"
click node_portable_config "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/portable_config.rs"
click node_python_bindings "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/python/contextswitch_core/__init__.py"
click node_uniffi "https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-uniffi/src/lib.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_cli,node_cli_core,node_cli_manage,node_cli_history,node_cli_reports,node_cli_config,node_android_app,node_android_timer,node_android_log,node_android_manage,node_android_settings,node_android_store,node_timer_service,node_user toneBlue
class node_domain_model,node_sync,node_portable_config,node_local_files,node_s3_service toneAmber
class node_provider,node_storage_impl,node_blob,node_s3,node_crypto toneMint
class node_python_bindings,node_uniffi toneRose
```

## Components

### User clients

- [CLI commands](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/cli.py): `cli/cosw/cli.py`
- [CLI transactions](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/core.py): `cli/cosw/core.py`
- [Project and tag management](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/manage.py): `cli/cosw/manage.py`
- [Span history](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/history.py): `cli/cosw/history.py`
- [Reports](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/reporting.py): `cli/cosw/reporting.py`
- [CLI configuration](https://github.com/chr1st1ank/context-switch/blob/main/cli/cosw/config.py): `cli/cosw/config.py`
- [Android app shell](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/MainActivity.kt): `android/app/src/main/java/dev/contextswitch/MainActivity.kt`
- [Timer screen](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/TimerScreen.kt): `android/app/src/main/java/dev/contextswitch/ui/TimerScreen.kt`
- [Log screen](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/LogScreen.kt): `android/app/src/main/java/dev/contextswitch/ui/LogScreen.kt`
- [Management screen](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/ManageScreen.kt): `android/app/src/main/java/dev/contextswitch/ui/ManageScreen.kt`
- [Settings screen](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/ui/SettingsScreen.kt): `android/app/src/main/java/dev/contextswitch/ui/SettingsScreen.kt`
- [Android logbook store](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/LogbookStore.kt): `android/app/src/main/java/dev/contextswitch/LogbookStore.kt`
- [Foreground timer service](https://github.com/chr1st1ank/context-switch/blob/main/android/app/src/main/java/dev/contextswitch/TimerService.kt): `android/app/src/main/java/dev/contextswitch/TimerService.kt`

### Domain and sync

- [Logbook domain](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/domain.rs): `libs/contextswitch-core/src/domain.rs`
- [Sync coordination](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/sync.rs): `libs/contextswitch-core/src/sync.rs`
- [Portable config](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/portable_config.rs): `libs/contextswitch-core/src/portable_config.rs`

### Storage backends

- [Provider abstraction](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/provider.rs): `libs/contextswitch-core/src/provider.rs`
- [Conditional storage](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/storage.rs): `libs/contextswitch-core/src/storage.rs`
- [Blob stores](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/blob.rs): `libs/contextswitch-core/src/blob.rs`
- [S3-compatible backend](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/s3.rs): `libs/contextswitch-core/src/s3.rs`
- [Envelope encryption](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/src/crypto.rs): `libs/contextswitch-core/src/crypto.rs`

### Language bindings

- [Python bindings](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-core/python/contextswitch_core/__init__.py): `libs/contextswitch-core/python/contextswitch_core/__init__.py`
- [UniFFI interface](https://github.com/chr1st1ank/context-switch/blob/main/libs/contextswitch-uniffi/src/lib.rs): `libs/contextswitch-uniffi/src/lib.rs`

### Other components

- **User**
- **Local filesystem**
- **S3 storage service**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User → Android app shell: uses app (evidence: `README.md`)
- CLI commands → CLI transactions: transacts (evidence: `cli/cosw/cli.py`)
- CLI commands → Project and tag management: dispatches (evidence: `cli/cosw/cli.py`)
- CLI commands → Span history: dispatches (evidence: `cli/cosw/cli.py`)
- CLI commands → CLI configuration: loads config (evidence: `cli/cosw/cli.py`)
- Span history → CLI transactions: reads and mutates (evidence: `cli/cosw/history.py`)
- Project and tag management → CLI transactions: uses transactions (evidence: `cli/cosw/manage.py`)
- Span history → Reports: uses reporting (evidence: `cli/cosw/history.py`)
- Reports → Python bindings: queries logbook (evidence: `cli/cosw/reporting.py`)
- CLI transactions → Python bindings: opens providers (evidence: `cli/cosw/core.py`)
- CLI commands → Python bindings: mutates logbook (evidence: `cli/cosw/cli.py`)
- Android app shell → Timer screen: shows (evidence: `android/app/src/main/java/dev/contextswitch/MainActivity.kt`)
- Android app shell → Log screen: shows (evidence: `android/app/src/main/java/dev/contextswitch/MainActivity.kt`)
- Android app shell → Management screen: shows (evidence: `android/app/src/main/java/dev/contextswitch/MainActivity.kt`)
- Android app shell → Settings screen: shows (evidence: `android/app/src/main/java/dev/contextswitch/MainActivity.kt`)
- Android app shell → Android logbook store: uses store (evidence: `android/app/src/main/java/dev/contextswitch/MainActivity.kt`)
- Android app shell → Foreground timer service: starts or stops (evidence: `android/app/src/main/java/dev/contextswitch/MainActivity.kt`)
- Timer screen → Android logbook store: uses logbook (evidence: `android/app/src/main/java/dev/contextswitch/ui/TimerScreen.kt`)
- Log screen → Android logbook store: reads logbook (evidence: `android/app/src/main/java/dev/contextswitch/ui/LogScreen.kt`)
- Management screen → Android logbook store: manages records (evidence: `android/app/src/main/java/dev/contextswitch/ui/ManageScreen.kt`)
- Settings screen → Android logbook store: uses logbook (evidence: `android/app/src/main/java/dev/contextswitch/ui/SettingsScreen.kt`)
- Foreground timer service → Android logbook store: restores snapshot (evidence: `android/app/src/main/java/dev/contextswitch/TimerService.kt`)
- CLI commands → Logbook domain: applies timer rules (evidence: `README.md`)
- Android logbook store → UniFFI interface: uses shared core (evidence: `README.md`)
- UniFFI interface → Logbook domain: exposes domain (evidence: `README.md`)
- Python bindings → Logbook domain: exposes domain (evidence: `README.md`)
- CLI transactions → Provider abstraction: opens configured provider
- Provider abstraction → Conditional storage: uses storage contract (evidence: `libs/contextswitch-core/src/provider.rs`)
- Conditional storage → Blob stores: reads and writes blobs (evidence: `libs/contextswitch-core/src/storage.rs`)
- Conditional storage → Logbook domain: validates logbook (evidence: `libs/contextswitch-core/src/domain.rs`)
- S3-compatible backend → Blob stores: implements blob store (evidence: `libs/contextswitch-core/src/s3.rs`)
- S3-compatible backend → S3 storage service: sends storage requests (evidence: `libs/contextswitch-core/src/s3.rs`)
- Conditional storage → Local filesystem: stores local data (evidence: `libs/contextswitch-core/src/storage.rs`)
- Provider abstraction → Envelope encryption: configures encryption (evidence: `libs/contextswitch-core/src/provider.rs`)
- Provider abstraction → S3-compatible backend: supports remote backend (evidence: `libs/contextswitch-core/src/provider.rs`)
- Android logbook store → Sync coordination: syncs cached logbook (evidence: `README.md`)
- Sync coordination → Conditional storage: uses versioned storage (evidence: `libs/contextswitch-core/src/sync.rs`)