README

Project graph package for fast AI and developer understanding of a Semitexa codebase.

Scans PHP source files, extracts semantic information via attributes and AST analysis, and stores it as a directed graph of nodes and edges. Enables LLMs and developers to understand a codebase in minutes instead of hours.

Quick Start

# Generate or update the graph
bin/semitexa ai:review-graph:generate

# Confirm it's ready
bin/semitexa ai:review-graph:stats

Full Documentation

• Architecture — Graph data model, node/edge types, extractors, storage
• Commands — Complete CLI reference with examples
• AI Integration — How AI agents consume the graph
• Intelligence Layer — Domains, flows, events, hotspots, intent inference

Primary Workflow

Run these commands before deep code changes or code generation:

bin/semitexa ai:review-graph:generate --json
bin/semitexa ai:review-graph:stats --json

generate builds or incrementally refreshes the graph. stats confirms that the graph is ready and shows node/edge counts.

Intelligence Commands

Beyond basic graph queries, the intelligence layer provides:

# Trace an event's full lifecycle (emitters → listeners → NATS → replay → DLQ)
bin/semitexa ai:review-graph:event-trace OrderCreated

# Trace an execution flow end-to-end
bin/semitexa ai:review-graph:flow-trace CheckoutFlow

# Get context for a development task
bin/semitexa ai:review-graph:context "adding payment method"

# Analyze impact of changing a component
bin/semitexa ai:review-graph:impact PaymentService

# Module overview with domain, flows, events, hotspots
bin/semitexa ai:review-graph:module Ordering --include-events --include-flows

# See how the graph changed since last scan
bin/semitexa ai:review-graph:diff

# Watch for file changes and auto-update
bin/semitexa ai:review-graph:watch

All commands support --format=json for programmatic consumption by AI agents.

Storage

The graph uses its own named ORM connection: project_graph.

• Preferred configuration: DB_PROJECT_GRAPH_*
• Default fallback: dedicated SQLite database
• Local CLI fallback path: var/tmp/project-graph.sqlite

This keeps graph storage separate from the application's primary database.

Why AI agents should use it first

• It gives a fast structural view of the real project, not just static package docs.
• It is safer than assuming the default database connection.
• It reduces blind searching before edits.
• It reveals event flows and cross-module dependencies that are invisible from file-level analysis.

All Commands