# alb4k/iplist architecture

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

- Interactive diagram: https://gitdiagram.com/alb4k/iplist
- Repository: https://github.com/alb4k/iplist

## Overview

IPList builds IPv4/CIDR route lists for AmneziaVPN split tunneling. The main workflow refreshes service metadata and address sources, enriches services with DNS/ASN evidence, partitions routes, applies user selections, and produces validated exports or AmneziaWG configurations. The README documents the transaction and safety guarantees; sampled code confirms the refresh coordinator, catalog loader, enrichment, and export logic. App.swift is large and only partially excerpted, so UI-to-state details beyond visible calls are not expanded.

Main entry points: [`Sources/IPList/App.swift`](https://github.com/alb4k/iplist/blob/main/Sources/IPList/App.swift) (App interface), [`Sources/IPList/Core.swift`](https://github.com/alb4k/iplist/blob/main/Sources/IPList/Core.swift) (Refresh coordinator), [`Sources/IPList/ServiceCatalogLoader.swift`](https://github.com/alb4k/iplist/blob/main/Sources/IPList/ServiceCatalogLoader.swift) (Catalog loader), [`Sources/IPList/EnrichmentLoader.swift`](https://github.com/alb4k/iplist/blob/main/Sources/IPList/EnrichmentLoader.swift) (DNS and ASN enrichment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and state"]
  node_appui["App interface<br/>[App.swift]"]
  node_state[("Saved state<br/>[App.swift]")]
  node_updates["Update checker"]
end

subgraph group_catalog["Catalog and routes"]
  node_models["Catalog models"]
  node_catalogloader["Catalog loader"]
  node_matcher["IPv4 matcher"]
  node_selection["Route selection<br/>[Core.swift]"]
end

subgraph group_refresh["Refresh and enrichment"]
  node_coordinator["Refresh coordinator<br/>[Core.swift]"]
  node_enrichment["DNS and ASN enrichment"]
end

subgraph group_output["Export and configuration"]
  node_exportformats["Export formats"]
  node_wgconfig["AmneziaWG config"]
end

node_user(("User"))
node_metadata[("Catalog metadata")]
node_addresssources[("Address sources")]
node_dns{{"System DNS"}}
node_ripestat{{"RIPEstat"}}
node_exportfiles["Export files"]

node_user -->|"uses"| node_appui
node_appui -->|"persists"| node_state
node_appui -->|"refreshes"| node_coordinator
node_appui -->|"checks updates"| node_updates
node_coordinator -->|"loads catalog"| node_catalogloader
node_catalogloader -->|"fetches metadata"| node_metadata
node_coordinator -->|"loads sources"| node_addresssources
node_coordinator -.->|"enriches services"| node_enrichment
node_enrichment -->|"resolves domains"| node_dns
node_enrichment -->|"queries prefixes"| node_ripestat
node_catalogloader -->|"parses into"| node_models
node_coordinator -->|"validates refresh"| node_selection
node_user -->|"chooses routes"| node_selection
node_selection -->|"normalizes routes"| node_matcher
node_appui -->|"exports routes"| node_exportformats
node_exportformats -->|"writes JSON"| node_exportfiles
node_appui -->|"creates config"| node_wgconfig
node_wgconfig -->|"writes config"| node_exportfiles

click node_appui "https://github.com/alb4k/iplist/blob/main/Sources/IPList/App.swift"
click node_state "https://github.com/alb4k/iplist/blob/main/Sources/IPList/App.swift"
click node_updates "https://github.com/alb4k/iplist/blob/main/Sources/IPList/AppUpdateChecker.swift"
click node_models "https://github.com/alb4k/iplist/blob/main/Sources/IPList/CatalogModels.swift"
click node_catalogloader "https://github.com/alb4k/iplist/blob/main/Sources/IPList/ServiceCatalogLoader.swift"
click node_matcher "https://github.com/alb4k/iplist/blob/main/Sources/IPList/AddressMatcher.swift"
click node_coordinator "https://github.com/alb4k/iplist/blob/main/Sources/IPList/Core.swift"
click node_enrichment "https://github.com/alb4k/iplist/blob/main/Sources/IPList/EnrichmentLoader.swift"
click node_selection "https://github.com/alb4k/iplist/blob/main/Sources/IPList/Core.swift"
click node_exportformats "https://github.com/alb4k/iplist/blob/main/Sources/IPList/ExportFormats.swift"
click node_wgconfig "https://github.com/alb4k/iplist/blob/main/Sources/IPList/AmneziaWGConfig.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_appui,node_state,node_updates,node_user toneBlue
class node_models,node_catalogloader,node_matcher,node_selection,node_metadata,node_addresssources toneAmber
class node_coordinator,node_enrichment toneMint
class node_exportformats,node_wgconfig toneRose
class node_dns,node_ripestat,node_exportfiles toneIndigo
```

## Components

### App and state

- [App interface](https://github.com/alb4k/iplist/blob/main/Sources/IPList/App.swift): `Sources/IPList/App.swift`
- [Saved state](https://github.com/alb4k/iplist/blob/main/Sources/IPList/App.swift): `Sources/IPList/App.swift`
- [Update checker](https://github.com/alb4k/iplist/blob/main/Sources/IPList/AppUpdateChecker.swift): `Sources/IPList/AppUpdateChecker.swift`

### Catalog and routes

- [Catalog models](https://github.com/alb4k/iplist/blob/main/Sources/IPList/CatalogModels.swift): `Sources/IPList/CatalogModels.swift`
- [Catalog loader](https://github.com/alb4k/iplist/blob/main/Sources/IPList/ServiceCatalogLoader.swift): `Sources/IPList/ServiceCatalogLoader.swift`
- [IPv4 matcher](https://github.com/alb4k/iplist/blob/main/Sources/IPList/AddressMatcher.swift): `Sources/IPList/AddressMatcher.swift`
- [Route selection](https://github.com/alb4k/iplist/blob/main/Sources/IPList/Core.swift): `Sources/IPList/Core.swift`

### Refresh and enrichment

- [Refresh coordinator](https://github.com/alb4k/iplist/blob/main/Sources/IPList/Core.swift): `Sources/IPList/Core.swift`
- [DNS and ASN enrichment](https://github.com/alb4k/iplist/blob/main/Sources/IPList/EnrichmentLoader.swift): `Sources/IPList/EnrichmentLoader.swift`

### Export and configuration

- [Export formats](https://github.com/alb4k/iplist/blob/main/Sources/IPList/ExportFormats.swift): `Sources/IPList/ExportFormats.swift`
- [AmneziaWG config](https://github.com/alb4k/iplist/blob/main/Sources/IPList/AmneziaWGConfig.swift): `Sources/IPList/AmneziaWGConfig.swift`

### Other components

- **User**
- **Catalog metadata**
- **Address sources**
- **System DNS**
- **RIPEstat**
- **Export files**

## Connections

- User → App interface: uses (evidence: `README.md`)
- App interface → Saved state: persists (evidence: `README.md`)
- App interface → Refresh coordinator: refreshes (evidence: `README.md`)
- App interface → Update checker: checks updates (evidence: `Sources/IPList/App.swift`)
- Refresh coordinator → Catalog loader: loads catalog (evidence: `Sources/IPList/Core.swift`)
- Catalog loader → Catalog metadata: fetches metadata (evidence: `README.md`)
- Refresh coordinator → Address sources: loads sources (evidence: `Sources/IPList/Core.swift`)
- Refresh coordinator → DNS and ASN enrichment: enriches services
- DNS and ASN enrichment → System DNS: resolves domains (evidence: `README.md`)
- DNS and ASN enrichment → RIPEstat: queries prefixes (evidence: `README.md`)
- Catalog loader → Catalog models: parses into (evidence: `Sources/IPList/ServiceCatalogLoader.swift`)
- Refresh coordinator → Route selection: validates refresh (evidence: `Sources/IPList/Core.swift`)
- User → Route selection: chooses routes (evidence: `README.md`)
- Route selection → IPv4 matcher: normalizes routes (evidence: `README.md`)
- App interface → Export formats: exports routes (evidence: `README.md`)
- Export formats → Export files: writes JSON (evidence: `README.md`)
- App interface → AmneziaWG config: creates config (evidence: `README.md`)
- AmneziaWG config → Export files: writes config (evidence: `README.md`)
