← Project Graph

PROJECT GRAPH FEATURE

Project Graph Overview

Project Graph is not a mandatory startup ritual. It is a package-level structural memory that you reach for when a task needs real architecture answers instead of guesses.

Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Project Graph is a package-level architecture memory for Semitexa repositories. It persists structural facts about modules, handlers, services, events, flows, and dependencies so engineers and AI can work from the actual system shape instead of rediscovering it repeatedly.

How it works

Use it on demand. Start from the task, fetch graph-backed context when structure matters, refresh the stored graph only when answers are stale, and then choose the narrowest command that answers the question: show, query, module, intelligence, impact, or context.

Why it matters

This matters because large repositories do not become easier just by adding more docs. Project Graph turns architecture into a reusable artifact: onboarding accelerates, impact analysis gets safer, AI prompts shrink, and structural questions stop triggering another round of blind grep.

Key concepts

task-first workflow
A graph-assisted workflow that starts from the task and only reaches for structural commands when the task actually needs them.
stored structural graph
A persisted architecture map of nodes and edges that can be reused across onboarding, review, and AI-assisted work.
intelligence layer
Higher-level answers built on top of the graph: hotspots, domain context, event lifecycles, inferred intent, and natural-language structural queries.
package-level capability
The graph surface belongs to the `semitexa-project-graph` package and is available where that package is installed and enabled.

Package Workflow

Start from the task, then reach for structural context only when the task needs it

The important upgrade is not “one more command namespace.” It is that the repository can answer architecture questions from stored structure and intelligence instead of forcing every engineer or agent to rediscover the same system shape from scratch.

Step 1

Start from the task

Project Graph is most useful when it is task-scoped. Begin with the work you are trying to do, then ask the graph for only the context that task actually needs.

bin/semitexa ai:task "trace checkout architecture"
bin/semitexa ai:review-graph:context "trace checkout architecture" --format=json

Step 2

Refresh only when graph answers are stale

The graph is stored separately and can be refreshed incrementally. Rebuild it when you need fresh graph-backed answers, not as a reflex before every single edit.

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

Step 3

Choose the narrowest structural question

Once the graph exists, you do not need one generic “graph mode.” You can ask for a readable slice, a hotspot view, an impact radius, or a task-specific context package.

bin/semitexa ai:review-graph:show --format=markdown --module=Demo
bin/semitexa ai:review-graph:impact Semitexa\\Demo\\Application\\Service\\DemoCatalogService --json
bin/semitexa ai:review-graph:intelligence --hotspots

Why Teams Care

  • The graph surface belongs to the package, so teams can add this capability intentionally instead of pretending every install already has it.
  • Humans and AI both benefit from the same stored architecture artifact instead of maintaining separate onboarding rituals.
  • Impact, hotspots, flow traces, and task context are materially different answers; Project Graph gives each of them a dedicated surface.
  • Graph storage stays isolated from the main application database, so architecture data does not pollute runtime domain data.
semitexa-project-graph task-first workflow intelligence layer stored structural graph

Verified against Semitexa Ultimate 2026.09.19.1020

Project Graph Overview

Project Graph is the package-level architecture memory for a Semitexa repository.

It persists structural facts about modules, handlers, services, events, flows, and dependencies so humans and AI can start from the actual system shape instead of rediscovering it task after task.

Canonical workflow

  1. Start from the task, not from a graph ritual.
  2. Reach for graph-backed context when the task needs structural understanding.
  3. Refresh the stored graph only when those answers are stale or missing.
  4. Choose the narrowest graph command that answers the question.

Commands

bin/semitexa ai:task "trace checkout architecture"
bin/semitexa ai:review-graph:context "trace checkout architecture" --format=json
bin/semitexa ai:review-graph:generate --json
bin/semitexa ai:review-graph:stats --json
bin/semitexa ai:review-graph:show Demo --format=markdown
bin/semitexa ai:review-graph:intelligence --hotspots

Why this matters

Project Graph is valuable because it turns architecture into a reusable artifact. Onboarding gets faster, structural review gets safer, impact analysis becomes easier, and AI prompts stop starting from random file sampling.

© Edsger W. Dijkstra: "Simplicity is prerequisite for reliability."

