panatgithub_AnkiHeadingSync/docs/plugin-improvement-audit-architecture-map.md

# Plugin Improvement Audit Architecture Map

## Scope

This map is based on the current production runtime path in the repository as inspected on 2026-04-26. It focuses on active code, active wiring, and code paths that materially affect user-visible sync behavior.

## 1. Active Entry Points

### Runtime entry

- `main.ts`
  - Exports `src/presentation/AnkiHeadingSyncPlugin.ts` as the plugin entry.

### Plugin composition root

- `src/presentation/AnkiHeadingSyncPlugin.ts :: onload()`
  - Creates persistence adapters:
    - `src/infrastructure/obsidian/ObsidianPluginDataStore.ts`
    - `src/infrastructure/persistence/DataJsonPluginConfigRepository.ts`
    - `src/infrastructure/persistence/DataJsonPluginStateRepository.ts`
  - Creates external gateways:
    - `src/infrastructure/anki/AnkiConnectGateway.ts`
    - `src/infrastructure/obsidian/ObsidianVaultGateway.ts`
  - Creates main use cases:
    - `ManualSyncCurrentFileUseCase`
    - `ManualSyncVaultUseCase`
    - `RebuildCardIndexUseCase`
    - `ClearCurrentFileSyncedCardsUseCase`
    - `CleanupEmptyDecksUseCase`
  - Registers commands through `src/presentation/commands/registerCommands.ts`
  - Registers the settings UI through `src/presentation/settings/PluginSettingTab.ts`

### User-visible command surface

- `src/presentation/commands/registerCommands.ts`
  - Registers 4 commands:
    - sync current file
    - sync vault
    - clear current file synced cards
    - cleanup empty decks

### User-visible settings surface

- `src/presentation/settings/PluginSettingTab.ts`
  - Active cards:
    - card types
    - sync content
    - deck
    - scope
    - commands

## 2. Active Runtime Layers

### Presentation

- `src/presentation/AnkiHeadingSyncPlugin.ts`
  - Plugin lifecycle, command callbacks, notices, settings update entry.
- `src/presentation/settings/PluginSettingTab.ts`
  - Settings rendering, note-type cache loading, field-mapping editing, folder-scope editing, deck template insertion button.
- `src/presentation/notices/NoticeService.ts`
  - User-facing success/error summaries.
- `src/presentation/modals/EmptyDeckSelectionModal.ts`
  - Deck cleanup modal.
- `src/presentation/i18n/*`
  - Locale detection and message lookup.

### Application

- `src/application/use-cases/*`
  - Thin user-action entry points over services.
- `src/application/services/ManualSyncService.ts`
  - Main orchestration service for file sync, vault sync, and rebuild index.
- `src/application/services/FileIndexerService.ts`
  - Scope filtering, incremental scan decisions, state-assisted restore of unchanged cards.
- `src/application/services/AnkiBatchExecutor.ts`
  - Batched Anki note create/update/model-migrate/tag-sync/deck-change/media-upload.
- `src/application/services/QaGroupSyncService.ts`
  - QA Group note sync, slot preservation, model mismatch handling, GI marker generation.
- `src/application/services/MarkdownWriteBackService.ts`
  - File-grouped marker writes, conflict capture, pending write-back generation.
- `src/application/services/RenderConfigService.ts`
  - Deck resolution, note-model selection, render-config hashing.
- `src/application/services/NoteFieldMappingService.ts`
  - Saved mapping validation and rendered-field projection.
- `src/application/services/QaGroupFieldMappingService.ts`
  - QA Group slot derivation and validation.

### Domain

- `src/domain/manual-sync/services/CardIndexingService.ts`
  - Heading scanning, card-type detection, ID/GI marker recovery, QA Group and semantic QA parsing.
- `src/domain/manual-sync/services/DiffPlannerService.ts`
  - Create/update/change-deck/rewrite-marker/orphan planning.
