Extractors
Extractors
Section titled “Extractors”Extractors read brownfield source and emit review-only candidates for Topogram adoption.
Status: current Audience: developers, agents, and extractor package authors Use when: you need to understand what extractors do before selecting, authoring, or trusting an extractor package.
Extractors are execution dependencies for topogram extract. They inspect an
existing app and return findings, evidence, and candidates. Topogram core owns
normalization, persistence, reports, reconcile/adoption plans, and canonical
topo/** writes.
Extractor packages do not mutate source apps, write canonical Topogram records, install packages, or perform adoption. They are lower-level discovery dependencies, while templates are user-facing starting points.
Workflow Evidence
Section titled “Workflow Evidence”Ordinary stack extractors should not guess workflows. Prisma, Express, React
Router, and similar packages should emit precise DB, API, UI, CLI, or
verification evidence for their own track. Topogram core performs the
conservative cross-track v1 synthesis: it emits review-only workflow candidates
only when API capabilities map to a DB entity with a status or state enum.
Broader synthesis across UI, CLI, and verification evidence remains future
work.
Package-backed workflows extractors are for workflow-native sources: BPMN,
Temporal, XState, Step Functions, Camunda, Rails state machines, Django FSM,
and similar systems that directly encode states, transitions, orchestration, or
process definitions. Those packages may emit workflow_definitions,
workflow_states, and workflow_transitions, but adoption still remains an
explicit Topogram review step. See Workflow Extraction
for the focused command path.
Step Functions belongs in that workflow-native group when the source includes local Amazon States Language JSON or YAML. Treat AWS account discovery, execution history, and credential-backed inspection as later work; extractor v1 should be deterministic and local.
Design Evidence
Section titled “Design Evidence”Design-system extractors should propose review-only design realization
candidates, not canonical design decisions. Storybook support starts with the
first-party @topogram/extractor-storybook-design package. It reads static CSF
story files and only emits design_realizations when parameters.topogram
explicitly names the widget, design contract, component ref, platform, pattern,
and status. Missing or unsupported story metadata becomes findings for review.
Use it when a component library already documents stable component identities in
Storybook and you want Topogram to carry those mappings into adopt design-realizations review.
Extractor package repos can have their own llms.txt and llms-full.txt.
Those files describe the package-local authoring and safety surface; they are
separate from the root Topogram repo llms.txt. Scaffolded extractor packages
generate package-local docs checks that refuse links or writes outside the
package root.
Commands
Section titled “Commands”topogram extractor listtopogram extractor recommend ./existing-app --from db,api,ui,cli,workflowstopogram extractor show @topogram/extractor-prisma-dbtopogram extractor policy pin @topogram/extractor-prisma-db@1topogram extract ./existing-app --out ./extracted-topogram --from db --extractor @topogram/extractor-prisma-dbtopogram extractor show @topogram/extractor-xstate-workflowstopogram extractor policy pin @topogram/extractor-xstate-workflows@1topogram extract ./xstate-app --out ./extracted-topogram --from workflows --extractor @topogram/extractor-xstate-workflowstopogram extractor show @topogram/extractor-storybook-designtopogram extractor policy pin @topogram/extractor-storybook-design@1topogram extract ./storybook-library --out ./storybook-topogram --from ui --extractor @topogram/extractor-storybook-design