# aglasencnik/typedicons architecture

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

- Interactive diagram: https://gitdiagram.com/aglasencnik/typedicons
- Repository: https://github.com/aglasencnik/typedicons

## Overview

1. This repository is a .NET solution split into three product-facing subsystems: a command-line tool, a shared core library, and a Roslyn source generator. The overall purpose is to turn Iconify icon selections into strongly typed Blazor-friendly icon references at compile time.

2. `src/TypedIcons.Cli` is the operational entry point. It exposes commands for project setup and icon lifecycle management: `init`, `add`, `remove`, `list`, `restore`, and `clean`. This is the user-facing boundary that edits project configuration and manages the local icon cache.

3. The CLI is organized around services rather than direct file manipulation. `ConfigService` handles `typedicons.json`, `IconService` and `IconifyService` handle icon resolution/cache-related work, and `InitializationService` wires up the initial project state. The command classes in `Commands/` are thin wrappers over those services.

4. `src/TypedIcons.Core` is the shared model layer used by both the CLI and the generator. It contains the configuration and cache abstractions (`IconConfig`, `IconCache`, `IconReference`) plus small utility extensions. This is the main contract boundary for “what icons are selected” and “what cached icon data exists.”

5. The repository’s key data flow starts with `typedicons.json` in the project root. That file is the source of truth for which icons are enabled in a consumer project. The CLI creates and updates it, and the source generator reads it during build.

6. A second data store exists in the project’s `obj` folder: the local icon cache. The README and file layout indicate this cache is generated from `typedicons.json`, is not committed to source control, and is restored from Iconify when needed. This cache decouples build-time generation from network access.

7. `src/TypedIcons.Generator` is the compile-time generation boundary. Its `IconGenerator` reads the config and cache and emits strongly typed C# code from `CodeTemplates.cs`. The generated output provides the `Icons.<Set>.<Name>` API used by consuming Blazor components.

8. The generator is distributed as a NuGet package and is installed into consumer projects, either manually or via `typedicons init`. The build-time integration is important architecturally: icon definitions are materialized during compilation, not at runtime, which is why the README emphasizes no dynamic loading and no runtime dependency on Iconify.

9. The sample project under `samples/TypedIcons.Sandbox` demonstrates the consumption side. It is a Blazor app with an `Icon` component usage path and test icon wrappers (`TestIcon`, `TestIconBase`, `TestIconSet`, etc.) that illustrate how generated icon types are surfaced in UI code. The sample also includes its own `typedicons.json`, showing the expected project-local configuration shape.

10. `tests/TypedIcons.Tests` focuses on generator behavior, especially around additional text inputs and test fixture data for `typedicons.json` and cache files. That indicates the most critical correctness surface is the transformation from config/cache inputs into generated source.

11. The CI and release workflows in `.github/workflows` likely validate the package/tooling pipeline rather than app deployment. In this repo, build quality matters across three outputs: the CLI executable/tool, the generator package, and the shared core library.

12. For an architecture diagram, the important boundaries are: consumer project, `typedicons.json` config, local cache in `obj`, CLI command layer, shared core models, generator at build time, and the resulting generated icon classes consumed by Blazor UI. The external dependency that materially affects the flow is Iconify, which is only needed to populate or restore the cache.

Main entry points: [`src/TypedIcons.Generator/IconGenerator.cs`](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Generator/IconGenerator.cs) (Icon generator), [`src/TypedIcons.Cli/Commands`](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Commands) (Commands), [`src/TypedIcons.Cli/Services/IconService.cs`](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/IconService.cs) (Icon service), [`src/TypedIcons.Core/Models/IconConfig.cs`](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconConfig.cs) (IconConfig)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_program(("CLI entry<br/>entrypoint<br/>[Program.cs]"))
  node_cli_commands["Commands<br/>command layer<br/>[Commands]"]
  node_cli_config["Config service<br/>[ConfigService.cs]"]
  node_cli_icons["Icon service<br/>[IconService.cs]"]
  node_cli_iconify["Iconify service<br/>remote service<br/>[IconifyService.cs]"]
  node_cli_init["Init service<br/>setup service"]
end

subgraph group_core["Core"]
  node_core_config["IconConfig<br/>model<br/>[IconConfig.cs]"]
  node_core_cache[("IconCache<br/>model<br/>[IconCache.cs]")]
  node_core_ref["IconReference<br/>model<br/>[IconReference.cs]"]
end

subgraph group_generator["Generator"]
  node_generator_entry["Icon generator<br/>source generator<br/>[IconGenerator.cs]"]
  node_generator_tpl["Templates<br/>[CodeTemplates.cs]"]
end

