Workflows on Ghafoor's Personal Blog

Architecture Queries

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Architecture Queries

Deeper architecture questions for system understanding, design reviews, and technical decision-making.

🏗️ System-Level Questions

Overall Architecture

1graphify query "describe the overall architecture of this project"
2graphify query "what are the main architectural patterns used?"
3graphify query "how is the codebase organized at a high level?"

Data Flow

1graphify query "describe the data flow from YouTube URL to Hugo content page"
2graphify query "how does data flow through the dictionary extraction pipeline?"
3graphify query "what is the data flow for anki flashcard generation?"

Module Boundaries

1graphify query "what are the module boundaries in this project?"
2graphify query "which modules are tightly coupled?"
3graphify query "show the dependency graph between major subsystems"

🔧 Subsystem Deep-Dives

Pipeline Architecture

1graphify query "describe the youtube content pipeline architecture"
2graphify query "how does the vocabulary extraction pipeline handle errors?"
3graphify query "what are the stages in the anki generation pipeline?"

Configuration & Extensibility

1graphify query "how is configuration managed across the project?"
2graphify query "how do skills integrate with the main application?"
3graphify query "what extension points exist for adding new content types?"

Build & Deployment

1graphify query "describe the Hugo build process and customizations"
2graphify query "how does the task automation work?"
3graphify query "what are the deployment steps for this site?"

🎯 Design Review Questions

Before Adding Features

1graphify query "where would a new content type fit in the current architecture?"
2graphify query "what existing patterns should a new skill follow?"
3graphify query "which modules would a new pipeline stage touch?"

Refactoring Candidates

1graphify query "which modules have the most incoming dependencies?"
2graphify query "what are the most complex functions by cyclomatic complexity?"
3graphify query "which files are central hubs in the dependency graph?"

Technical Debt

1graphify query "where are the circular dependencies?"
2graphify query "which modules violate layering principles?"
3graphify query "what code is unused or unreachable?"

📊 Visualization Queries

Community Structure

1graphify query "what communities exist in the codebase?"
2graphify query "which files belong to the 'YouTube Pipeline' community?"
3graphify query "show the relationship between communities"

Centrality & Importance

1graphify query "which files are most central in the graph?"
2graphify query "what are the hub files that connect subsystems?"
3graphify query "which symbols are most referenced across the codebase?"

🧪 Example Session: Onboarding

 1# 1. Big picture
 2graphify query "project overview"
 3
 4# 2. Subsystems
 5graphify query "what are the main subsystems?"
 6# → Dictionary, YouTube, Anki, Lexicon, JupyterLite
 7
 8# 3. Pick one
 9graphify query "how does the Dictionary subsystem work?"
10
11# 4. Pipeline
12graphify query "describe the data flow in the Dictionary pipeline"
13
14# 5. Key files
15graphify explain scripts/dictionary/extract_vocab.py
16
17# 5. Config
18graphify query "how is the Dictionary pipeline configured?"
19
20# 6. Extension
21graphify query "how would I add a new vocabulary source?"

💡 Query Tips for Architecture

Tip	Example
Ask for “architecture” or “design”	`graphify query "architecture of the skill system"`
Use “data flow” for pipelines	`graphify query "data flow from transcript to Hugo page"`
Ask for “boundaries” for coupling	`graphify query "module boundaries in scripts/dictionary"`
Request “patterns” for conventions	`graphify query "patterns used for Hugo content generation"`

Next Steps

Dependency Tracing - Trace specific relationships
Impact Analysis - Assess change impact

Daily Usage

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Daily Usage

The most common Graphify queries you’ll run during daily development. Keep this page bookmarked.

🔑 The Golden Rule

Signal activity before EVERY command:

1mkdir -p graphify-out && touch graphify-out/.graphify-activity

🏗️ Architecture Questions

Project Overview

1graphify query "project overview"

Use when: Starting work, onboarding, or need a refresher.

How a System Works

1graphify query "how does the youtube content pipeline work?"
2graphify query "how does the dictionary extraction work?"
3graphify query "how does the anki generation work?"

Use when: Need to understand a subsystem before modifying it.

Dependency Tracing

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Dependency Tracing

Trace relationships between any two components using graphify path — the most powerful command for understanding how code connects.

🔗 The `path` Command

1# Always signal activity first
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# Trace from A to B
5graphify path <source> <target>

What It Shows

Node chain — Sequence of nodes connecting source to target
Edge types — imports_from, calls, contains, references
File locations — Exact paths and line numbers
Direction — Data/control flow direction

