# post-q/pq-map architecture

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

- Interactive diagram: https://gitdiagram.com/post-q/pq-map
- Repository: https://github.com/post-q/pq-map

## Overview

pq-map discovers and correlates a domain’s externally visible certificate and cryptographic services. The documented workflow is CT certificate discovery, DNS service discovery, live TLS probing, then correlated text, JSON, or graph output. The graph preserves CT database/HTTP fallback, DNS record discovery, probing and alternate-port scanning, and the cache subsystems. Some orchestration source was not sampled, so the workflow links follow the README; internal call details beyond sampled code are not asserted.

Main entry points: [`src/collect.rs`](https://github.com/post-q/pq-map/blob/main/src/collect.rs) (Discovery coordinator), [`src/cli.rs`](https://github.com/post-q/pq-map/blob/main/src/cli.rs) (CLI), [`src/probe/mod.rs`](https://github.com/post-q/pq-map/blob/main/src/probe/mod.rs) (Endpoint probe coordinator), [`src/discover/ctdb.rs`](https://github.com/post-q/pq-map/blob/main/src/discover/ctdb.rs) (CT database lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["CLI<br/>[cli.rs]"]
  node_collector["Discovery coordinator<br/>[collect.rs]"]
  node_config["Runtime configuration<br/>[config.rs]"]
end

subgraph group_cert["Certificate discovery"]
  node_ct["CT certificate parsing<br/>[ct.rs]"]
  node_ctdb["CT database lookup<br/>[ctdb.rs]"]
  node_fetch["CT HTTP fallback<br/>[fetch.rs]"]
  node_ctcache[("CT cache<br/>[cache.rs]")]
  node_chaincache[("Chain cache<br/>[chain_cache.rs]")]
end

subgraph group_dns["DNS discovery"]
  node_dns["DNS records<br/>[dns.rs]"]
  node_resolver["DNS resolution<br/>[resolve.rs]"]
end

subgraph group_probe["Live probing"]
  node_probecache[("Probe cache<br/>[probe_cache.rs]")]
  node_sweep["Alternate-port sweep<br/>[sweep.rs]"]
  node_probe["Endpoint probe coordinator<br/>[mod.rs]"]
  node_tls["TLS handshake and parsing<br/>[tls.rs]"]
  node_openssl["OpenSSL fallback<br/>[tls.rs]"]
end

subgraph group_results["State and output"]
  node_model["Correlated domain state<br/>[model.rs]"]
  node_text["Text reports<br/>[text.rs]"]
  node_graph["Semantic graph output<br/>[graph.rs]"]
  node_json["JSON output<br/>[cli.rs]"]
end

node_user(("Domain operator"))
node_dns_service[("DNS infrastructure")]
node_services(("Domain services"))
node_ct_database[("CT database<br/>external system")]
node_crtsh["crt.sh<br/>external system"]

node_user -->|"scans domain"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts discovery"| node_collector
node_collector -->|"reads and writes"| node_ctcache
node_collector -->|"queries CT"| node_ctdb
node_ctdb -->|"queries certificates"| node_ct_database
node_collector -.->|"falls back to HTTP"| node_fetch
node_fetch -.->|"fetches CT records"| node_crtsh
node_collector -->|"normalizes certificates"| node_ct
node_collector -->|"reads and writes"| node_chaincache
node_collector -->|"discovers records"| node_dns
node_dns -->|"queries records"| node_dns_service
node_collector -->|"resolves hosts"| node_resolver
node_resolver -->|"resolves names"| node_dns_service
node_collector -->|"reads and writes"| node_probecache
node_collector -->|"probes endpoints"| node_probe
node_collector -.->|"scans other ports"| node_sweep
node_sweep -->|"probes discovered ports"| node_probe
node_probe -->|"attempts TLS"| node_tls
node_probe -.->|"falls back on handshake failure"| node_openssl
node_tls -->|"connects to endpoints"| node_services
node_openssl -.->|"connects to endpoints"| node_services
node_collector -->|"assembles state"| node_model
node_cli -->|"renders text"| node_text
node_cli -->|"renders graph"| node_graph
node_cli -->|"serializes state"| node_json

click node_cli "https://github.com/post-q/pq-map/blob/main/src/cli.rs"
click node_collector "https://github.com/post-q/pq-map/blob/main/src/collect.rs"
click node_config "https://github.com/post-q/pq-map/blob/main/src/config.rs"
click node_ct "https://github.com/post-q/pq-map/blob/main/src/discover/ct.rs"
click node_ctdb "https://github.com/post-q/pq-map/blob/main/src/discover/ctdb.rs"
click node_fetch "https://github.com/post-q/pq-map/blob/main/src/discover/fetch.rs"
click node_ctcache "https://github.com/post-q/pq-map/blob/main/src/discover/cache.rs"
click node_chaincache "https://github.com/post-q/pq-map/blob/main/src/discover/chain_cache.rs"
click node_dns "https://github.com/post-q/pq-map/blob/main/src/discover/dns.rs"
click node_resolver "https://github.com/post-q/pq-map/blob/main/src/discover/resolve.rs"
click node_probecache "https://github.com/post-q/pq-map/blob/main/src/discover/probe_cache.rs"
click node_sweep "https://github.com/post-q/pq-map/blob/main/src/probe/sweep.rs"
click node_probe "https://github.com/post-q/pq-map/blob/main/src/probe/mod.rs"
click node_tls "https://github.com/post-q/pq-map/blob/main/src/probe/tls.rs"
click node_openssl "https://github.com/post-q/pq-map/blob/main/src/probe/tls.rs"
click node_model "https://github.com/post-q/pq-map/blob/main/src/model.rs"
click node_text "https://github.com/post-q/pq-map/blob/main/src/render/text.rs"
click node_graph "https://github.com/post-q/pq-map/blob/main/src/render/graph.rs"
click node_json "https://github.com/post-q/pq-map/blob/main/src/cli.rs"

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,node_collector,node_config toneBlue
class node_ct,node_ctdb,node_fetch,node_ctcache,node_chaincache,node_dns_service,node_ct_database toneAmber
class node_dns,node_resolver toneMint
class node_probecache,node_sweep,node_probe,node_tls,node_openssl toneRose
class node_model,node_text,node_graph,node_json,node_user,node_services,node_crtsh toneIndigo
```

## Components

### Entry and orchestration

- [CLI](https://github.com/post-q/pq-map/blob/main/src/cli.rs): `src/cli.rs`
- [Discovery coordinator](https://github.com/post-q/pq-map/blob/main/src/collect.rs): `src/collect.rs`
- [Runtime configuration](https://github.com/post-q/pq-map/blob/main/src/config.rs): `src/config.rs`

### Certificate discovery

- [CT certificate parsing](https://github.com/post-q/pq-map/blob/main/src/discover/ct.rs): `src/discover/ct.rs`
- [CT database lookup](https://github.com/post-q/pq-map/blob/main/src/discover/ctdb.rs): `src/discover/ctdb.rs`
- [CT HTTP fallback](https://github.com/post-q/pq-map/blob/main/src/discover/fetch.rs): `src/discover/fetch.rs`
- [CT cache](https://github.com/post-q/pq-map/blob/main/src/discover/cache.rs): `src/discover/cache.rs`
- [Chain cache](https://github.com/post-q/pq-map/blob/main/src/discover/chain_cache.rs): `src/discover/chain_cache.rs`

### DNS discovery

- [DNS records](https://github.com/post-q/pq-map/blob/main/src/discover/dns.rs): `src/discover/dns.rs`
- [DNS resolution](https://github.com/post-q/pq-map/blob/main/src/discover/resolve.rs): `src/discover/resolve.rs`

### Live probing

- [Probe cache](https://github.com/post-q/pq-map/blob/main/src/discover/probe_cache.rs): `src/discover/probe_cache.rs`
- [Alternate-port sweep](https://github.com/post-q/pq-map/blob/main/src/probe/sweep.rs): `src/probe/sweep.rs`
- [Endpoint probe coordinator](https://github.com/post-q/pq-map/blob/main/src/probe/mod.rs): `src/probe/mod.rs`
- [TLS handshake and parsing](https://github.com/post-q/pq-map/blob/main/src/probe/tls.rs): `src/probe/tls.rs`
- [OpenSSL fallback](https://github.com/post-q/pq-map/blob/main/src/probe/tls.rs): `src/probe/tls.rs`

### State and output

- [Correlated domain state](https://github.com/post-q/pq-map/blob/main/src/model.rs): `src/model.rs`
- [Text reports](https://github.com/post-q/pq-map/blob/main/src/render/text.rs): `src/render/text.rs`
- [Semantic graph output](https://github.com/post-q/pq-map/blob/main/src/render/graph.rs): `src/render/graph.rs`
- [JSON output](https://github.com/post-q/pq-map/blob/main/src/cli.rs): `src/cli.rs`

### Other components

- **Domain operator**
- **DNS infrastructure**
- **Domain services**
- **CT database**: external system
- **crt.sh**: external system

## Connections

- Domain operator → CLI: scans domain
- CLI → Runtime configuration: loads settings
- CLI → Discovery coordinator: starts discovery
- Discovery coordinator → CT cache: reads and writes
- Discovery coordinator → CT database lookup: queries CT
- CT database lookup → CT database: queries certificates
- Discovery coordinator → CT HTTP fallback: falls back to HTTP
- CT HTTP fallback → crt.sh: fetches CT records
- Discovery coordinator → CT certificate parsing: normalizes certificates
- Discovery coordinator → Chain cache: reads and writes
- Discovery coordinator → DNS records: discovers records
- DNS records → DNS infrastructure: queries records
- Discovery coordinator → DNS resolution: resolves hosts
- DNS resolution → DNS infrastructure: resolves names
- Discovery coordinator → Probe cache: reads and writes
- Discovery coordinator → Endpoint probe coordinator: probes endpoints
- Discovery coordinator → Alternate-port sweep: scans other ports
- Alternate-port sweep → Endpoint probe coordinator: probes discovered ports
- Endpoint probe coordinator → TLS handshake and parsing: attempts TLS
- Endpoint probe coordinator → OpenSSL fallback: falls back on handshake failure
- TLS handshake and parsing → Domain services: connects to endpoints
- OpenSSL fallback → Domain services: connects to endpoints
- Discovery coordinator → Correlated domain state: assembles state
- CLI → Text reports: renders text
- CLI → Semantic graph output: renders graph
- CLI → JSON output: serializes state