subgraph group_sample["Sample app"]
  node_sample_app["Sandbox app<br/>blazor app<br/>[Program.cs]"]
  node_sample_config["Sample config<br/>project config<br/>[typedicons.json]"]
  node_sample_icons["Test icons<br/>ui wrappers<br/>[TestIcons.cs]"]
end

subgraph group_tests["Tests"]
  node_tests_entry["Generator tests<br/>test suite"]
  node_tests_data_cfg["Test config<br/>fixture<br/>[typedicons.json]"]
  node_tests_data_cache[("Test cache<br/>fixture")]
end

subgraph group_cicd["CI/CD"]
  node_ci_workflows["Workflows<br/>[ci.yml]"]
end

subgraph group_external["External"]
  node_iconify(("Iconify<br/>external api"))
end

node_cli_program -->|"routes"| node_cli_commands
node_cli_commands -->|"uses"| node_cli_config
node_cli_commands -->|"uses"| node_cli_icons
node_cli_commands -->|"uses"| node_cli_init
node_cli_icons -->|"restores from"| node_cli_iconify
node_cli_config -->|"persists"| node_core_config
node_cli_icons -->|"reads/writes"| node_core_cache
node_cli_icons -->|"tracks"| node_core_ref
node_cli_init -->|"creates"| node_core_config
node_cli_iconify -->|"calls"| node_iconify
node_generator_entry -->|"reads"| node_core_config
node_generator_entry -->|"reads"| node_core_cache
node_generator_entry -->|"emits"| node_generator_tpl
node_generator_entry -->|"expands"| node_core_ref
node_sample_app -->|"uses"| node_sample_icons
node_sample_app -->|"shaped by"| node_sample_config
node_tests_entry -->|"loads"| node_tests_data_cfg
node_tests_entry -->|"loads"| node_tests_data_cache
node_tests_entry -->|"validates"| node_generator_entry
node_ci_workflows -->|"builds"| node_cli_program
node_ci_workflows -->|"builds"| node_generator_entry
node_ci_workflows -->|"builds"| node_core_config

