First Query
Run your first Graphify architecture query and understand the output.
On this page
First Query
Your first Graphify architecture question — from signal to answer.
Prerequisites
- Graphify installed (
uv tool install graphifyy && graphify install) - Graph built (
graphify . --code-onlyin your project root) - In your project directory
The Golden Rule: Signal Activity
Before EVERY Graphify command, you must signal activity:
1mkdir -p graphify-out && touch graphify-out/.graphify-activity
This is required by the GraphifyStats VS Code extension and prevents stale data warnings.
Your First Query
1# 1. Signal activity
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# 2. Ask an architecture question
5graphify query "project overview"
Expected Output
This project is a Hugo + HBStack site for a personal blog with course content.
The codebase includes:
**Core Systems:**
- Dictionary/vocabulary extraction pipeline (scripts/dictionary/)
- YouTube content automation (scripts/dictionary/yt-to-content-v2.py)
- Anki flashcard generation (scripts/anki/)
- CBT lexicon extraction (scripts/extract-cbt-lexicon.mjs)
**Content Structure:**
- Courses under content/courses/ags/ (spirituality, storytelling)
- Docs under content/docs/ (dictionary, anki, tutorials, lexicon)
- JupyterLite integration for interactive notebooks
**Build Pipeline:**
- Hugo with HBStack theme
- Task-based automation (Taskfile.yaml)
- Custom shortcodes for accordions, vocabulary, diagrams
Understanding the Output
| Element | Meaning |
|---|---|
| Natural language answer | Graphify synthesizes findings into readable text |
| File references | Specific paths cited (e.g., scripts/dictionary/yt-to-content-v2.py) |
| Architectural concepts | Components, pipelines, data flows identified |
Next Queries to Try
1# Always signal activity first!
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# How does a specific system work?
5graphify query "how does the youtube content pipeline work?"
6
7# What depends on a file?
8graphify query "what depends on tasks/content.yaml?"
9
10# Trace a relationship
11graphify path scripts/dictionary/yt-to-content-v2.py data/course/ags/storytelling/j-wiebe/youtube-content/course-structure.yaml
12
13# Deep-dive on a component
14graphify explain scripts/dictionary/yt-to-content-v2.py
Common Patterns
| Question Type | Query Template |
|---|---|
| Architecture overview | graphify query "project overview" |
| How X works | graphify query "how does X work?" |
| Dependencies of X | graphify query "what depends on X?" |
| Relationship A→B | graphify path A B |
| Deep-dive on file | graphify explain <file-path> |
Tips for Better Queries
- Use specific names from your codebase — “yt-to-content-v2.py” not “the script”
- Ask about concepts, not syntax — “how does auth work?” not “show me the login function”
- Iterate — Start broad, then drill down with
explainandpath - Rebuild if stale —
graphify update .after significant changes
Next Steps
- Daily Usage - Common query patterns for development
- Verification - Confirm your setup is correct