# graphgeeks-lab/graphfaker architecture

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

- Interactive diagram: https://gitdiagram.com/graphgeeks-lab/graphfaker
- Repository: https://github.com/graphgeeks-lab/graphfaker

## Overview

GraphFaker generates synthetic graph datasets from reusable schemas or built-in domains, and can also turn selected real-world sources into graphs. The main workflow is to choose a domain or schema, generate entities, relationships and events, retain planted-pattern truth and run metadata, then export tables or load them into a graph store. Fraud, coordination and supply-chain domains add labelled patterns and hardness evaluation; social generation and schema drafting are additional paths. The graph follows documented behavior and indexed references; unsampled implementations are represented only at subsystem level where the tree supports them.

Main entry points: [`graphfaker/cli.py`](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/cli.py) (CLI), [`graphfaker/backends/tables.py`](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/backends/tables.py) (Graph Tables), [`graphfaker/engine/run.py`](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/run.py) (Schema Engine), [`graphfaker/schema/graph.py`](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/graph.py) (Graph Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["Python API<br/>[core.py]"]
end

subgraph group_model["Schemas And Domains"]
  node_schema["Graph Schema<br/>[graph.py]"]
  node_samplers["Attribute Samplers<br/>[samplers.py]"]
  node_schema_patterns["Pattern Schema<br/>[patterns.py]"]
  node_social["Social Domain<br/>[social.py]"]
  node_fraud["Fraud Domain"]
  node_coordination["Coordination Domain"]
  node_supply["Supply Chain Domain"]
  node_draft["Schema Drafter<br/>[draft.py]"]
end

subgraph group_runtime["Generation Runtime"]
  node_engine["Schema Engine<br/>[run.py]"]
  node_sampling["Attribute Sampling<br/>[sampling.py]"]
  node_topology["Topology Builder<br/>[topology.py]"]
  node_process["Process Generator<br/>[process.py]"]
  node_injection["Pattern Injection<br/>[injection.py]"]
  node_domain_process["Fraud Process<br/>[process.py]"]
end

subgraph group_outputs["Data And Integrations"]
  node_tables[("Graph Tables<br/>[tables.py]")]
  node_export["File Export<br/>[export.py]"]
  node_neo4j["Neo4j Sink<br/>[neo4j.py]"]
  node_live_neo4j["Live Neo4j Sink<br/>[neo4j_live.py]"]
  node_other_sinks["Other Sinks"]
  node_fetchers["Real-World Fetchers"]
end

subgraph group_analysis["Truth And Analysis"]
  node_truth[("Ground Truth<br/>[truth.py]")]
  node_verify["Load Verification<br/>[verify.py]"]
  node_resolve["Entity Resolution<br/>[resolve.py]"]
end

node_user(("User"))
node_external_data(("External Data"))

node_user -->|"runs commands"| node_cli
node_user -->|"calls API"| node_api
node_cli -->|"selects domain"| node_fraud
node_cli -.->|"selects domain"| node_coordination
node_cli -.->|"selects domain"| node_supply
node_cli -.->|"selects domain"| node_social
node_cli -->|"runs schema"| node_engine
node_api -->|"generates graph"| node_engine
node_social -->|"declares graph"| node_schema
node_schema -->|"defines attributes"| node_samplers
node_schema -->|"declares patterns"| node_schema_patterns
node_draft -->|"creates schema"| node_schema
node_engine -->|"samples attributes"| node_sampling
node_engine -->|"builds edges"| node_topology
node_engine -->|"produces tables"| node_tables
node_process -->|"uses declarations"| node_schema_patterns
node_fraud -->|"generates activity"| node_domain_process
node_fraud -->|"plants typologies"| node_injection
node_coordination -->|"plants playbooks"| node_injection
node_supply -->|"plants patterns"| node_injection
node_cli -->|"writes dataset"| node_export
node_tables -->|"loads tables"| node_neo4j
node_tables -->|"streams batches"| node_live_neo4j
node_tables -.->|"exports tables"| node_other_sinks
node_external_data -->|"provides records"| node_fetchers
node_fetchers -.->|"feeds graph"| node_cli
node_engine -.->|"records planted truth"| node_truth
node_tables -->|"checks loaded graph"| node_verify
node_truth -->|"checks ground truth"| node_verify
node_tables -.->|"resolves entities"| node_resolve

click node_cli "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/cli.py"
click node_api "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/core.py"
click node_schema "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/graph.py"
click node_samplers "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/samplers.py"
click node_schema_patterns "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/patterns.py"
click node_social "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/domains/social.py"
click node_fraud "https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/domains/fraud"
click node_coordination "https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/domains/coordination"
click node_supply "https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/domains/supply_chain"
click node_draft "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/llm/draft.py"
click node_engine "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/run.py"
click node_sampling "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/sampling.py"
click node_topology "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/topology.py"
click node_process "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/process.py"
click node_injection "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/injection.py"
click node_domain_process "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/domains/fraud/process.py"
click node_tables "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/backends/tables.py"
click node_export "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/export.py"
click node_neo4j "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/neo4j.py"
click node_live_neo4j "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/neo4j_live.py"
click node_other_sinks "https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/sinks"
click node_truth "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/truth.py"
click node_verify "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/verify.py"
click node_resolve "https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/resolve.py"
click node_fetchers "https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/fetchers"

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_api,node_user toneBlue
class node_schema,node_samplers,node_schema_patterns,node_social,node_fraud,node_coordination,node_supply,node_draft toneAmber
class node_engine,node_sampling,node_topology,node_process,node_injection,node_domain_process toneMint
class node_tables,node_export,node_neo4j,node_live_neo4j,node_other_sinks,node_fetchers toneRose
class node_truth,node_verify,node_resolve,node_external_data toneIndigo
```

## Components

### User Entry

- [CLI](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/cli.py): `graphfaker/cli.py`
- [Python API](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/core.py): `graphfaker/core.py`

### Schemas And Domains

- [Graph Schema](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/graph.py): `graphfaker/schema/graph.py`
- [Attribute Samplers](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/samplers.py): `graphfaker/schema/samplers.py`
- [Pattern Schema](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/schema/patterns.py): `graphfaker/schema/patterns.py`
- [Social Domain](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/domains/social.py): `graphfaker/domains/social.py`
- [Fraud Domain](https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/domains/fraud): `graphfaker/domains/fraud`
- [Coordination Domain](https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/domains/coordination): `graphfaker/domains/coordination`
- [Supply Chain Domain](https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/domains/supply_chain): `graphfaker/domains/supply_chain`
- [Schema Drafter](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/llm/draft.py): `graphfaker/llm/draft.py`

### Generation Runtime

- [Schema Engine](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/run.py): `graphfaker/engine/run.py`
- [Attribute Sampling](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/sampling.py): `graphfaker/engine/sampling.py`
- [Topology Builder](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/topology.py): `graphfaker/engine/topology.py`
- [Process Generator](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/process.py): `graphfaker/engine/process.py`
- [Pattern Injection](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/engine/injection.py): `graphfaker/engine/injection.py`
- [Fraud Process](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/domains/fraud/process.py): `graphfaker/domains/fraud/process.py`

### Data And Integrations

- [Graph Tables](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/backends/tables.py): `graphfaker/backends/tables.py`
- [File Export](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/export.py): `graphfaker/export.py`
- [Neo4j Sink](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/neo4j.py): `graphfaker/sinks/neo4j.py`
- [Live Neo4j Sink](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/neo4j_live.py): `graphfaker/sinks/neo4j_live.py`
- [Other Sinks](https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/sinks): `graphfaker/sinks`
- [Real-World Fetchers](https://github.com/graphgeeks-lab/graphfaker/tree/main/graphfaker/fetchers): `graphfaker/fetchers`

### Truth And Analysis

- [Ground Truth](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/truth.py): `graphfaker/sinks/truth.py`
- [Load Verification](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/sinks/verify.py): `graphfaker/sinks/verify.py`
- [Entity Resolution](https://github.com/graphgeeks-lab/graphfaker/blob/main/graphfaker/resolve.py): `graphfaker/resolve.py`

### Other components

- **User**
- **External Data**

## Connections

- User → CLI: runs commands (evidence: `README.md`)
- User → Python API: calls API (evidence: `README.md`)
- CLI → Fraud Domain: selects domain (evidence: `graphfaker/cli.py`)
- CLI → Coordination Domain: selects domain
- CLI → Supply Chain Domain: selects domain
- CLI → Social Domain: selects domain
- CLI → Schema Engine: runs schema (evidence: `graphfaker/cli.py`)
- Python API → Schema Engine: generates graph
- Social Domain → Graph Schema: declares graph (evidence: `graphfaker/domains/social.py`)
- Graph Schema → Attribute Samplers: defines attributes (evidence: `graphfaker/schema/graph.py`)
- Graph Schema → Pattern Schema: declares patterns
- Schema Drafter → Graph Schema: creates schema (evidence: `graphfaker/llm/draft.py`)
- Schema Engine → Attribute Sampling: samples attributes (evidence: `graphfaker/engine/run.py`)
- Schema Engine → Topology Builder: builds edges (evidence: `graphfaker/engine/run.py`)
- Schema Engine → Graph Tables: produces tables (evidence: `graphfaker/engine/run.py`)
- Process Generator → Pattern Schema: uses declarations (evidence: `graphfaker/engine/process.py`)
- Fraud Domain → Fraud Process: generates activity (evidence: `graphfaker/domains/fraud/process.py`)
- Fraud Domain → Pattern Injection: plants typologies (evidence: `graphfaker/domains/fraud/typologies.py`)
- Coordination Domain → Pattern Injection: plants playbooks (evidence: `graphfaker/domains/coordination/playbooks.py`)
- Supply Chain Domain → Pattern Injection: plants patterns (evidence: `graphfaker/domains/supply_chain/patterns.py`)
- CLI → File Export: writes dataset (evidence: `graphfaker/cli.py`)
- Graph Tables → Neo4j Sink: loads tables (evidence: `graphfaker/sinks/neo4j.py`)
- Graph Tables → Live Neo4j Sink: streams batches (evidence: `graphfaker/sinks/neo4j_live.py`)
- Graph Tables → Other Sinks: exports tables (evidence: `graphfaker/sinks/duckdb.py`)
- External Data → Real-World Fetchers: provides records (evidence: `README.md`)
- Real-World Fetchers → CLI: feeds graph (evidence: `graphfaker/cli.py`)
- Schema Engine → Ground Truth: records planted truth
- Graph Tables → Load Verification: checks loaded graph (evidence: `graphfaker/sinks/verify.py`)
- Ground Truth → Load Verification: checks ground truth (evidence: `graphfaker/sinks/verify.py`)
- Graph Tables → Entity Resolution: resolves entities
