The start page and your first map

The start page#

The start page is what DunneFlow shows when no map is open, which is how a freshly installed application begins. It is deliberately not the dashboard with everything emptied out: it says what is here, and offers the two things you can do about it.

• The lead line says how many programs have been mapped, or that none have.
• Maps are kept in shows the path to your maps, with two buttons. Show me opens it in Finder, File Explorer or your Linux file manager. Move… points DunneFlow somewhere else and optionally carries your maps across (see Installing).
• The program list shows every directory that actually holds a map, and how many points in time each holds (one point in time, 3 points in time). Click a row to open it. DunneFlow decides what is a map by looking inside a directory, never by its name.
• + Analyse a directory… reads a new tree.
• The footer states that nothing leaves this machine: the analysis is standard-library parsing and no part of it calls a model or opens a network connection.

If a map is already open and you come back to the start page (for example by visiting /start), an extra panel names it and offers Back to it or Close it. Closing returns the server to its start state; nothing on disk is touched, and a running analysis keeps running.

The Analyse a directory dialog#

Press + Analyse a directory… on the start page. The same entry sits in the program menu inside the dashboard, just above × Close this map, so you never have to leave a map to read another.

Directory to read is the whole path, as this machine sees it. A path relative to your terminal means nothing to the server, which reads the tree itself. Choose… opens a folder picker, and the typed field never goes away. For a Python project, point it at src/ or the package directory rather than the repository root.

Call it names the directory the map is written to. Leave it and DunneFlow uses the directory's own name.

Read the documentation too is on by default. DunneFlow scans the Markdown, reStructuredText and plain text beside the code as a separate, parallel corpus. That is what fills the glossary, the naming lanes and the second lane of Document view. Turn it off for a quicker, code-only map.

The pre-flight#

DunneFlow checks what you type as you type it, and Analyse stays disabled until it is satisfied. Each refusal has its own sentence. The one you are most likely to meet is:

dunneflow is the program being read — its graph is open here, and an analysis may
discard and re-extract it. Switch to another program first, or run this from a terminal.

That happens when you analyse into the name that is currently open, which would rewrite the graph the server is holding while you read it. Switch the program menu to something else first. Analysing into a name that exists but is not open is allowed, and the dialog says plainly that it rewrites that program's working snapshot. See When it refuses for the full list.

While it runs#

A progress panel appears bottom-right and stays there. You can dismiss it and keep reading: the map you already have open stays open and stays true for the whole run.

The steps are counted for this run, because the options you chose remove work. A full run reads the source tree, reads the documents, captures the document bodies, reads standards (only if you gave a standards directory), resolves calls and command trees, captures the source bodies, writes the map, and looks for anomalies.

If nothing has moved for several minutes, the panel says so and does nothing about it. Resolution can be quiet for a long time on a large program, so whether a run is stuck is your call.

Stopping it#

Stop it ends the run. What it had written stays on disk, marked unfinished. That mark matters: an analysis killed part-way leaves a graph that opens perfectly and is wrong, for example reporting every routine but no calls between them. So DunneFlow records whether its own analysis finished, and every command that vouches for a map refuses an unfinished one. Analysing again completes it quickly, because extraction is cached against the content of each file.

A stopped run is reported as stopped, not failed.

What it read, and what it left out#

A run from the command line ends by saying both:

files 118 (parsed 118, cached 0, removed 0, failed 0) in 1.7s
  read: python 107 · typescript 11
    typescript plugins/typescript/tsconfig.json: 11 files
    typescript opened in 0.3s
  unread: 8 .js, 5 .json, 4 .yaml, 2 .html, 1 .cjs, 1 .css, 1 .mjs — no reader here
  claims those suffixes
  …
  pruned 16 directories: __pycache__ ×14, node_modules, vendor

read: is per language, so you can tell a tree whose TypeScript was read from one that has none. Every line after it is a filter, and none is silent:

What you get#

A directory under your maps root, holding:

• graph@<instant>.db: every fact about the program, in SQLite. Every question the dashboard asks is a query against it.
• docs@<instant>.db: the documentation, in a parallel store that a documentation rescan can rebuild without touching the graph.
• source.db and docsource.db: the bodies of what was read, held by content hash. This is what lets Code view show you the source months later, on a machine that never held the tree.
• map@<instant>/: fourteen Markdown documents about the program plus an index (entrypoints, flows, routines, data, boundaries, governance, database, network, anomalies, glossary, naming, traceability, mirror and constants). They are readable with no tooling at all, so you can send someone the answer rather than the application.

Then the dashboard opens. Next: The shell.