# iikuzmychov/bidirectionaldictionary architecture

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

- Interactive diagram: https://gitdiagram.com/iikuzmychov/bidirectionaldictionary
- Repository: https://github.com/iikuzmychov/bidirectionaldictionary

## Overview

1. This repository is a .NET class library, not an application. Its main product is a bidirectional dictionary package that lets you look up `key -> value` and `value -> key` with the same data structure.

2. The core architecture centers on three implementation types under `src/BidirectionalDictionary/Types`:
   - `BidirectionalDictionary<TKey, TValue>`: the mutable in-memory implementation.
   - `ConcurrentBidirectionalDictionary<TKey, TValue>`: the thread-safe implementation.
   - `ReadOnlyBidirectionalDictionary<TKey, TValue>`: a wrapper that exposes read-only access while preserving inverse lookup.

3. The fundamental data-flow is symmetric indexing: inserts and removals must keep two internal views in sync, one for forward lookup and one for reverse lookup. That is the key architectural constraint of the library.

4. The package exposes abstraction boundaries through two interfaces in `src/BidirectionalDictionary/Interfaces`:
   - `IBidirectionalDictionary<TKey, TValue>`
   - `IReadOnlyBidirectionalDictionary<TKey, TValue>`
   These allow consumers to program against contracts while swapping between mutable, concurrent, and read-only implementations.

5. The public API surface is intentionally broad and dictionary-like. The concrete types implement standard collection contracts such as dictionary/enumerable behavior, and the repository has separate test coverage for:
   - dictionary access
   - read-only dictionary access
   - enumeration
   - key collections
   - value collections
   - inverse views via `Inverse`

6. The read-only model is a wrapper, not a copy. `ReadOnlyBidirectionalDictionary` and `AsReadOnly()` share the same underlying data with the mutable source, but block mutation through the read-only API. That makes the read-only boundary a facade over the same storage.

7. The concurrent implementation is a distinct subsystem with different synchronization behavior. The README states that reads are lock-free and writes use fine-grained stripe locks rather than a single global lock, so the concurrency boundary is localized around mutation while keeping lookup fast.

8. The `Extensions` folder adds LINQ-based creation helpers. These extension methods convert:
   - `IEnumerable<KeyValuePair<TKey, TValue>>`
   - tuple sequences
   - arbitrary sequences with selector functions
   into a bidirectional dictionary. This is a construction pipeline into the core types, not a separate data model.

9. The `DebugViews` folder contains debugger-only visualization helpers for dictionary items, keys, and values. These do not affect runtime behavior, but they improve inspectability and are part of the developer experience boundary around the collections.

10. The library is multi-targeted. The `PublicAPI` folders for `netstandard2.0`, `netstandard2.1`, `net6.0`, and `net9.0` indicate version-specific API baselines and shipped/unshipped public surface tracking. This is important for compatibility management and release discipline.

11. Testing is a major part of the architecture. `tests/BidirectionalDictionary.Tests` is organized by implementation type and by contract, with separate suites for the mutable, concurrent, and read-only variants. There are also specialized enumerator and collection tests, showing that enumeration semantics are treated as first-class behavior.

12. Concurrency validation is stronger than ordinary unit tests. The concurrent dictionary has stress tests and a Coyote-based test file, which indicates model/checker-based exploration of multithreaded behavior in addition to conventional test cases.

13. Benchmarking is an explicit subsystem under `benchmarks/BidirectionalDictionary.Benchmarks`. It contains separate benchmark classes for the mutable, concurrent, and read-only implementations, suggesting the project compares lookup and mutation costs across variants rather than optimizing a single path in isolation.

14. The repo is packaged and released through CI. GitHub Actions workflows exist for CI and publishing, and `codecov.yml` plus the badge in the README show coverage reporting is part of the build pipeline. The overall lifecycle is: source code → tests/benchmarks/coverage → packaged NuGet release.

15. For an architecture diagram, the most important boundaries are:
   - external consumers using the NuGet package
   - the core bidirectional indexing engine
   - the read-only wrapper boundary
   - the concurrent synchronization boundary
   - supporting layers for extensions, debug views, tests, and benchmarks
   - release/quality tooling around the library

