# ankitects/anki architecture

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

- Interactive diagram: https://gitdiagram.com/ankitects/anki
- Repository: https://github.com/ankitects/anki

## Overview

#### Purpose and Entry Points
Anki is the desktop spaced-repetition application. Its primary runtime is a Python/Qt desktop client backed by Rust domain logic and SQLite storage. Desktop startup is packaged through `qt/runanki.py` and `qt/installer/app/src/anki/__main__.py`; the Qt application shell is centered in `qt/aqt/main.py`.

#### Desktop Presentation Layer
The `aqt` Python package owns native Qt windows, user interaction, profiles, background tasks, and add-on integration. It orchestrates domain calls rather than implementing most collection logic. Key surfaces include study/review (`qt/aqt/reviewer.py`), card browsing (`qt/aqt/browser/browser.py`), and note editing (`qt/aqt/editor.py`). Web content is embedded in Qt WebViews and locally served media (`qt/aqt/webview.py`, `qt/aqt/mediasrv.py`).

#### Rust Collection Core and Persistence
`rslib` is the authoritative domain layer: collections, notes, cards, decks, notetypes, undo, imports, search, scheduling, statistics, and sync. `rslib/src/collection/mod.rs` establishes collection lifecycle and transactional behavior; domain services expose operations around it. Storage is SQLite-oriented, with schema/migrations and SQL-backed repositories under `rslib/src/storage/sqlite.rs`, `rslib/src/storage/schema11.sql`, and `rslib/src/storage/upgrades/`.

#### Cross-Language API Boundary
Python calls Rust through generated protobuf-oriented backend APIs, not by directly owning core business rules. The public contract begins in `proto/anki/backend.proto`; Rust request handlers are grouped in `rslib/src/backend/mod.rs`; Python bridge/client code is in `pylib/anki/_backend.py` and `pylib/anki/rsbackend.py`. `pylib/rsbridge/lib.rs` provides the native Rust/Python bridge. This is the critical compatibility boundary for the desktop UI, Python library, and add-ons.

#### Study, Rendering, and Web UI Flow
A review action flows from Qt or TypeScript UI through the bridge to Rust scheduling, which selects/answers cards, writes card/review-log changes transactionally, and returns state/rendering data. Scheduling and FSRS behavior reside in `rslib/src/scheduler/mod.rs`, `rslib/src/scheduler/answering/mod.rs`, and `rslib/src/scheduler/fsrs/mod.rs`. Card-template rendering is in `rslib/src/card_rendering/service.rs`. Modern embedded UI is Svelte/TypeScript: reviewer code is `ts/reviewer/index.ts`; routed screens such as editor and deck options are in `ts/routes/editor/+page.svelte` and `ts/routes/deck-options/[deckId]/+page.svelte`.

#### Sync and External Integrations
Collection and media sync use HTTP protocol clients against AnkiWeb-compatible services, with optional server runtime. Client sync logic is in `rslib/src/sync/collection/mod.rs` and `rslib/src/sync/media/syncer.rs`; HTTP transport is `rslib/src/sync/http_client/mod.rs`. The standalone sync server binary starts at `rslib/sync/main.rs`, with server routes/handlers under `rslib/src/sync/http_server/`. Separate integrations include AnkiHub (`rslib/src/ankihub/mod.rs`) and AnkiDroid services (`rslib/src/ankidroid/service.rs`).

#### Build, Generated Contracts, and Distribution
This is a multi-runtime build: Rust, Python, Qt 6, Node/TypeScript/Svelte, protobuf, Sass, and platform packaging. Rust build configuration generates Ninja workflows from `build/configure/src/main.rs` and `build/ninja_gen/src/lib.rs`. Protobuf definitions in `proto/anki/` generate language bindings; Fluent localization sources in `ftl/core/` are compiled/consumed by Rust and frontend layers. Release packaging targets Windows, macOS, and Linux via `qt/installer/`, while CI/release automation runs in `.github/workflows/ci.yml` and `.github/workflows/release.yml`.