- `src/domain/manual-sync/services/CardMarkerService.ts`
  - Card ID marker parse/create/validate/apply.
- `src/domain/manual-sync/services/GroupMarkerService.ts`
  - GI marker parse/create/validate/apply.
- `src/domain/manual-sync/services/DeckExtractionService.ts`
  - YAML/body deck declaration parsing.
- `src/domain/manual-sync/services/DeckResolutionService.ts`
  - Folder/file/default deck resolution and warning generation.
- `src/domain/manual-sync/services/QaGroupBlockParser.ts`
  - QA Group block parsing.
- `src/domain/manual-sync/services/SemanticQaListParser.ts`
  - Semantic QA list parsing.

### Infrastructure

- `src/infrastructure/anki/AnkiConnectGateway.ts`
  - AnkiConnect HTTP adapter and `multi` request batching.
- `src/infrastructure/obsidian/ObsidianVaultGateway.ts`
  - Vault reads, compare-and-swap writes, folder tree, backlinks, media resolution.
- `src/infrastructure/persistence/DataJsonPluginConfigRepository.ts`
  - Settings load/save normalization and validation.
- `src/infrastructure/persistence/DataJsonPluginStateRepository.ts`
  - Plugin state load/save and migration.

## 3. Main Data Flow

### Manual sync: current file

1. Command callback in `registerCommands()` calls `AnkiHeadingSyncPlugin.runSyncCurrentFile()`.
2. `ManualSyncCurrentFileUseCase.execute()` forwards to `ManualSyncService.syncFile()`.
3. `ManualSyncService.syncFile()` validates settings and scope, then loads plugin state.
4. `FileIndexerService.indexFile()` reads the target Markdown file and delegates parsing to `CardIndexingService.index()`.
5. `DiffPlannerService.plan()` compares indexed cards with persisted state.
6. `AnkiBatchExecutor.execute()` syncs ordinary/basic/cloze/semantic cards.
7. `QaGroupSyncService.sync()` syncs QA Group blocks separately.
8. `MarkdownWriteBackService.write()` writes card ID markers and GI markers back into Markdown.
9. `ManualSyncService.buildNextState()` saves files/cards/groupBlocks/pending write-back into plugin state.
10. `NoticeService.showSyncSummary()` renders a localized summary.

### Manual sync: vault

1. `ManualSyncVaultUseCase.execute()` forwards to `ManualSyncService.syncVault()`.
2. `FileIndexerService.indexVault()` uses `ScanScopeService` plus `ObsidianVaultGateway.listMarkdownFileRefs()` to enumerate in-scope files.
3. Incremental decisions are made per file using file stamp, deck-rule fingerprint, missing known cards, and pending write-back state.
4. Remaining flow matches current-file sync.

### Rebuild index

1. `RebuildCardIndexUseCase.execute()` forwards to `ManualSyncService.rebuildIndex()`.
2. Vault is reindexed with `forceReadAll = true`.
3. No Anki note create/update occurs.
4. Existing markers can still be rewritten if enough identity exists.
5. Persisted state is rebuilt from indexed files plus recovered QA Group state.

### Clear current file synced cards

1. `ClearCurrentFileSyncedCardsUseCase.hasTrackedCards()` checks local state for current file.
2. `execute()` loads note IDs/group IDs from local state.
3. Anki notes are deleted through `AnkiGateway.deleteNotes()`.
4. Markdown markers are removed through `MarkdownSyncedMarkerRemovalService`.
5. Local state is rewritten without that file’s cards/groups.

## 4. Critical State Objects

### Settings

- `src/application/config/PluginSettings.ts :: PluginSettings`
  - Controls note-type selection, field mapping caches, deck logic, scope logic, backlink behavior, tag sync, and AnkiConnect URL.
  - Contains both current `cardTypeConfigs` and legacy mirrored note-type fields.

### Persisted plugin state