Main entry points: [`src/BidirectionalDictionary/Types/BidirectionalDictionary.cs`](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/BidirectionalDictionary.cs) (BidirectionalDictionary), [`src/BidirectionalDictionary/Types/ConcurrentBidirectionalDictionary.cs`](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/ConcurrentBidirectionalDictionary.cs) (ConcurrentDictionary), [`src/BidirectionalDictionary/Types/ReadOnlyBidirectionalDictionary.cs`](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/ReadOnlyBidirectionalDictionary.cs) (ReadOnlyDictionary), [`tests/BidirectionalDictionary.Tests`](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/tests/BidirectionalDictionary.Tests) (Library tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["Consumers"]
  node_external_consumers(("Consumers<br/>library users"))
end

subgraph group_core["Core library"]
  node_ibidir["IBidirectionalDictionary<br/>interface"]
  node_ireadonlybidir["IReadOnlyBidirectionalDictionary<br/>interface"]
  node_bidir_core["BidirectionalDictionary<br/>mutable dict"]
  node_concurrent_core["ConcurrentDictionary<br/>concurrent dict"]
  node_readonly_core["ReadOnlyDictionary<br/>read-only wrapper"]
  node_forward_index[("Forward index<br/>key→value view")]
  node_reverse_index[("Reverse index<br/>value→key view")]
  node_sync_boundary{{"Sync rules<br/>indexing invariant"}}
  node_concurrency_boundary{{"Stripe locks<br/>sync layer"}}
end

subgraph group_support["Support"]
  node_extensions_api["LINQ helpers<br/>extensions"]
  node_debug_views["Debug views<br/>debugger helpers"]
end

subgraph group_quality["Quality"]
  node_public_api["Public API<br/>compatibility baseline"]
  node_library_tests["Library tests<br/>test suite"]
  node_stress_validation["Stress checks<br/>concurrency tests"]
  node_benchmarks_suite["Benchmarks<br/>perf suite"]
end

subgraph group_release["Release"]
  node_ci_publish["CI publish<br/>release pipeline<br/>[ci.yml]"]
end

node_external_consumers -->|"code against"| node_ibidir
node_external_consumers -->|"code against"| node_ireadonlybidir
node_ibidir -->|"implemented by"| node_bidir_core
node_ibidir -->|"implemented by"| node_concurrent_core
node_ireadonlybidir -->|"implemented by"| node_readonly_core
node_bidir_core -->|"stores"| node_forward_index
node_bidir_core -->|"stores"| node_reverse_index
node_sync_boundary -->|"keeps in sync"| node_forward_index
node_sync_boundary -->|"keeps in sync"| node_reverse_index
node_bidir_core -->|"enforces"| node_sync_boundary
node_concurrent_core -->|"enforces"| node_sync_boundary
node_concurrent_core -->|"uses"| node_concurrency_boundary
node_readonly_core -->|"wraps"| node_bidir_core
node_readonly_core -->|"preserves"| node_sync_boundary
node_extensions_api -->|"creates"| node_bidir_core
node_debug_views -->|"inspects"| node_bidir_core
node_public_api -->|"tracks"| node_ibidir
node_public_api -->|"tracks"| node_ireadonlybidir
node_library_tests -->|"verifies"| node_bidir_core
node_library_tests -->|"verifies"| node_concurrent_core
node_library_tests -->|"verifies"| node_readonly_core
node_stress_validation -->|"stresses"| node_concurrent_core
node_benchmarks_suite -->|"measures"| node_bidir_core
node_benchmarks_suite -->|"measures"| node_concurrent_core
node_benchmarks_suite -->|"measures"| node_readonly_core
node_ci_publish -->|"runs"| node_library_tests
node_ci_publish -->|"guards"| node_public_api
node_ci_publish -->|"publishes"| node_benchmarks_suite

click node_ibidir "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Interfaces/IBidirectionalDictionary.cs"
click node_ireadonlybidir "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Interfaces/IReadOnlyBidirectionalDictionary.cs"
click node_bidir_core "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/BidirectionalDictionary.cs"
click node_concurrent_core "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/ConcurrentBidirectionalDictionary.cs"
click node_readonly_core "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/ReadOnlyBidirectionalDictionary.cs"
click node_extensions_api "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Extensions/BidirectionalDictionaryEnumerableExtensions.cs"
click node_debug_views "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/DebugViews/DictionaryDebugView.cs"
click node_public_api "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/PublicAPI/net6.0/PublicAPI.Shipped.txt"
click node_library_tests "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/tests/BidirectionalDictionary.Tests"
click node_stress_validation "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/tests/BidirectionalDictionary.Tests/Types/ConcurrentBidirectionalDictionary/ConcurrentBidirectionalDictionaryTests.Coyote.cs"
click node_benchmarks_suite "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/benchmarks/BidirectionalDictionary.Benchmarks"
click node_ci_publish "https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/.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_external_consumers toneBlue
class node_ibidir,node_ireadonlybidir,node_bidir_core,node_concurrent_core,node_readonly_core,node_forward_index,node_reverse_index,node_sync_boundary,node_concurrency_boundary toneAmber
class node_extensions_api,node_debug_views toneMint
class node_public_api,node_library_tests,node_stress_validation,node_benchmarks_suite toneRose
class node_ci_publish toneIndigo
```

## Components

### Consumers

External code using the NuGet package and its contracts.

- **Consumers**: library users · Code that uses the package through mutable, concurrent, or read-only contracts.

### Core library

Public interfaces and concrete bidirectional dictionary implementations.

- [IBidirectionalDictionary](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Interfaces/IBidirectionalDictionary.cs): interface · Mutable bidirectional dictionary contract with inverse lookup behavior. · `src/BidirectionalDictionary/Interfaces/IBidirectionalDictionary.cs`
- [IReadOnlyBidirectionalDictionary](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Interfaces/IReadOnlyBidirectionalDictionary.cs): interface · Read-only contract that still exposes forward and reverse lookup. · `src/BidirectionalDictionary/Interfaces/IReadOnlyBidirectionalDictionary.cs`
- [BidirectionalDictionary](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/BidirectionalDictionary.cs): mutable dict · In-memory implementation that keeps forward and reverse indexes synchronized. · `src/BidirectionalDictionary/Types/BidirectionalDictionary.cs`
- [ConcurrentDictionary](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/ConcurrentBidirectionalDictionary.cs): concurrent dict · Thread-safe implementation with lock-free reads and striped write synchronization. · `src/BidirectionalDictionary/Types/ConcurrentBidirectionalDictionary.cs`
- [ReadOnlyDictionary](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Types/ReadOnlyBidirectionalDictionary.cs): read-only wrapper · Facade over shared storage that blocks mutation while preserving inverse lookup. · `src/BidirectionalDictionary/Types/ReadOnlyBidirectionalDictionary.cs`
- **Forward index**: key→value view · Primary lookup side for key-to-value access within the implementations.
- **Reverse index**: value→key view · Inverse lookup side kept in sync with the forward index.
- **Sync rules**: indexing invariant · Symmetric update/removal logic that maintains both views consistently.
- **Stripe locks**: sync layer · Concurrency control boundary around writes, while reads stay fast.

### Support

Extensions and debugger-facing helpers around the core collections.

- [LINQ helpers](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/Extensions/BidirectionalDictionaryEnumerableExtensions.cs): extensions · Construction helpers from key-value pairs, tuples, and selector-based sequences. · `src/BidirectionalDictionary/Extensions/BidirectionalDictionaryEnumerableExtensions.cs`
- [Debug views](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/DebugViews/DictionaryDebugView.cs): debugger helpers · Debugger-only views for items, keys, and values. · `src/BidirectionalDictionary/DebugViews/DictionaryDebugView.cs`

### Quality

Tests, benchmarks, and release/compatibility tooling.

- [Public API](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/src/BidirectionalDictionary/PublicAPI/net6.0/PublicAPI.Shipped.txt): compatibility baseline · Versioned shipped and unshipped API tracking across target frameworks. · `src/BidirectionalDictionary/PublicAPI/net6.0/PublicAPI.Shipped.txt`
- [Library tests](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/tests/BidirectionalDictionary.Tests): test suite · Contract and behavior tests for mutable, concurrent, and read-only variants. · `tests/BidirectionalDictionary.Tests`
- [Stress checks](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/tests/BidirectionalDictionary.Tests/Types/ConcurrentBidirectionalDictionary/ConcurrentBidirectionalDictionaryTests.Coyote.cs): concurrency tests · Stress and Coyote-based validation for multithreaded correctness. · `tests/BidirectionalDictionary.Tests/Types/ConcurrentBidirectionalDictionary/ConcurrentBidirectionalDictionaryTests.Coyote.cs`
- [Benchmarks](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/benchmarks/BidirectionalDictionary.Benchmarks): perf suite · Performance comparisons across mutable, concurrent, and read-only implementations. · `benchmarks/BidirectionalDictionary.Benchmarks`

### Release

CI and packaging pipeline for the library.

- [CI publish](https://github.com/iikuzmychov/bidirectionaldictionary/blob/master/.github/workflows/ci.yml): release pipeline · GitHub Actions workflows for validation, coverage, and NuGet publishing. · `.github/workflows/ci.yml`

## Connections

- Consumers → IBidirectionalDictionary: code against · Consumers use the mutable contract when they need write access.
- Consumers → IReadOnlyBidirectionalDictionary: code against · Consumers use the read-only contract for lookup-only access.
- IBidirectionalDictionary → BidirectionalDictionary: implemented by · The mutable implementation fulfills the primary bidirectional contract.
- IBidirectionalDictionary → ConcurrentDictionary: implemented by · The concurrent implementation also fulfills the mutable contract.
- IReadOnlyBidirectionalDictionary → ReadOnlyDictionary: implemented by · The read-only wrapper fulfills the read-only contract.
- BidirectionalDictionary → Forward index: stores · Holds the forward map for key-to-value lookup.
- BidirectionalDictionary → Reverse index: stores · Holds the reverse map for value-to-key lookup.
- Sync rules → Forward index: keeps in sync · Updates must preserve consistency in the forward view.
- Sync rules → Reverse index: keeps in sync · Updates must preserve consistency in the reverse view.
- BidirectionalDictionary → Sync rules: enforces · Mutable operations maintain the symmetric indexing invariant.
- ConcurrentDictionary → Sync rules: enforces · Concurrent mutation must preserve the same indexing invariant.
- ConcurrentDictionary → Stripe locks: uses · Synchronization is localized around writes with striped locking.
- ReadOnlyDictionary → BidirectionalDictionary: wraps · Read-only access shares the same underlying data with the mutable source.
- ReadOnlyDictionary → Sync rules: preserves · The wrapper exposes consistency of both directions without mutation.
- LINQ helpers → BidirectionalDictionary: creates · LINQ helpers materialize bidirectional dictionaries from sequences.
- Debug views → BidirectionalDictionary: inspects · Debugger views expose collection state without changing runtime behavior.
- Public API → IBidirectionalDictionary: tracks · API baselines record the public contract surface.
- Public API → IReadOnlyBidirectionalDictionary: tracks · API baselines record the public contract surface.
- Library tests → BidirectionalDictionary: verifies · Tests cover mutable dictionary behavior and contract compliance.
- Library tests → ConcurrentDictionary: verifies · Tests cover concurrent behavior and collection semantics.
- Library tests → ReadOnlyDictionary: verifies · Tests cover wrapper behavior and read-only access.
- Stress checks → ConcurrentDictionary: stresses · Concurrency-specific validation explores multithreaded correctness.
- Benchmarks → BidirectionalDictionary: measures · Benchmarks compare mutable operations and lookup cost.
- Benchmarks → ConcurrentDictionary: measures · Benchmarks compare concurrent performance characteristics.
- Benchmarks → ReadOnlyDictionary: measures · Benchmarks compare the read-only wrapper path.
- CI publish → Library tests: runs · CI validates the library through the test suite.
- CI publish → Public API: guards · Release pipeline preserves compatibility baselines.
- CI publish → Benchmarks: publishes · Benchmarking supports performance visibility alongside releases.
