# abhinavbwj/aec-knowledge-graph architecture

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

- Interactive diagram: https://gitdiagram.com/abhinavbwj/aec-knowledge-graph
- Repository: https://github.com/abhinavbwj/aec-knowledge-graph

## Overview

AEC Knowledge Graph turns curated JSONL entities and relationships, plus extracted skill references, into an embedded Kuzu graph that engineers can query from the CLI or Python. The main workflow is seed or plugin input → ETL/validation → database build → canonical Cypher queries → results. Query capabilities include influence paths, project discovery and profiles, movement and standards lineage, skill citations, and graph statistics. The source excerpts show the main wiring; the documented sibling-plugin inputs are external to this repository.

Main entry points: [`src/aec_kg/query.py`](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py) (Canonical queries), [`src/aec_kg/cli.py`](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/cli.py) (CLI), [`src/aec_kg/load.py`](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/load.py) (Graph builder), [`src/aec_kg/etl/from_trinity.py`](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/etl/from_trinity.py) (Skill ETL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Graph inputs"]
  node_seed_nodes["Seed entities"]
  node_seed_edges["Seed relations"]
  node_auto_data["ETL output"]
end

subgraph group_ingestion["Ingestion and storage"]
  node_etl["Skill ETL<br/>[from_trinity.py]"]
  node_schema["Pydantic models<br/>[schema.py]"]
  node_loader["Graph builder<br/>[load.py]"]
  node_kuzu[("Kuzu graph<br/>[load.py]")]
end

subgraph group_querying["Query and access"]
  node_cli["CLI<br/>[cli.py]"]
  node_queries["Canonical queries<br/>[query.py]"]
  node_project_queries["Project discovery<br/>[query.py]"]
  node_lineage_queries["Influence and lineage<br/>[query.py]"]
  node_skill_queries["Skill citations<br/>[query.py]"]
  node_stats["Graph statistics<br/>[query.py]"]
  node_results["Query results<br/>[query.py]"]
end

node_user(("Engineer"))
node_python_api(("Python callers"))
node_plugin_sources["Sibling plugins"]

node_user -->|"invokes"| node_cli
node_cli -->|"runs ETL"| node_etl
node_plugin_sources -->|"provides skills"| node_etl
node_seed_nodes -->|"supplies aliases"| node_etl
node_etl -->|"validates output"| node_schema
node_etl -->|"writes JSONL"| node_auto_data
node_cli -->|"builds graph"| node_loader
node_seed_nodes -->|"loads entities"| node_loader
node_seed_edges -->|"loads relations"| node_loader
node_auto_data -->|"merges ETL data"| node_loader
node_loader -->|"validates records"| node_schema
node_loader -->|"creates and populates"| node_kuzu
node_user -.->|"calls"| node_python_api
node_python_api -->|"requests queries"| node_queries
node_cli -->|"dispatches queries"| node_queries
node_cli -->|"requests counts"| node_stats
node_queries -->|"opens connection"| node_kuzu
node_queries -->|"uses graph labels"| node_schema
node_queries -->|"supports"| node_project_queries
node_queries -->|"supports"| node_lineage_queries
node_queries -->|"supports"| node_skill_queries
node_queries -->|"counts labels"| node_stats
node_project_queries -->|"returns project data"| node_results
node_lineage_queries -->|"returns paths"| node_results
node_skill_queries -->|"returns citations"| node_results
node_stats -->|"returns counts"| node_results
node_queries -->|"returns rows"| node_results
node_cli -->|"prints results"| node_results

click node_cli "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/cli.py"
click node_seed_nodes "https://github.com/abhinavbwj/aec-knowledge-graph/tree/main/data/nodes"
click node_seed_edges "https://github.com/abhinavbwj/aec-knowledge-graph/tree/main/data/edges"
click node_etl "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/etl/from_trinity.py"
click node_auto_data "https://github.com/abhinavbwj/aec-knowledge-graph/tree/main/data/auto"
click node_schema "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/schema.py"
click node_loader "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/load.py"
click node_kuzu "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/load.py"
click node_queries "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py"
click node_project_queries "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py"
click node_lineage_queries "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py"
click node_skill_queries "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py"
click node_stats "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py"
click node_results "https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py"

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_seed_nodes,node_seed_edges,node_auto_data toneBlue
class node_etl,node_schema,node_loader,node_kuzu toneAmber
class node_cli,node_queries,node_project_queries,node_lineage_queries,node_skill_queries,node_stats,node_results toneMint
class node_user,node_python_api,node_plugin_sources toneIndigo
```

## Components

### Graph inputs

- [Seed entities](https://github.com/abhinavbwj/aec-knowledge-graph/tree/main/data/nodes): `data/nodes`
- [Seed relations](https://github.com/abhinavbwj/aec-knowledge-graph/tree/main/data/edges): `data/edges`
- [ETL output](https://github.com/abhinavbwj/aec-knowledge-graph/tree/main/data/auto): `data/auto`

### Ingestion and storage

- [Skill ETL](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/etl/from_trinity.py): `src/aec_kg/etl/from_trinity.py`
- [Pydantic models](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/schema.py): `src/aec_kg/schema.py`
- [Graph builder](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/load.py): `src/aec_kg/load.py`
- [Kuzu graph](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/load.py): `src/aec_kg/load.py`

### Query and access

- [CLI](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/cli.py): `src/aec_kg/cli.py`
- [Canonical queries](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py): `src/aec_kg/query.py`
- [Project discovery](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py): `src/aec_kg/query.py`
- [Influence and lineage](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py): `src/aec_kg/query.py`
- [Skill citations](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py): `src/aec_kg/query.py`
- [Graph statistics](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py): `src/aec_kg/query.py`
- [Query results](https://github.com/abhinavbwj/aec-knowledge-graph/blob/main/src/aec_kg/query.py): `src/aec_kg/query.py`

### Other components

- **Engineer**
- **Python callers**
- **Sibling plugins**

## Connections

- Engineer → CLI: invokes (evidence: `src/aec_kg/cli.py`)
- CLI → Skill ETL: runs ETL (evidence: `src/aec_kg/cli.py`)
- Sibling plugins → Skill ETL: provides skills (evidence: `src/aec_kg/etl/from_trinity.py`)
- Seed entities → Skill ETL: supplies aliases (evidence: `src/aec_kg/etl/from_trinity.py`)
- Skill ETL → Pydantic models: validates output (evidence: `src/aec_kg/etl/from_trinity.py`)
- Skill ETL → ETL output: writes JSONL (evidence: `src/aec_kg/etl/from_trinity.py`)
- CLI → Graph builder: builds graph (evidence: `src/aec_kg/cli.py`)
- Seed entities → Graph builder: loads entities (evidence: `src/aec_kg/load.py`)
- Seed relations → Graph builder: loads relations (evidence: `src/aec_kg/load.py`)
- ETL output → Graph builder: merges ETL data (evidence: `src/aec_kg/load.py`)
- Graph builder → Pydantic models: validates records (evidence: `src/aec_kg/load.py`)
- Graph builder → Kuzu graph: creates and populates (evidence: `src/aec_kg/load.py`)
- Engineer → Python callers: calls (evidence: `README.md`)
- Python callers → Canonical queries: requests queries (evidence: `README.md`)
- CLI → Canonical queries: dispatches queries (evidence: `src/aec_kg/cli.py`)
- CLI → Graph statistics: requests counts (evidence: `src/aec_kg/cli.py`)
- Canonical queries → Kuzu graph: opens connection (evidence: `src/aec_kg/query.py`)
- Canonical queries → Pydantic models: uses graph labels (evidence: `src/aec_kg/query.py`)
- Canonical queries → Project discovery: supports (evidence: `README.md`)
- Canonical queries → Influence and lineage: supports (evidence: `README.md`)
- Canonical queries → Skill citations: supports (evidence: `README.md`)
- Canonical queries → Graph statistics: counts labels (evidence: `src/aec_kg/query.py`)
- Project discovery → Query results: returns project data (evidence: `src/aec_kg/query.py`)
- Influence and lineage → Query results: returns paths (evidence: `src/aec_kg/query.py`)
- Skill citations → Query results: returns citations (evidence: `src/aec_kg/query.py`)
- Graph statistics → Query results: returns counts (evidence: `src/aec_kg/query.py`)
- Canonical queries → Query results: returns rows (evidence: `src/aec_kg/query.py`)
- CLI → Query results: prints results (evidence: `src/aec_kg/cli.py`)
