Diagrams

A diagram is durable project knowledge, not a picture pasted into one chat. ContextStream stores its title, kind, and text definition so another supported assistant can find it, explain it, or revise it later.

The eight shapes

Pick the shape that matches the relationship you are trying to show:

Sequence diagrams are usually the clearest answer to “how does this request move through the system?” Entity-relationship diagrams are the right default for a database model. Flowcharts are better when the important part is a branch or decision.

Where diagrams earn their keep

Architecture. Save the service boundary, request path, or dependency shape while the people who understand it are present. Later, “why does this request touch the queue?” can be answered from the diagram and the decisions around it.

Operations. Put a failure path beside a runbook. The runbook says what to do; the diagram shows what is happening.

Planning. Attach a timeline or flow to a plan when ordered prose is not enough. A fresh session can inspect both without reconstructing the model from chat history.

Data work. Keep the current schema model close to the project rather than in a screenshot that becomes impossible to edit.

Creating and changing one

Ask for the outcome and the intended shape:

save a sequence diagram of sign-in, token refresh, and retry

Give it a specific title. “Auth refresh across the desktop client and API” is findable; “architecture diagram” is not.

The saved definition stays editable. Ask to add a service, rename a table, change a relationship, or replace the diagram when the architecture changes. If the old diagram remains useful historically, give the replacement a dated or versioned title instead of silently changing the record.

Trace an auth refresh before changing it

For an intermittent sign-out bug, save a sequence diagram that follows one request:

1. the desktop client sends an API request with an expired access token;
2. the API returns the authentication failure;
3. the client asks the refresh coordinator for a new token;
4. concurrent requests wait on the same refresh rather than starting their own;
5. a successful refresh retries the original request;
6. an invalid refresh token clears the session and returns the user to sign-in.

Add the failure branch where the computer wakes with several queued requests. That branch is often the part prose hides: whether all requests retry, whether one refresh result is shared, and where stale work is cancelled.

Now the records have separate jobs. The sequence diagram makes the handoffs and ordering visible. Source search finds the implementation. The code graph shows callers and blast radius. A decision explains why concurrent refreshes are coalesced. A runbook covers what to inspect when production sign-outs rise.

Before using the diagram as a change plan, compare it with the indexed source. If the code sends one request directly around the coordinator, show that exception or fix it; do not make the diagram look cleaner than the system.

Finding and sharing diagrams

Ask for diagrams by system, project area, or shape:

show the sequence diagrams for ingestion

Diagrams respect the same personal, workspace, and project access boundaries as the rest of ContextStream. A shared workspace can expose a team view of its diagrams; a personal record stays personal. To give someone outside that boundary the diagram together with the decisions and code around it, include it in a capsule.

Diagrams, documents, and code health

These answer different questions:

• A diagram is the model someone deliberately saved.
• A document explains a system, procedure, proposal, or outcome in prose.
• Code health derives current relationships from indexed source and the code graph.

An architecture diagram can become stale even when the graph is current. Before using a diagram for a risky change, compare it with the indexed code and update it if the two disagree.

If it doesn't work

The diagram is too crowded. Split one system map into a high-level flow and smaller diagrams for the important paths.

The wrong shape was used. Ask for a replacement by purpose: “turn this flowchart into a sequence diagram so the service handoffs are clear.”

It no longer matches the code. Treat the indexed source as current evidence, then update or supersede the saved diagram.

Someone else cannot see it. Check whether it is personal, which workspace and project it belongs to, and whether the viewer has access.

Next

• Documents and runbooks
• Code health and dependencies
• Sharing context with a link