🎯 Common Use Cases

1. Script → Config (How does a script read config?)

1graphify path scripts/dictionary/yt-to-content-v2.py tasks/content.yaml

Typical output:

Impact Analysis

hello@ghafoorsblog.com (AG Sayyed) — Mon, 09 Nov 2026 00:00:00 +0000

Impact Analysis

Assess the impact of changes before you make them — find all dependents, trace ripple effects, and plan safe refactoring.

🎯 The Core Question

“If I change X, what breaks?”

Graphify answers this by finding all nodes that depend on X, directly or transitively.

🔍 Finding Direct Dependents

What Depends on This File?

1graphify query "what depends on scripts/dictionary/yt-to-content-v2.py?"
2graphify query "what depends on tasks/content.yaml?"
3graphify query "what depends on data/course/meta/providers-ags-storytelling.yaml?"

What Calls This Function?

1graphify query "what calls mergeParams?"
2graphify query "what calls the vocabulary extraction function?"

What Imports This Module?

1graphify query "what imports scripts/dictionary/extract_vocab.py?"

🌊 Tracing Transitive Dependents (Ripple Effects)

Full Dependency Chain

1# Find ALL transitive dependents (not just direct)
2graphify query "show the full dependency tree for scripts/dictionary/yt-to-content-v2.py"

Path to Each Dependent

1# For each dependent, trace the path
2graphify path scripts/dictionary/yt-to-content-v2.py tasks/content.yaml
3graphify path scripts/dictionary/yt-to-content-v2.py content/courses/ags/storytelling/j-wiebe/youtube-content/articulate-your-thoughts/index.md
4graphify path scripts/dictionary/yt-to-content-v2.py .github/skills/youtube-content/SKILL.md

📋 Pre-Refactoring Checklist

Before Changing a File

 1# 1. Signal activity
 2mkdir -p graphify-out && touch graphify-out/.graphify-activity
 3
 4# 2. Find direct dependents
 5graphify query "what depends on path/to/file.py?"
 6
 7# 3. Find function-level dependents
 8graphify query "what calls functionName in path/to/file.py?"
 9
10# 4. Trace to each dependent
11graphify path path/to/file.py dependent1
12graphify path path/to/file.py dependent2
13
14# 5. Assess risk
15# - How many dependents?
16# - How critical are they?
17# - Are tests covering them?

Before Changing a Function Signature

1# 1. Find all callers
2graphify query "what calls functionName?"
3
4# 2. For each caller, trace the call chain
5graphify path path/to/file.py caller1
6graphify path path/to/file.py caller2
7
8# 3. Check if callers are in tests
9graphify query "which callers of functionName are in test files?"

Before Deleting a File

1# 1. Comprehensive dependent check
2graphify query "what depends on path/to/file.py?"
3
4# 2. Check if it's an entry point
5graphify query "is path/to/file.py an entry point or imported by tasks?"
6
7# 3. Verify no dynamic imports
8grep -r "import.*path/to/file" . --include="*.py" --include="*.js" --include="*.ts"

🎯 Real-World Examples

Example 1: Changing the YouTube Content Script

Scenario: Modify scripts/dictionary/yt-to-content-v2.py to add a new CLI flag.

Workflows on Ghafoor's Personal Blog

Architecture Queries

Architecture Queries

🏗️ System-Level Questions

Overall Architecture

Data Flow

Module Boundaries

🔧 Subsystem Deep-Dives

Pipeline Architecture

Configuration & Extensibility

Build & Deployment

🎯 Design Review Questions

Before Adding Features

Refactoring Candidates

Technical Debt

📊 Visualization Queries

Community Structure

Centrality & Importance

🧪 Example Session: Onboarding

💡 Query Tips for Architecture

Next Steps

Daily Usage

Daily Usage

🔑 The Golden Rule

🏗️ Architecture Questions

Project Overview

How a System Works

Dependency Tracing

Dependency Tracing

🔗 The path Command

What It Shows

🎯 Common Use Cases

1. Script → Config (How does a script read config?)

Impact Analysis

Impact Analysis

🎯 The Core Question

🔍 Finding Direct Dependents

What Depends on This File?

What Calls This Function?

What Imports This Module?

🌊 Tracing Transitive Dependents (Ripple Effects)

Full Dependency Chain

Path to Each Dependent

📋 Pre-Refactoring Checklist

Before Changing a File

Before Changing a Function Signature

Before Deleting a File

🎯 Real-World Examples

Example 1: Changing the YouTube Content Script

🔗 The `path` Command