flow

Documentation

Overview

Package flow generates architecture flow diagrams from the codeiq graph.

Mirrors src/main/java/io/github/randomcodespace/iq/flow/ — `View` is the enum of supported diagram views, `Engine` queries the graph, the builders in this file produce a `Diagram` per view, and `Renderer` emits Mermaid / JSON / DOT / YAML.

Five views match the Java side exactly:

• overview: 4 subgraphs (CI, Infrastructure, Application, Security)
• ci: CI/CD pipeline detail (workflows, jobs, triggers)
• deploy: K8s / Docker / Terraform topology
• runtime: endpoints / entities / messaging grouped by layer
• auth: guards / endpoints / protection coverage

Index

• func IsKnownView(s string) bool
• func Render(d *Diagram, format string) (string, error)
• func RenderDOT(d *Diagram) string
• func RenderJSON(d *Diagram) (string, error)
• func RenderMermaid(d *Diagram) string
• func RenderYAML(d *Diagram) (string, error)
• type Diagram
  • func NewDiagram(title, view string) *Diagram
  • func (d *Diagram) AllNodes() []Node
  • func (d *Diagram) ValidEdges() []Edge
• type Edge
  • func NewEdge(source, target string) Edge
  • func NewLabelEdge(source, target, label string) Edge
  • func NewStyledEdge(source, target, label, style string) Edge
• type Engine
  • func NewEngine(store Store) *Engine
  • func NewEngineFromSnapshot(snap *Snapshot) *Engine
  • func (e *Engine) Generate(ctx context.Context, view View) (*Diagram, error)
  • func (e *Engine) GenerateAll(ctx context.Context) (map[View]*Diagram, error)
• type Node
  • func NewNode(id, label, kind string) Node
  • func NewNodeWithProps(id, label, kind string, props map[string]any) Node
  • func NewNodeWithStyle(id, label, kind, style string, props map[string]any) Node
• type Snapshot
  • func LoadSnapshot(store Store) (*Snapshot, error)
  • func NewSnapshot(nodes []*model.CodeNode, edges []*model.CodeEdge) *Snapshot
  • func (s *Snapshot) Count() int
  • func (s *Snapshot) EdgesFrom(id string) []*model.CodeEdge
  • func (s *Snapshot) FindByKind(kind model.NodeKind) []*model.CodeNode
• type Store
• type Subgraph
  • func NewSubgraph(id, label string, nodes []Node) Subgraph
  • func NewSubgraphWithDrillDown(id, label string, nodes []Node, drillDownView string) Subgraph
• type View
  • func AllViews() []View

Functions

func IsKnownView

func IsKnownView(s string) bool

IsKnownView reports whether the supplied string identifies a built-in view. Used by the `flow` CLI and the `generate_flow` MCP tool to reject typos before opening the graph.

func Render

func Render(d *Diagram, format string) (string, error)

Render emits the Diagram in the requested format. Recognised formats: json (default), mermaid, dot, yaml. Returns an error for unknown formats.

func RenderDOT

func RenderDOT(d *Diagram) string

RenderDOT emits the diagram as a Graphviz DOT digraph string. Subgraphs are emitted as `cluster_*` for visual grouping in Graphviz output.

func RenderJSON

func RenderJSON(d *Diagram) (string, error)

RenderJSON emits the diagram as indented JSON. Field names match the Java FlowRenderer.renderJson output exactly so parity diffs match 1:1.

func RenderMermaid

func RenderMermaid(d *Diagram) string

RenderMermaid emits the diagram as a Mermaid `graph` flowchart string. The output is deterministic — nodes within each subgraph and edges are sorted by ID before emission.

func RenderYAML

func RenderYAML(d *Diagram) (string, error)

RenderYAML emits the diagram as YAML. The mapping uses the same key names as the JSON output.

Types

type Diagram

type Diagram struct {
	Title      string         `json:"title"`
	View       string         `json:"view"`
	Direction  string         `json:"direction"`
	Subgraphs  []Subgraph     `json:"subgraphs"`
	LooseNodes []Node         `json:"loose_nodes"`
	Edges      []Edge         `json:"edges"`
	Stats      map[string]any `json:"stats"`
}

Diagram is the complete flow diagram. Renderers consume this structure directly; no other shape is exposed.

func NewDiagram

func NewDiagram(title, view string) *Diagram

NewDiagram constructs an empty diagram for the supplied view with the default left-to-right ("LR") direction and pre-allocated slices/maps.

func (*Diagram) AllNodes

func (d *Diagram) AllNodes() []Node

AllNodes returns every node across both loose nodes and subgraph nodes. Order matches the Java side: loose nodes first, then each subgraph's nodes in subgraph order.

func (*Diagram) ValidEdges

func (d *Diagram) ValidEdges() []Edge

ValidEdges returns the edges whose source AND target IDs exist on a node in the diagram. Dangling references are silently dropped — matches the Java side's FlowDiagram.toMap behaviour.

type Edge

type Edge struct {
	Source string `json:"source"`
	Target string `json:"target"`
	Label  string `json:"label,omitempty"`
	Style  string `json:"style"`
}

Edge is one edge in a flow diagram. Edges are filtered against the set of valid node IDs during rendering — dangling edges are dropped.

func NewEdge

func NewEdge(source, target string) Edge

NewEdge constructs a solid, unlabelled edge.

func NewLabelEdge

func NewLabelEdge(source, target, label string) Edge

NewLabelEdge constructs a solid edge with a label.

func NewStyledEdge