click node_cli_program "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Program.cs"
click node_cli_commands "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Commands"
click node_cli_config "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/ConfigService.cs"
click node_cli_icons "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/IconService.cs"
click node_cli_iconify "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/IconifyService.cs"
click node_cli_init "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/InitializationService.cs"
click node_core_config "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconConfig.cs"
click node_core_cache "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconCache.cs"
click node_core_ref "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconReference.cs"
click node_generator_entry "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Generator/IconGenerator.cs"
click node_generator_tpl "https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Generator/CodeTemplates.cs"
click node_sample_app "https://github.com/aglasencnik/typedicons/blob/main/samples/TypedIcons.Sandbox/Program.cs"
click node_sample_config "https://github.com/aglasencnik/typedicons/blob/main/samples/TypedIcons.Sandbox/typedicons.json"
click node_sample_icons "https://github.com/aglasencnik/typedicons/blob/main/samples/TypedIcons.Sandbox/Components/Components/TestIcons.cs"
click node_tests_entry "https://github.com/aglasencnik/typedicons/blob/main/tests/TypedIcons.Tests/IconGeneratorTests.cs"
click node_tests_data_cfg "https://github.com/aglasencnik/typedicons/blob/main/tests/TypedIcons.Tests/TestData/typedicons.json"
click node_tests_data_cache "https://github.com/aglasencnik/typedicons/blob/main/tests/TypedIcons.Tests/TestData/typedicons.cache.json"
click node_ci_workflows "https://github.com/aglasencnik/typedicons/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_cli_program,node_cli_commands,node_cli_config,node_cli_icons,node_cli_iconify,node_cli_init,node_iconify toneBlue
class node_core_config,node_core_cache,node_core_ref toneAmber
class node_generator_entry,node_generator_tpl toneMint
class node_sample_app,node_sample_config,node_sample_icons toneRose
class node_tests_entry,node_tests_data_cfg,node_tests_data_cache toneIndigo
class node_ci_workflows toneTeal
```

## Components

### CLI

Command-line entrypoint and project maintenance flow

- [CLI entry](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Program.cs): entrypoint · Operates commands for init, add, remove, list, restore, and clean · `src/TypedIcons.Cli/Program.cs`
- [Commands](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Commands): command layer · Thin command wrappers around application services · `src/TypedIcons.Cli/Commands`
- [Config service](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/ConfigService.cs): config service · Reads and writes typedicons.json · `src/TypedIcons.Cli/Services/ConfigService.cs`
- [Icon service](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/IconService.cs): icon service · Coordinates icon selection and local cache operations · `src/TypedIcons.Cli/Services/IconService.cs`
- [Iconify service](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/IconifyService.cs): remote service · Handles fetching or restoring icon data from Iconify · `src/TypedIcons.Cli/Services/IconifyService.cs`
- [Init service](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Cli/Services/InitializationService.cs): setup service · Bootstraps a consumer project for TypedIcons · `src/TypedIcons.Cli/Services/InitializationService.cs`

### Core

Shared icon/config contracts

- [IconConfig](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconConfig.cs): model · Selected icon set configuration · `src/TypedIcons.Core/Models/IconConfig.cs`
- [IconCache](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconCache.cs): model · Cached icon data used during build and restore · `src/TypedIcons.Core/Models/IconCache.cs`
- [IconReference](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Core/Models/IconReference.cs): model · Reference to a specific icon selection · `src/TypedIcons.Core/Models/IconReference.cs`

### Generator

Compile-time code generation

- [Icon generator](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Generator/IconGenerator.cs): source generator · Reads config and cache to emit typed icon APIs · `src/TypedIcons.Generator/IconGenerator.cs`
- [Templates](https://github.com/aglasencnik/typedicons/blob/main/src/TypedIcons.Generator/CodeTemplates.cs): code templates · String templates for generated C# output · `src/TypedIcons.Generator/CodeTemplates.cs`

### Sample app

Blazor consumption example

- [Sandbox app](https://github.com/aglasencnik/typedicons/blob/main/samples/TypedIcons.Sandbox/Program.cs): blazor app · Sample consumer showing generated icon usage · `samples/TypedIcons.Sandbox/Program.cs`
- [Sample config](https://github.com/aglasencnik/typedicons/blob/main/samples/TypedIcons.Sandbox/typedicons.json): project config · Example typedicons.json for a consumer project · `samples/TypedIcons.Sandbox/typedicons.json`
- [Test icons](https://github.com/aglasencnik/typedicons/blob/main/samples/TypedIcons.Sandbox/Components/Components/TestIcons.cs): ui wrappers · Sample icon wrapper types used to demonstrate consumption · `samples/TypedIcons.Sandbox/Components/Components/TestIcons.cs`

### Tests

Generator-focused verification

- [Generator tests](https://github.com/aglasencnik/typedicons/blob/main/tests/TypedIcons.Tests/IconGeneratorTests.cs): test suite · Checks generator behavior with config and cache inputs · `tests/TypedIcons.Tests/IconGeneratorTests.cs`
- [Test config](https://github.com/aglasencnik/typedicons/blob/main/tests/TypedIcons.Tests/TestData/typedicons.json): fixture · typedicons.json fixture used by tests · `tests/TypedIcons.Tests/TestData/typedicons.json`
- [Test cache](https://github.com/aglasencnik/typedicons/blob/main/tests/TypedIcons.Tests/TestData/typedicons.cache.json): fixture · typedicons.cache.json fixture used by tests · `tests/TypedIcons.Tests/TestData/typedicons.cache.json`

### CI/CD

Repository workflows

- [Workflows](https://github.com/aglasencnik/typedicons/blob/main/.github/workflows/ci.yml): ci workflows · Build and release validation for CLI, generator, and core · `.github/workflows/ci.yml`

### External

Third-party service

- **Iconify**: external api · External icon source used to populate or restore cache

## Connections

- CLI entry → Commands: routes · Starts the command surface
- Commands → Config service: uses · Commands read and update project configuration
- Commands → Icon service: uses · Commands manage icon selection and cache state
- Commands → Init service: uses · Init command bootstraps a project
- Icon service → Iconify service: restores from · Fetches or restores icon data when cache is missing
- Config service → IconConfig: persists · Maps typedicons.json into the shared config model
- Icon service → IconCache: reads/writes · Coordinates the local icon cache lifecycle
- Icon service → IconReference: tracks · Works with selected icon references
- Init service → IconConfig: creates · Initializes default project configuration
- Iconify service → Iconify: calls · External source for icon metadata and content
- Icon generator → IconConfig: reads · Consumes selected icon definitions at build time
- Icon generator → IconCache: reads · Uses cached icon data to avoid runtime fetching
- Icon generator → Templates: emits · Formats generated C# output from templates
- Icon generator → IconReference: expands · Turns references into strongly typed icon members
- Sandbox app → Test icons: uses · Blazor UI consumes generated icon wrappers
- Sandbox app → Sample config: shaped by · Sample project demonstrates the local configuration file
- Generator tests → Test config: loads · Uses typedicons.json fixture inputs
- Generator tests → Test cache: loads · Uses cache fixture inputs
- Generator tests → Icon generator: validates · Verifies generated output from config and cache data
- Workflows → CLI entry: builds · Validates the CLI package in CI
- Workflows → Icon generator: builds · Validates the generator package in CI
- Workflows → IconConfig: builds · Checks shared contracts as part of the solution