Main entry points: [`rslib/src/collection/mod.rs`](https://github.com/ankitects/anki/blob/main/rslib/src/collection/mod.rs) (Collection domain), [`pylib/anki/_backend.py`](https://github.com/ankitects/anki/blob/main/pylib/anki/_backend.py) (Python backend client), [`proto/anki/backend.proto`](https://github.com/ankitects/anki/blob/main/proto/anki/backend.proto) (Backend protobuf contract), [`qt/aqt/reviewer.py`](https://github.com/ankitects/anki/blob/main/qt/aqt/reviewer.py) (Study, browser, editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_startup["Desktop startup<br/>Python entry point<br/>[runanki.py]"]
  node_qt_shell["Qt application shell<br/>Python/Qt<br/>[main.py]"]
  node_desktop_surfaces["Study, browser, editor<br/>Qt UI<br/>[reviewer.py]"]
  node_webview["Embedded web UI<br/>Qt WebView<br/>[webview.py]"]
  node_reviewer_ui["Reviewer frontend<br/>TypeScript<br/>[index.ts]"]
  node_routes_ui["Editor and deck routes<br/>Svelte<br/>[+page.svelte]"]
  node_python_client["Python backend client<br/>Python bridge client<br/>[_backend.py]"]
  node_native_bridge{{"Rust/Python bridge<br/>Native extension<br/>[lib.rs]"}}
end

subgraph group_core["Rust core"]
  node_backend_contract["Backend protobuf contract<br/>Protobuf API<br/>[backend.proto]"]
  node_backend_handlers["Backend request handlers<br/>Rust API<br/>[mod.rs]"]
  node_collection["Collection domain<br/>Rust domain core<br/>[mod.rs]"]
  node_scheduler["Scheduler and FSRS<br/>Rust scheduling<br/>[mod.rs]"]
  node_rendering["Card rendering<br/>Rust rendering<br/>[service.rs]"]
  node_sqlite[("SQLite storage<br/>Persistence<br/>[sqlite.rs]")]
end

subgraph group_sync["Sync services"]
  node_sync_client["Collection and media sync<br/>Rust sync client<br/>[mod.rs]"]
  node_http_transport["Sync HTTP transport<br/>Rust HTTP client<br/>[mod.rs]"]
  node_sync_server["Standalone sync server<br/>Rust server binary<br/>[main.rs]"]
  node_ankiweb(("AnkiWeb-compatible service<br/>Remote sync service"))
end

subgraph group_build["Build and release"]
  node_build_generator["Ninja build generator<br/>Rust build tooling<br/>[main.rs]"]
  node_generated_bindings["Generated language bindings<br/>Build artifact"]
  node_packaging["Platform packaging<br/>Release packaging"]
  node_ci_release["CI and release automation<br/>GitHub Actions<br/>[ci.yml]"]
end

node_startup -->|"launches"| node_qt_shell
node_qt_shell -->|"hosts"| node_desktop_surfaces
node_desktop_surfaces -->|"embeds"| node_webview
node_webview -->|"serves"| node_reviewer_ui
node_webview -->|"serves"| node_routes_ui
node_desktop_surfaces -->|"domain requests"| node_python_client
node_reviewer_ui -->|"review actions"| node_python_client
node_python_client -->|"invokes"| node_native_bridge
node_native_bridge -->|"dispatches requests"| node_backend_handlers
node_backend_contract -.->|"generates API"| node_python_client
node_backend_contract -.->|"defines requests"| node_backend_handlers
node_backend_handlers -->|"orchestrates"| node_collection
node_collection -->|"study operations"| node_scheduler
node_scheduler -->|"returns card state"| node_rendering
node_collection -->|"transactional reads/writes"| node_sqlite
node_collection -->|"synchronizes"| node_sync_client
node_sync_client -->|"uses"| node_http_transport
node_http_transport -->|"HTTP protocol"| node_ankiweb
node_sync_server -.->|"server implementation"| node_ankiweb
node_build_generator -->|"build workflow"| node_generated_bindings
node_backend_contract -->|"source definitions"| node_generated_bindings
node_generated_bindings -.->|"binds contract"| node_native_bridge
node_build_generator -->|"produces release inputs"| node_packaging
node_ci_release -->|"publishes"| node_packaging

click node_startup "https://github.com/ankitects/anki/blob/main/qt/runanki.py"
click node_qt_shell "https://github.com/ankitects/anki/blob/main/qt/aqt/main.py"
click node_desktop_surfaces "https://github.com/ankitects/anki/blob/main/qt/aqt/reviewer.py"
click node_webview "https://github.com/ankitects/anki/blob/main/qt/aqt/webview.py"
click node_reviewer_ui "https://github.com/ankitects/anki/blob/main/ts/reviewer/index.ts"
click node_routes_ui "https://github.com/ankitects/anki/blob/main/ts/routes/editor/%2Bpage.svelte"
click node_python_client "https://github.com/ankitects/anki/blob/main/pylib/anki/_backend.py"
click node_native_bridge "https://github.com/ankitects/anki/blob/main/pylib/rsbridge/lib.rs"
click node_backend_contract "https://github.com/ankitects/anki/blob/main/proto/anki/backend.proto"
click node_backend_handlers "https://github.com/ankitects/anki/blob/main/rslib/src/backend/mod.rs"
click node_collection "https://github.com/ankitects/anki/blob/main/rslib/src/collection/mod.rs"
click node_scheduler "https://github.com/ankitects/anki/blob/main/rslib/src/scheduler/mod.rs"
click node_rendering "https://github.com/ankitects/anki/blob/main/rslib/src/card_rendering/service.rs"
click node_sqlite "https://github.com/ankitects/anki/blob/main/rslib/src/storage/sqlite.rs"
click node_sync_client "https://github.com/ankitects/anki/blob/main/rslib/src/sync/collection/mod.rs"
click node_http_transport "https://github.com/ankitects/anki/blob/main/rslib/src/sync/http_client/mod.rs"
click node_sync_server "https://github.com/ankitects/anki/blob/main/rslib/sync/main.rs"
click node_build_generator "https://github.com/ankitects/anki/blob/main/build/configure/src/main.rs"
click node_ci_release "https://github.com/ankitects/anki/blob/main/.github/workflows/ci.yml"

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_startup,node_qt_shell,node_desktop_surfaces,node_webview,node_reviewer_ui,node_routes_ui,node_python_client,node_native_bridge toneBlue
class node_backend_contract,node_backend_handlers,node_collection,node_scheduler,node_rendering,node_sqlite toneAmber
class node_sync_client,node_http_transport,node_sync_server,node_ankiweb toneMint
class node_build_generator,node_generated_bindings,node_packaging,node_ci_release toneRose
```

## Components

### Desktop client

- [Desktop startup](https://github.com/ankitects/anki/blob/main/qt/runanki.py): Python entry point · `qt/runanki.py`
- [Qt application shell](https://github.com/ankitects/anki/blob/main/qt/aqt/main.py): Python/Qt · `qt/aqt/main.py`
- [Study, browser, editor](https://github.com/ankitects/anki/blob/main/qt/aqt/reviewer.py): Qt UI · Primary native interaction surfaces. · `qt/aqt/reviewer.py`
- [Embedded web UI](https://github.com/ankitects/anki/blob/main/qt/aqt/webview.py): Qt WebView · Hosts local web content and media. · `qt/aqt/webview.py`
- [Reviewer frontend](https://github.com/ankitects/anki/blob/main/ts/reviewer/index.ts): TypeScript · `ts/reviewer/index.ts`
- [Editor and deck routes](https://github.com/ankitects/anki/blob/main/ts/routes/editor/%2Bpage.svelte): Svelte · `ts/routes/editor/+page.svelte`
- [Python backend client](https://github.com/ankitects/anki/blob/main/pylib/anki/_backend.py): Python bridge client · `pylib/anki/_backend.py`
- [Rust/Python bridge](https://github.com/ankitects/anki/blob/main/pylib/rsbridge/lib.rs): Native extension · `pylib/rsbridge/lib.rs`

### Rust core

- [Backend protobuf contract](https://github.com/ankitects/anki/blob/main/proto/anki/backend.proto): Protobuf API · Compatibility boundary for Python, UI, and add-ons. · `proto/anki/backend.proto`
- [Backend request handlers](https://github.com/ankitects/anki/blob/main/rslib/src/backend/mod.rs): Rust API · `rslib/src/backend/mod.rs`
- [Collection domain](https://github.com/ankitects/anki/blob/main/rslib/src/collection/mod.rs): Rust domain core · Owns collection lifecycle and transactions. · `rslib/src/collection/mod.rs`
- [Scheduler and FSRS](https://github.com/ankitects/anki/blob/main/rslib/src/scheduler/mod.rs): Rust scheduling · Selects and answers study cards. · `rslib/src/scheduler/mod.rs`
- [Card rendering](https://github.com/ankitects/anki/blob/main/rslib/src/card_rendering/service.rs): Rust rendering · `rslib/src/card_rendering/service.rs`
- [SQLite storage](https://github.com/ankitects/anki/blob/main/rslib/src/storage/sqlite.rs): Persistence · Schema, migrations, and SQL repositories. · `rslib/src/storage/sqlite.rs`

### Sync services

- [Collection and media sync](https://github.com/ankitects/anki/blob/main/rslib/src/sync/collection/mod.rs): Rust sync client · `rslib/src/sync/collection/mod.rs`
- [Sync HTTP transport](https://github.com/ankitects/anki/blob/main/rslib/src/sync/http_client/mod.rs): Rust HTTP client · `rslib/src/sync/http_client/mod.rs`
- [Standalone sync server](https://github.com/ankitects/anki/blob/main/rslib/sync/main.rs): Rust server binary · `rslib/sync/main.rs`
- **AnkiWeb-compatible service**: Remote sync service

### Build and release

- [Ninja build generator](https://github.com/ankitects/anki/blob/main/build/configure/src/main.rs): Rust build tooling · `build/configure/src/main.rs`
- **Generated language bindings**: Build artifact · Generated from protobuf contracts.
- **Platform packaging**: Release packaging · Builds Windows, macOS, and Linux distributions.
- [CI and release automation](https://github.com/ankitects/anki/blob/main/.github/workflows/ci.yml): GitHub Actions · `.github/workflows/ci.yml`

## Connections

- Desktop startup → Qt application shell: launches
- Qt application shell → Study, browser, editor: hosts
- Study, browser, editor → Embedded web UI: embeds
- Embedded web UI → Reviewer frontend: serves
- Embedded web UI → Editor and deck routes: serves
- Study, browser, editor → Python backend client: domain requests
- Reviewer frontend → Python backend client: review actions
- Python backend client → Rust/Python bridge: invokes
- Rust/Python bridge → Backend request handlers: dispatches requests
- Backend protobuf contract → Python backend client: generates API
- Backend protobuf contract → Backend request handlers: defines requests
- Backend request handlers → Collection domain: orchestrates
- Collection domain → Scheduler and FSRS: study operations
- Scheduler and FSRS → Card rendering: returns card state
- Collection domain → SQLite storage: transactional reads/writes
- Collection domain → Collection and media sync: synchronizes
- Collection and media sync → Sync HTTP transport: uses
- Sync HTTP transport → AnkiWeb-compatible service: HTTP protocol
- Standalone sync server → AnkiWeb-compatible service: server implementation
- Ninja build generator → Generated language bindings: build workflow
- Backend protobuf contract → Generated language bindings: source definitions
- Generated language bindings → Rust/Python bridge: binds contract
- Ninja build generator → Platform packaging: produces release inputs
- CI and release automation → Platform packaging: publishes
