# antigluten/amgi architecture

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

- Interactive diagram: https://gitdiagram.com/antigluten/amgi
- Repository: https://github.com/antigluten/amgi

## Overview

Amgi is an offline-first, Anki-compatible flashcard app for iOS, with watchOS and widget companions. The main workflow is to manage decks and cards, study a scheduled review queue, and sync collection changes with a compatible server. The SwiftUI features call dependency-client interfaces, which lead through service facades and typed protobuf requests to Anki’s Rust engine. Other major capabilities include browsing and editing cards, EPUB reading with offline dictionary lookup, statistics, templates, image occlusion, and Shortcuts. Some feature-level links are documented rather than verified in sampled implementation excerpts.

Main entry points: [`Sources/AnkiClients`](https://github.com/antigluten/amgi/tree/main/Sources/AnkiClients) (Dependency clients), [`AmgiFeatures/Sources/RootFeature/RootView.swift`](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/RootFeature/RootView.swift) (App shell), [`AmgiFeatures/Sources/ReaderFeature/Reader/EPUBChapterPageController.swift`](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/ReaderFeature/Reader/EPUBChapterPageController.swift) (EPUB reader), [`AmgiFeatures/Sources/ReviewCore/ReviewSession.swift`](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/ReviewCore/ReviewSession.swift) (Review session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_app["App shell<br/>[RootView.swift]"]
  node_decks["Deck management<br/>[DeckListView.swift]"]
  node_review["Review session"]
  node_browse["Browse and edit<br/>[BrowseView.swift]"]
  node_templates["Template editing"]
  node_stats["Statistics"]
  node_sync["Sync flow"]
  node_theme["Theme system<br/>[ThemeManager.swift]"]
end

subgraph group_reader["Reading"]
  node_reader["EPUB reader"]
  node_bookclient["Reader book client"]
  node_dictionary["Dictionary lookup"]
  node_epubparser["EPUB parsing"]
end

subgraph group_domain["Anki domain"]
  node_clients["Dependency clients"]
  node_services["Service facades"]
  node_domainmodels["Domain models"]
  node_cardrender["Card rendering"]
end

subgraph group_backend["Backend bridge"]
  node_backend["Backend wrapper<br/>[AnkiBackend.swift]"]
  node_proto["Protobuf bridge"]
  node_rust["Anki Rust engine<br/>[lib.rs]"]
  node_storage[("Collection storage")]
end

subgraph group_companions["Companions"]
  node_widget["Home widgets"]
  node_watch["Watch app"]
  node_shortcuts["Shortcuts"]
end

node_user(("Learner"))
node_syncserver(("Sync server"))

node_user -.->|"uses"| node_app
node_app -.->|"routes to"| node_decks
node_app -.->|"routes to"| node_review
node_app -.->|"routes to"| node_browse
node_app -.->|"routes to"| node_stats
node_app -.->|"routes to"| node_sync
node_decks -->|"requests data"| node_clients
node_review -->|"requests review data"| node_clients
node_review -->|"prepares cards"| node_cardrender
node_browse -.->|"requests data"| node_clients
node_templates -.->|"requests data"| node_clients
node_stats -.->|"requests data"| node_clients
node_sync -->|"calls"| node_clients
node_sync -->|"synchronizes"| node_syncserver
node_reader -.->|"loads books"| node_bookclient
node_reader -.->|"looks up text"| node_dictionary
node_reader -.->|"opens EPUB"| node_epubparser
node_bookclient -->|"uses note clients"| node_clients
node_bookclient -->|"assembles books"| node_domainmodels
node_clients -->|"calls"| node_services
node_services -->|"invokes"| node_backend
node_backend -->|"dispatches requests"| node_proto
node_proto -->|"bridges calls"| node_rust
node_rust -->|"reads and writes"| node_storage
node_theme -.->|"supplies appearance"| node_app
node_widget -.->|"shows due counts"| node_storage
node_watch -->|"runs engine"| node_rust
node_shortcuts -.->|"requests actions"| node_clients

click node_app "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/RootFeature/RootView.swift"
click node_decks "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/DecksFeature/DeckList/DeckListView.swift"
click node_review "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/ReviewCore/ReviewSession.swift"
click node_browse "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/BrowseFeature/BrowseView.swift"
click node_templates "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/TemplatesFeature/TemplateEditorView.swift"
click node_stats "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/StatsFeature/StatsDashboardView.swift"
click node_sync "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/SyncFeature/SyncCoordinator.swift"
click node_reader "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/ReaderFeature/Reader/EPUBChapterPageController.swift"
click node_bookclient "https://github.com/antigluten/amgi/blob/main/Sources/AnkiClients/ReaderBookClient%2BLive.swift"
click node_dictionary "https://github.com/antigluten/amgi/blob/main/AmgiReader/Sources/ReaderDictionary/DictionaryLookupRuntime.swift"
click node_epubparser "https://github.com/antigluten/amgi/blob/main/AmgiReader/Sources/ReaderEPUB/EPUBBookParser.swift"
click node_clients "https://github.com/antigluten/amgi/tree/main/Sources/AnkiClients"
click node_services "https://github.com/antigluten/amgi/tree/main/Sources/AnkiServices"
click node_domainmodels "https://github.com/antigluten/amgi/tree/main/Sources/AnkiKit"
click node_cardrender "https://github.com/antigluten/amgi/blob/main/Sources/AmgiCardWeb/CardRenderEngine.swift"
click node_backend "https://github.com/antigluten/amgi/blob/main/Sources/AnkiBackend/AnkiBackend.swift"
click node_proto "https://github.com/antigluten/amgi/blob/main/Sources/AnkiProtoBridge/ServiceCatalog.swift"
click node_rust "https://github.com/antigluten/amgi/blob/main/anki-bridge-rs/src/lib.rs"
click node_theme "https://github.com/antigluten/amgi/blob/main/AmgiUI/Sources/Theme/ThemeManager.swift"
click node_widget "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/WidgetFeature/WidgetTimelineProvider.swift"
click node_watch "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/WatchFeature/WatchContentView.swift"
click node_shortcuts "https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/IntentsFeature/StudyDeckIntent.swift"

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_app,node_decks,node_review,node_browse,node_templates,node_stats,node_sync,node_theme toneBlue
class node_reader,node_bookclient,node_dictionary,node_epubparser toneAmber
class node_clients,node_services,node_domainmodels,node_cardrender,node_syncserver toneMint
class node_backend,node_proto,node_rust,node_storage toneRose
class node_widget,node_watch,node_shortcuts,node_user toneIndigo
```

## Components

### App experience

- [App shell](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/RootFeature/RootView.swift): `AmgiFeatures/Sources/RootFeature/RootView.swift`
- [Deck management](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/DecksFeature/DeckList/DeckListView.swift): `AmgiFeatures/Sources/DecksFeature/DeckList/DeckListView.swift`
- [Review session](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/ReviewCore/ReviewSession.swift): `AmgiFeatures/Sources/ReviewCore/ReviewSession.swift`
- [Browse and edit](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/BrowseFeature/BrowseView.swift): `AmgiFeatures/Sources/BrowseFeature/BrowseView.swift`
- [Template editing](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/TemplatesFeature/TemplateEditorView.swift): `AmgiFeatures/Sources/TemplatesFeature/TemplateEditorView.swift`
- [Statistics](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/StatsFeature/StatsDashboardView.swift): `AmgiFeatures/Sources/StatsFeature/StatsDashboardView.swift`
- [Sync flow](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/SyncFeature/SyncCoordinator.swift): `AmgiFeatures/Sources/SyncFeature/SyncCoordinator.swift`
- [Theme system](https://github.com/antigluten/amgi/blob/main/AmgiUI/Sources/Theme/ThemeManager.swift): `AmgiUI/Sources/Theme/ThemeManager.swift`

### Reading

- [EPUB reader](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/ReaderFeature/Reader/EPUBChapterPageController.swift): `AmgiFeatures/Sources/ReaderFeature/Reader/EPUBChapterPageController.swift`
- [Reader book client](https://github.com/antigluten/amgi/blob/main/Sources/AnkiClients/ReaderBookClient%2BLive.swift): `Sources/AnkiClients/ReaderBookClient+Live.swift`
- [Dictionary lookup](https://github.com/antigluten/amgi/blob/main/AmgiReader/Sources/ReaderDictionary/DictionaryLookupRuntime.swift): `AmgiReader/Sources/ReaderDictionary/DictionaryLookupRuntime.swift`
- [EPUB parsing](https://github.com/antigluten/amgi/blob/main/AmgiReader/Sources/ReaderEPUB/EPUBBookParser.swift): `AmgiReader/Sources/ReaderEPUB/EPUBBookParser.swift`

### Anki domain

- [Dependency clients](https://github.com/antigluten/amgi/tree/main/Sources/AnkiClients): `Sources/AnkiClients`
- [Service facades](https://github.com/antigluten/amgi/tree/main/Sources/AnkiServices): `Sources/AnkiServices`
- [Domain models](https://github.com/antigluten/amgi/tree/main/Sources/AnkiKit): `Sources/AnkiKit`
- [Card rendering](https://github.com/antigluten/amgi/blob/main/Sources/AmgiCardWeb/CardRenderEngine.swift): `Sources/AmgiCardWeb/CardRenderEngine.swift`

### Backend bridge

- [Backend wrapper](https://github.com/antigluten/amgi/blob/main/Sources/AnkiBackend/AnkiBackend.swift): `Sources/AnkiBackend/AnkiBackend.swift`
- [Protobuf bridge](https://github.com/antigluten/amgi/blob/main/Sources/AnkiProtoBridge/ServiceCatalog.swift): `Sources/AnkiProtoBridge/ServiceCatalog.swift`
- [Anki Rust engine](https://github.com/antigluten/amgi/blob/main/anki-bridge-rs/src/lib.rs): `anki-bridge-rs/src/lib.rs`
- **Collection storage**

### Companions

- [Home widgets](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/WidgetFeature/WidgetTimelineProvider.swift): `AmgiFeatures/Sources/WidgetFeature/WidgetTimelineProvider.swift`
- [Watch app](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/WatchFeature/WatchContentView.swift): `AmgiFeatures/Sources/WatchFeature/WatchContentView.swift`
- [Shortcuts](https://github.com/antigluten/amgi/blob/main/AmgiFeatures/Sources/IntentsFeature/StudyDeckIntent.swift): `AmgiFeatures/Sources/IntentsFeature/StudyDeckIntent.swift`

### Other components

- **Learner**
- **Sync server**

## Connections

- Learner → App shell: uses
- App shell → Deck management: routes to
- App shell → Review session: routes to
- App shell → Browse and edit: routes to
- App shell → Statistics: routes to
- App shell → Sync flow: routes to
- Deck management → Dependency clients: requests data (evidence: `README.md`)
- Review session → Dependency clients: requests review data (evidence: `README.md`)
- Review session → Card rendering: prepares cards (evidence: `AmgiFeatures/Sources/ReviewCore/ReviewSession.swift`)
- Browse and edit → Dependency clients: requests data
- Template editing → Dependency clients: requests data
- Statistics → Dependency clients: requests data
- Sync flow → Dependency clients: calls (evidence: `AmgiFeatures/Sources/SyncFeature/SyncCoordinator.swift`)
- Sync flow → Sync server: synchronizes (evidence: `README.md`)
- EPUB reader → Reader book client: loads books
- EPUB reader → Dictionary lookup: looks up text
- EPUB reader → EPUB parsing: opens EPUB
- Reader book client → Dependency clients: uses note clients (evidence: `Sources/AnkiClients/ReaderBookClient+Live.swift`)
- Reader book client → Domain models: assembles books (evidence: `Sources/AnkiClients/ReaderBookClient+Live.swift`)
- Dependency clients → Service facades: calls (evidence: `README.md`)
- Service facades → Backend wrapper: invokes (evidence: `Sources/AnkiServices/DecksService.swift`)
- Backend wrapper → Protobuf bridge: dispatches requests (evidence: `README.md`)
- Protobuf bridge → Anki Rust engine: bridges calls (evidence: `README.md`)
- Anki Rust engine → Collection storage: reads and writes (evidence: `README.md`)
- Theme system → App shell: supplies appearance
- Home widgets → Collection storage: shows due counts
- Watch app → Anki Rust engine: runs engine (evidence: `README.md`)
- Shortcuts → Dependency clients: requests actions