Demo Package README Implementation slice 
# About Semitexa"Make it work, make it right, make it fast." — Kent BeckSemitexa isn't just a framework; it's a philosophy of efficiency.Engineered for the high-performance Swoole ecosystem and built with an AI-first mindset,it allows you to stop fighting the infrastructure and start building the future.Simple by design. Powerful by nature.## Requirements- Docker and Docker Compose- Composer (on host for install)## InstallFrom an empty folder (get the framework and install dependencies):```bashcomposer require semitexa/core```From a clone or existing project (dependencies already in `composer.json`):```bashcomposer install```Then:```bashcp .env.example .env```## Run (Docker — supported way)```bashbin/semitexa server:start```To stop:```bashbin/semitexa server:stop```Default URL: **http://0.0.0.0:9502** (configurable via `.env` `SWOOLE_PORT`).## DocumentationProject-level docs live in `docs/`. Package-level deep reference lives in `vendor/` (or `packages/` in the monorepo).| Topic | File or folder ||-------|----------------|| **AI context for this project** | [docs/AI_CONTEXT.md](docs/AI_CONTEXT.md) || **Running the app** — Docker, ports, logs | [vendor/semitexa/core/docs/RUNNING.md](vendor/semitexa/core/docs/RUNNING.md) || **Adding pages and routes** — modules, Request/Handler | [vendor/semitexa/core/docs/ADDING_ROUTES.md](vendor/semitexa/core/docs/ADDING_ROUTES.md) || **Attributes** — AsPayload, AsPayloadHandler, AsResource, etc. | [vendor/semitexa/core/docs/attributes/README.md](vendor/semitexa/core/docs/attributes/README.md) || **Service contracts** — contracts:list, active implementation | [vendor/semitexa/core/docs/SERVICE_CONTRACTS.md](vendor/semitexa/core/docs/SERVICE_CONTRACTS.md) || **Package map & conventions** (if semitexa/docs is installed) | [vendor/semitexa/docs/README.md](vendor/semitexa/docs/README.md) · [vendor/semitexa/docs/guides/CONVENTIONS.md](vendor/semitexa/docs/guides/CONVENTIONS.md) |Use `docs/` for app-level guides and decisions. Use package docs in `vendor/semitexa/` for framework internals and reference material.## Structure- `src/modules/` – your application modules (add new pages and endpoints here). New routes only in modules.- `docs/` – project-level canonical documentation for this app.- `var/docs/` – working directory for notes, drafts, and research; not canonical.- `AI_ENTRY.md` – entry point for AI assistants; `AI_NOTES.md` – your notes (never overwritten).## Tests```bashcomposer require --dev phpunit/phpunit``````bashvendor/bin/phpunit```Use `phpunit.xml.dist`; add tests in `tests/`.

Decision Model

The graph improves structural decision quality, not just command count

Search still matters for local text facts. Project Graph matters when the question is architectural: what depends on this, what flows through here, what is high-risk, and what context actually belongs in the next review or AI prompt.

The practical gain is not just speed. It is that onboarding, refactors, code review, and AI work stop starting from zero every time.

That makes Project Graph a serious package capability, not decorative metadata and not a demo-only gimmick.

Question Without Project Graph With Project Graph
Do I need the graph for every task? Usually the team invents a ritual and runs it blindly. No. Start from the task and use graph commands only when structure matters.
What changes once the package is enabled? Architecture stays scattered across files, docs, and oral explanations. The repository gains a stored graph plus intelligence and context-packing surfaces.
What can it answer beyond node lists? Engineers must improvise with grep, memory, and assumption chains. Flows, events, hotspots, impact, module context, and AI-ready packages become explicit.
Why is this better than plain repository search? Search answers local text matches but not system shape. Graph-backed answers are structural, reusable, and safer for review or AI work.

The promise is simple: less blind structural exploration, more reusable architectural truth.

Related features

How it works

Use it on demand. Start from the task, fetch graph-backed context when structure matters, refresh the stored graph only when answers are stale, and then choose the narrowest command that answers the question: show, query, module, intelligence, impact, or context.

Why it matters

This matters because large repositories do not become easier just by adding more docs. Project Graph turns architecture into a reusable artifact: onboarding accelerates, impact analysis gets safer, AI prompts shrink, and structural questions stop triggering another round of blind grep.

Key concepts

task-first workflow
A graph-assisted workflow that starts from the task and only reaches for structural commands when the task actually needs them.
stored structural graph
A persisted architecture map of nodes and edges that can be reused across onboarding, review, and AI-assisted work.
intelligence layer
Higher-level answers built on top of the graph: hotspots, domain context, event lifecycles, inferred intent, and natural-language structural queries.
package-level capability
The graph surface belongs to the `semitexa-project-graph` package and is available where that package is installed and enabled.

Operational Notes

What makes the package workflow trustworthy

The graph only helps when teams are explicit about scope, freshness, and installation context.

Project Graph uses its own named connection, so the architecture map stays separate from the main application database.

The default local fallback is a dedicated SQLite file under `var/tmp/project-graph.sqlite`, which makes first use straightforward.

Treat refresh as conditional: rebuild or verify freshness when graph-backed answers are stale, not as a startup ritual for every task.

Be explicit that `ai:review-graph:*` commands belong to installs where `semitexa-project-graph` is enabled.

Support Semitexa
Built for developers who prefer control over magic. Your support helps keep it fast, open, and evolving.

Donate via PayPal