- `src/domain/manual-sync/entities/PluginState.ts :: PluginState`
  - `files`
    - Per-file index metadata: `fileHash`, `fileStamp`, `deckRulesFingerprint`, `noteIds`, `groupIds`.
  - `cards`
    - Per-note synced card snapshot keyed by note ID.
  - `groupBlocks`
    - Per-QA-group synced snapshot keyed by group ID.
  - `pendingWriteBack`
    - Deferred marker writes intended for conflict recovery.

### Scan-time objects

- `IndexedCard`
- `IndexedGroupCardBlock`
- `IndexedFile`

### Plan-time objects

- `src/domain/manual-sync/value-objects/ManualSyncPlan.ts :: ManualSyncPlan`
  - `toCreate`
  - `toUpdate`
  - `toVerifyDeck`
  - `toChangeDeck`
  - `toRewriteMarker`
  - `toOrphan`

## 5. Main External API Boundaries

### Obsidian APIs

- `Plugin.loadData()` / `Plugin.saveData()` through `ObsidianPluginDataStore`
- Vault file enumeration through `ObsidianVaultGateway.listMarkdownFileRefs()`
- Compare-and-swap write boundary through `ObsidianVaultGateway.replaceMarkdownFile()`
- Metadata and tag extraction through `getAllTags()` and cached metadata
- Obsidian notices and settings controls in presentation layer

### AnkiConnect

- All network calls are centralized in `AnkiConnectGateway.invoke()` / `invokeMulti()`.
- The adapter uses AnkiConnect action names directly (`modelNames`, `deckNamesAndIds`, `getDeckStats`, `addNote`, `updateNoteFields`, `changeDeck`, `deleteDecks`, `storeMediaFile`, `multi`, etc.).

## 6. Active Code vs Likely Legacy / Dormant Remnants

### Clearly active

- `main.ts`
- `src/presentation/AnkiHeadingSyncPlugin.ts`
- `src/presentation/settings/PluginSettingTab.ts`
- `src/application/services/ManualSyncService.ts`
- `src/application/services/FileIndexerService.ts`
- `src/application/services/AnkiBatchExecutor.ts`
- `src/application/services/QaGroupSyncService.ts`
- `src/infrastructure/anki/AnkiConnectGateway.ts`
- `src/infrastructure/obsidian/ObsidianVaultGateway.ts`

### Generated or packaging artifacts

- `main.js`
  - Root-level generated bundle copy written by `esbuild.config.mjs`.
- `dist/plugin/*`
  - Staged package output used for release/manual sync.

### Debug / manual inspection scripts

- `query_note.js`
- `query_notes.js`
  - Direct HTTP scripts with hard-coded note IDs and no repository call sites.

### Likely dormant or legacy architectural branches

- `src/application/services/QaGroupModelService.ts`
- `src/application/services/QaGroupModelDefinition.ts`
- `src/application/config/ManagedNoteModels.ts`
  - These define and test a managed `ObsiAnki QA Group 12` model, but no production runtime call site invokes `QaGroupModelService.ensureModel()`.
  - The active runtime QA Group path instead uses user-selected note types plus `QaGroupFieldMappingService`.

- `src/presentation/AnkiHeadingSyncPlugin.ts :: runRebuildCardIndex()`
  - Wired in plugin initialization, but not surfaced by `registerCommands()` and not listed in the settings command card.

- Legacy mirrored settings fields in `PluginSettings`
  - `qaHeadingLevel`, `clozeHeadingLevel`, `qaGroupMarker`, `qaNoteType`, `clozeNoteType`, `semanticQaMarker`, `semanticQaNoteType`
  - Still exist and are derived from `cardTypeConfigs`, which indicates an unfinished migration rather than a clean single source of truth.

## 7. Audit Notes

- The active sync engine is stateful and layered.
- The highest-value audit attention should stay on:
  - pending write-back persistence
  - QA Group authority split
  - semantic QA runtime/UI parity
  - AnkiConnect failure handling
  - hidden rebuild/recovery surface