func NewStyledEdge(source, target, label, style string) Edge

NewStyledEdge constructs an edge with an explicit style (solid | dotted | thick).

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is the flow-diagram generator. Stateless apart from the bound Store; safe for concurrent calls because Generate loads a fresh Snapshot every invocation.

Mirrors src/main/java/.../flow/FlowEngine.java.

func NewEngine

func NewEngine(store Store) *Engine

NewEngine constructs an Engine over the given Store.

func NewEngineFromSnapshot

func NewEngineFromSnapshot(snap *Snapshot) *Engine

NewEngineFromSnapshot constructs an Engine that returns the supplied snapshot from every call — useful for tests that want to avoid the Kuzu round trip.

func (*Engine) Generate

func (e *Engine) Generate(ctx context.Context, view View) (*Diagram, error)

Generate produces the Diagram for the named view. Returns an error when view is unknown.

func (*Engine) GenerateAll

func (e *Engine) GenerateAll(ctx context.Context) (map[View]*Diagram, error)

GenerateAll produces a Diagram for every supported view in declaration order. Loads the snapshot once and dispatches to every view builder.

type Node

type Node struct {
	ID         string         `json:"id"`
	Label      string         `json:"label"`
	Kind       string         `json:"kind"`
	Style      string         `json:"style"`
	Properties map[string]any `json:"properties"`
}

Node is one node in a flow diagram. The diagram is a collapsed / summarized view of the underlying graph, so a single flow Node frequently represents a *category* of graph nodes (e.g. "Endpoints x42").

func NewNode

func NewNode(id, label, kind string) Node

NewNode constructs a Node with default style ("default") and empty properties. Use NewNodeWithProps / NewNodeWithStyle for richer cases.

func NewNodeWithProps

func NewNodeWithProps(id, label, kind string, props map[string]any) Node

NewNodeWithProps constructs a Node with the supplied properties map.

func NewNodeWithStyle

func NewNodeWithStyle(id, label, kind, style string, props map[string]any) Node

NewNodeWithStyle constructs a Node with an explicit style class (default | success | warning | danger). The style maps to Mermaid classDef and DOT color attributes.

type Snapshot

type Snapshot struct {
	Nodes []*model.CodeNode
	Edges []*model.CodeEdge
	// contains filtered or unexported fields
}

Snapshot is a materialised view of the graph used by every view builder. Loading once at the top of Generate avoids the per-view round trip the Java `FlowDataSource.findByKind` pattern caused. Snapshot is read-only and safe to share across goroutines.

Mirrors the Java side's CacheFlowDataSource — pre-loaded in memory so view builders are pure functions over (nodes, edges).

func LoadSnapshot

func LoadSnapshot(store Store) (*Snapshot, error)

LoadSnapshot loads every node and edge from store. On large graphs this is materially heavier than the Java CacheFlowDataSource path; the flow command surface accepts the trade because it is interactive (one human call) rather than hot-path.

func NewSnapshot

func NewSnapshot(nodes []*model.CodeNode, edges []*model.CodeEdge) *Snapshot

NewSnapshot constructs a Snapshot over the supplied nodes and edges. Both slices are retained by reference — do not mutate after passing.

func (*Snapshot) Count

func (s *Snapshot) Count() int

Count returns the total node count. Mirrors Java FlowDataSource.count().

func (*Snapshot) EdgesFrom

func (s *Snapshot) EdgesFrom(id string) []*model.CodeEdge

EdgesFrom returns edges whose source ID matches.

func (*Snapshot) FindByKind

func (s *Snapshot) FindByKind(kind model.NodeKind) []*model.CodeNode

FindByKind returns every node of the given kind. The result slice is a pointer back into Snapshot.Nodes — callers MUST NOT modify it.

type Store

type Store interface {
	LoadAllNodes() ([]*model.CodeNode, error)
	LoadAllEdges() ([]*model.CodeEdge, error)
}

Store is the minimum graph surface Engine needs. *graph.Store satisfies this; tests use an in-memory fake.

type Subgraph

type Subgraph struct {
	ID            string `json:"id"`
	Label         string `json:"label"`
	Nodes         []Node `json:"nodes"`
	DrillDownView string `json:"drill_down_view,omitempty"`
	ParentView    string `json:"parent_view,omitempty"`
}

Subgraph is a labelled group of nodes. Subgraphs may declare a drill-down view that the UI follows when the user expands the group.

func NewSubgraph

func NewSubgraph(id, label string, nodes []Node) Subgraph

NewSubgraph constructs a subgraph with no drill-down hint.

func NewSubgraphWithDrillDown

func NewSubgraphWithDrillDown(id, label string, nodes []Node, drillDownView string) Subgraph

NewSubgraphWithDrillDown constructs a subgraph with a drill-down view.

type View

type View string

View is a single supported flow view. The string value is the canonical identifier used in CLI args, MCP tool params, and stored output paths.

const (
	// ViewOverview is the high-level architecture overview.
	ViewOverview View = "overview"
	// ViewCI is the CI/CD pipeline detail view.
	ViewCI View = "ci"
	// ViewDeploy is the deployment topology view.
	ViewDeploy View = "deploy"
	// ViewRuntime is the runtime architecture view.
	ViewRuntime View = "runtime"
	// ViewAuth is the auth / security view.
	ViewAuth View = "auth"
)

func AllViews

func AllViews() []View

AllViews returns every supported view in declaration order. The order matches the Java side `FlowEngine.AVAILABLE_VIEWS` constant.