Graphtia documentation · workflow
Plan a migration with code and dependency evidence
Plan framework, API, service and database-schema changes using Explorer’s source relationships, impact candidates and related tests.
This workflow uses current Explorer capabilities to investigate a proposed change. It produces evidence for a plan that you write and validate; it does not execute a migration.
Build the plan around a concrete change
1. Define the change and its constraints
Choose the feature, service, API operation or declared table you intend to change. Record the target design and external requirements your team will verify.
2. Establish the indexed baseline
Register and index the relevant workspace, then check the published revision, supported coverage and currentness. Keep missing helpers, unsupported files and unresolved facts visible.
3. Trace the relevant relationships
Locate the concrete symbols or contracts. Inspect direct callers, dependents and dependencies, then expand only the paths or supported boundaries that matter to the migration.
4. Build a validation checklist
Inspect related-test candidates and their source. List runtime, deployment, database and unsupported behavior that static evidence cannot settle.
5. Plan and implement a bounded slice
Use the reviewed evidence to choose a small change set. Make the code and configuration changes in your development tools, run your tests and carry out database or deployment work through your normal processes.
6. Refresh the evidence and review again
Update the index after the change and check currentness before using new results. Where retained published revisions are available, compare them and record the evidence for the next decision. Keep runtime test results separate from structural observations.
Four migration-planning examples
The following are illustrative workflows, not customer case studies or automatic migration results.
Prepare a framework upgrade or replacement
Inspect supported route, controller, middleware and Blade relationships. Follow the feature's dependencies and direct consumers, then review related-test candidates before choosing the first implementation slice.
Framework recognition does not certify compatibility with a target version. Runtime macros, container behavior and dynamic configuration can remain unresolved. Obtain upgrade requirements from the target framework's official documentation.
Review an API change across its callers and contract
Inspect the OpenAPI operation and supported handler candidates, then follow indexed HTTP consumers and their source evidence where a supported static match exists. Review related tests and the contract assumptions that need integration testing.
A single candidate is not a universal contract-to-code proof. Explorer's stronger Next association is limited to exact method/path/application-scope evidence, supported server context, neutral published configuration and a confirmed binding edge. No automatic breaking-change certification, deployment check or response-conformance guarantee is implied.
Plan a schema change with its code context
Inspect supported table, field, key, index and migration declarations. Follow code-to-table evidence for supported Python and TypeScript/JavaScript patterns, then review the exact SQL-site owners and associated test candidates. Where needed, compare declarations with DDL you explicitly supply.
Code-to-table coverage is pattern-specific and does not prove every reader, writer or column dependency. EF Core/JPA structure does not automatically imply the Python/TS code-to-table surface. Supplied DDL comparison and ordered declared composition do not connect to a database, apply migrations or verify locks, data, backfills or applied state.
Evaluate a component before extracting it from a monolith
Inspect the component's direct dependents, shared modules and supported API or task boundaries. Follow selected cross-language relationships where the source provides a supported match. Use that evidence to discuss a candidate extraction boundary and sequence the changes your team will make.
Explorer does not choose an optimal service boundary, infer production traffic or verify arbitrary FFI and dynamic integrations. Supported cross-language boundaries remain within one authorized project/revision; separate registered projects do not automatically become a federated graph.
Questions to ask your coding agent
Using the authorized project's current indexed revision, help me plan a change to the orders API. Identify the relevant operation and handler candidates, inspect direct consumers and related-test candidates, and cite the supporting source. Keep the scope bounded and list unresolved behavior and checks that require execution. Do not treat a missing result as proof of no dependency.
What is in the indexed project?
get_project_summary, get_architecture_projection
Check revision, coverage and currentness; a bounded architecture projection is not a complete repository dump.
Where is the component and who uses it?
search_symbol, resolve_symbol, get_symbol, get_callers, get_dependents, get_dependencies, get_references
Resolve canonical identities before relationship queries. Direct relationships use depth 1; inspect selected targets to answer the next concrete question.
What may be affected and which tests should I inspect?
get_blast_radius, get_related_tests, find_path
Treat impact as bounded static candidates and tests as associations. Neither predicts every failure or proves test execution.
What API declarations and supported boundaries are present?
get_api_catalog, get_contract_catalog, get_openapi_contract
Separate provider/consumer candidates, OpenAPI declarations and the narrow supported static association. Do not infer deployed endpoints or schema conformance.
Which declared database structures and code sites should I review?
get_db_schema, get_db_code_links
Use a cataloged SQL source and returned table/code identities. Check dialect, confidence, diagnostics and incomplete coverage. No live database state is queried.
What project decisions and prior evidence are indexed?
get_document_catalog, search_documents, get_document
Documentary evidence is separate from code relations. Search covers metadata and a bounded prefix, not the complete text of every document.
How do retained indexed publications differ?
get_project_summary
Use returned from_graph_version and to_graph_version values for retained-manifest comparison. This is not an arbitrary Git diff or a guarantee that pruned history is available.
Keep implementation and evidence separate
Select and authorize each registered workspace separately. Keep project, revision and canonical IDs together; grants and cursor tokens are not interchangeable. An external agent's editing tools have their own authorization outside Explorer's structural queries.
Explorer supports the planning and review stages. Your team makes the source changes, runs tests, applies migrations and deploys through its normal tools. Framework recognition does not certify compatibility with the version you plan to adopt.