Flow charts explained: symbols, types, and examples

People draw flow charts to show a start, a few steps, a decision, and a stop, so a reader can tell a question from an action. The symbols are old, the judgment is the part people skip, and the judgment is what keeps a chart from becoming a pile of boxes.

I keep them in git as Mermaid because the argument is usually "which way does no go," and that argument belongs on a line I can diff. This page is about the symbols and that judgment. The flowchart syntax page owns the token table. The tutorial for creating a flowchart in Mermaid owns the step-by-step build. If you came here for a keyword reference, use those. If you came here to decide what the chart is allowed to say, stay.

A flow chart is a bad picture of a database, a bad picture of a call stack, and a decent picture of a policy. I'll show four uses people mix up: a process, a decision, a swimlane, and a system flow. Then I'll build one. I won't pretend the build is the hard part. Stopping is the hard part.

The symbols, and the one job each is allowed

There are more stencil shapes than a software team will ever use honestly. I use five, and I get suspicious when a chart needs a sixth.

The terminator is the start or the stop. In classrooms it's a rounded pill. In Mermaid I write it as a stadium, start([Start]) and stop([Stop]). It is not a step. If you only have one, you forgot the other, or this picture is a fragment of a larger process and you should say so in the sentence above it.

The process is a rectangle. lookup[Look up the account] is work someone or something does. It should be a verb phrase. "Account" is a noun, and a rectangle labeled with a noun is a hint that you wanted a data store or a system box, not a step.

The decision is a diamond. One question, two or more labeled exits. gate{Still active?} is a decision. "Handle the account" is not a decision, even if you put it in a diamond to make the chart look serious. I label the exits |Yes| and |No|, or with the actual words the product uses. An unlabeled diamond is a fork. Readers will guess, and they will guess differently.

The data symbol is a parallelogram in the old stencil. It means input or output, a record moving, not the work done to it. Mermaid writes that as id[/Account id/]. I use it when the thing on the line is data the next step consumes. I don't use it for every variable, or the chart becomes a type signature.

The document is the wavy rectangle, the piece of paper the process produces. Mermaid can draw that with a document shape. I use it for a letter, a receipt, a report, something a human could hold or file. I don't use it for a JSON response. That's data, or it's a process step called "Write the response."

Here's those five in one small closure flow, so the shapes are doing jobs and not sitting in a legend.

flowchart TD
    start([Start]) --> id[/Account id/]
    id --> lookup[Look up the account]
    lookup --> gate{Still active?}
    gate -->|Yes| letter@{ shape: doc, label: "Closure letter" }
    gate -->|No| stop([Stop])
    letter --> stop

start and stop are terminators. The parallelogram is the id we were handed. The rectangle is the lookup. The diamond is the only question. The document is the letter, and only the yes path produces one. The no path stops without a letter, which is the policy, not a missing box.

If shape: doc fails in an older renderer, change that line to letter[Closure letter] and keep going. Check the version if the wavy edge matters to you. The policy is the diamond, not the edge style. I also didn't name a node end. stop is the id. end is reserved for closing a subgraph, and it will eat the rest of the file.

A symbol you add for decoration will get read as a claim. A cylinder that means "database" in your head means "database" to the next reader, even if you only wanted a prettier rectangle. If I can't say the claim in one sentence, I don't change the shape.

Direction is a reading order

TD means top to bottom. LR means left to right. That's the whole feature, and people treat it as a theme.

I use top to bottom for a decision, because the question should sit above the answers and the eye should fall through yes and no. I use left to right for a pipeline, where each stage hands work to the next and a diamond would be a surprise. I pick one before the chart has ten nodes. Flipping direction later is legal, and the diff looks like I redesigned the policy. I didn't. I rotated the page, and every reviewer has to re-learn the picture.

Don't mix directions inside one chart to "save space." A subgraph can point a different way. It can also make a small process look like a maze. If the chart doesn't fit, you have two charts, or you have steps that should have been a sentence.

Labels on arrows are part of the reading order. The eye hits the diamond, then the word on the line, then the next box. If the word is missing, the eye invents one. I have watched two reviewers approve a chart and then argue in the ticket about which branch refunded the customer. The chart had the boxes. It didn't have |Refund| and |Refuse|. The boxes were never the policy.

What a flow chart is bad at

It is bad at conversations. "The app calls the bank, the bank says no, the app tells the user" is a sequence. Drawn as boxes, the callers disappear and the order becomes a suggestion. If you find yourself labeling rectangles with service names and arrows with HTTP verbs, stop and ask whether the readers need the call order. If they do, this is the wrong picture.

It is bad at lifecycles. Draft, review, live, and back to draft is a state machine. A flow chart can fake it until the same state is entered from two places, and then you copy the box so the layout stays a tree. The copied box is a lie. There is one Draft. A state diagram has one Draft. Use that when the noun sits in conditions and the arrows are events.

It is bad at data. Keys, cardinality, and "an order has many items" are not a path. People still draw a rectangle per table and arrows that mean foreign keys. The arrows also look like control flow. Six months later someone reads "then we go to the payments table," which is not what you drew, and is also not crazy given the picture. Put the schema in an ER diagram.

It is bad at schedules and bad at ownership charts. A date range is not a step. A reporting line is not a step. I've seen an org chart built out of flow arrows, and every new hire read it as the way work moves. It wasn't. It was who reports to whom, drawn with the wrong symbol.

It is bad at posters. You will not get the box to sit in the corner because the layout is a graph layout. Nudge it and the next node will undo the nudge. If the layout is the content, use a drawing tool and admit the file is a picture. Check that tool's version for how it wants to be edited. I'm not going to invent its feature list.

The test I use: can I read the chart out loud as "do this, and if that, do that"? If the sentence wants "who calls whom," or "which rows exist," or "which state is this in," I picked the wrong shape. What a flowchart is used for pushes on that question from the usage side. The meaning of the word flowchart is the definitional neighbor. This page assumes you already have a process in mind and you're about to draw it wrong in a specific way.

A process chart, almost a list

A process chart is the kind with few questions. Publish the notes. Run the checks. Tag the release. Tell the channel. It's a list that earned arrows because the order matters and one step really does depend on the previous one.

I still see people force a diamond into the middle so it "looks like a flow chart." Don't. A list with one honest gate is a process. A diamond that always goes yes is a rectangle you were afraid to commit to. If the gate is real only on Fridays, say that in the label. gate{Is this a production tag?} is a decision. gate{Continue?} is a shrug.

The failure mode is granularity. "Ship the release" as one box is honest if the chart's reader doesn't do the shipping. Split into "run the checks" and "tag" and "deploy" when those are different owners or different failure modes. Don't split "tag" into "open the terminal" and "type the command." That's a script, and it belongs in the script.

I write process charts left to right when they're pipelines, and I stop at about seven boxes. Past that, the reader is scrolling and the order is the only information, which a numbered list would have given them with less ceremony. A flow chart earns its keep when at least one arrow is not "the next step," or when the same step is reached two ways. If every arrow is the next step, you wrote an outline.

A decision chart, which is the usual reason

Most of the flow charts I actually maintain are decision charts. The rectangles are there so the diamond has somewhere to land. An expense policy is the classic. Under a limit, pay it. Over the limit, a manager reviews. Rejection goes back to the employee. Approval joins the payment path.

flowchart TD
    filed([Expense filed]) --> amount[Read the amount]
    amount --> gate{Over the manager limit?}
    gate -->|No| pay[Schedule payment]
    gate -->|Yes| mgr[Manager review]
    mgr -->|Approved| pay
    mgr -->|Rejected| back[Return it to the employee]

Read the joins before you admire the shapes. pay has two parents. That's the point of the chart. Under the limit and approved-by-manager are different histories and the same next action. If those histories need different payment paths, they must not join. A join is a claim that the downstream step cannot tell the paths apart, or doesn't care.

back doesn't join. The employee has the expense again. I didn't draw a loop into filed, because filing again is a new pass and this chart is one pass. If you need the loop, draw it, and accept that the picture is now a lifecycle wearing flowchart clothes. That can be fine for a single review cycle. It gets clumsy when there are three states and two ways back.

The limit is not in the diamond. "Over the manager limit?" stays readable if finance changes the number from fifty to eighty. Put the number in the paragraph under the figure, or in the config the code reads. I've hardcoded a dollar amount in a diamond and then the chart was wrong for a quarter after the policy change, because nobody updates pictures when they update constants. Say the rule. Cite the constant beside it.

Both exits of mgr are labeled. I don't rely on the layout's left and right to mean yes and no. Layout moves. Labels stay. If a third exit appears, "needs a receipt," it gets its own label and its own box. Don't overload |No| to mean three different nos.

Swimlanes, drawn as subgraphs

A swimlane says who does the step. The classic drawing is horizontal bands. Mermaid doesn't have a lane primitive. A subgraph is the honest substitute. The band is a box around one actor's steps. The arrows that cross the box are handoffs.

This is an access request. The employee asks and then waits. The manager decides. IT grants or records the denial. I don't pretend the subgraphs are UML partitions. They're groups with titles, which is what a lane was for.

flowchart TB
    subgraph Employee
        ask[Request access]
        wait[Wait for the decision]
    end
    subgraph Manager
        need{Is the access required?}
        approve[Approve the role]
    end
    subgraph IT
        grant[Grant the role]
        deny[Record the denial]
    end
    ask --> need
    need -->|Yes| approve
    need -->|No| deny
    approve --> grant
    grant --> wait
    deny --> wait

The lanes are the point, so the titles have to be actors, not themes. "Employee," "Manager," and "IT" tell you who moves. A subgraph called "Phase 1" tells you nothing the step labels didn't already tell you. If I can't name the lane as a person or a team, I don't want lanes. I want a normal flowchart.

Crossing arrows are handoffs. ask --> need leaves the employee and enters the manager. That's the email, the ticket, the tap on the shoulder. If a step in the employee lane calls a step in the employee lane through the IT lane for no reason, the lanes are decoration and the path is a mess. Redraw the path, then see if the lanes still match the owners.

wait is a real step. People delete the wait because it isn't work. It's the state the employee is in, and deleting it makes the chart look like the employee grants their own access. I have seen that reading in a review. The author said "obviously IT does it." The picture said the arrows ended in the employee band. Trust the picture, then fix the picture.

Don't nest lanes three deep. A subgraph inside a subgraph is legal and usually a sign you wanted a second diagram, one per team. The login flowchart template is a single-actor cousin of this, useful when you don't have handoffs yet and you're about to invent a lane called "System" for every rectangle.

A system chart is still a flow

People say "system flowchart" and mean a map of services. Sometimes they mean the path of one request through those services. Those are different drawings. I only call it a flow chart when there's a path: the request hits the edge, the edge refuses bad input, the API writes, the worker sends mail. Decisions and order. If there is no decision and no order, you wanted boxes in a grid, a block diagram, and a flowchart will move those boxes the next time you add an arrow.

A system flow goes wrong by naming boxes after repos and arrows after "uses." Everything uses everything, and the chart becomes a hairball that proves the company has microservices. Nobody can read a policy out of it. I keep a system flow only for one request I can narrate. "A bad token stops at the edge. A good token becomes a row. The worker reads the row." Three sentences. If I need a fourth service in the picture, it has to appear in the narration, or it's a logo.

Direction for that kind of chart is usually left to right, because people expect a request to travel across the page. Top to bottom also works, and it matches the decision charts on either side of it in a design doc. I pick the one the surrounding figures use, so the reader doesn't rotate their head at every heading.

I don't color services by team in the same chart where color means yes and no. One meaning per color, and only after the path is right. A rainbow of team colors is an org chart again. We already talked about that failure.

Build one, then stop adding boxes

I'll build the expense chart the way I actually build it, not as a syntax tour.

Write the question first. "Over the manager limit?" That becomes gate. If I don't have a question, I don't open a flowchart yet. I might have a list.

Write the terminators. Filed, and the two outcomes that leave this policy: payment scheduled, or returned to the employee. I used filed as a stadium and left pay and back as rectangles because they're work, not the end of the world. You can stadium the outcomes too. I don't stadium every box. The pill means "this picture starts or stops."

Add the one process that makes the question possible. Read the amount. Without it, the diamond is magic. Don't add "open the form" and "click submit." The chart starts when the expense is filed.

Connect gate with labeled arrows before you add the manager. The no path can point at pay immediately. Then add mgr on the yes path, with approved and rejected. Join approved to pay only if you mean the join.

Stop. Look at the preview in the editor. Read it out loud. If you hear a step you didn't mean, it's in the picture. If you hear yourself explaining a step that isn't in the picture, either add it or admit the prose is the spec and the chart is a summary. Say which one in the pull request so the next editor doesn't "complete" a summary into a second spec.

The blank-page version of this is the AI flowchart generator. Ask for the nodes you already named, the question, and the join. Then delete anything you didn't name. Five free AI uses is a lifetime total, so don't spend one on "make a professional expense flow" and then fight the extra boxes. Making a flow chart is the build from the other direction, from an empty file. An online flowchart tool is the "I don't want to install a drawing program" path. Use them if you're stuck on the mechanics. The symbols above are still the review.

Calls the syntax will not make for you

A legal chart can still be a bad chart. These are the calls I make, and the parser will not back me up.

I refuse a diamond with a paragraph inside it. The question gets shorter, or the chart gets split. A diamond that needs a legend is two decisions.

I refuse a node id of end, graph, or subgraph. Those words already work for the language. stop and done are free, and they don't close a block by accident.

I put the unhappy path on the page. A chart of only the happy path is a brochure. back[Return it to the employee] is the box managers actually ask about. If the unhappy path is "to be designed," say that in prose and leave the arrow off. A fake box labeled "handle errors" is worse than a gap, because the fake box looks like a design.

An org chart is not one of these. Reporting lines want an org chart in Mermaid, which is a tree of people, not a decision. I don't add a symbol the team hasn't agreed on. If document, data, and process are all rectangles, the chart is still readable, and it's more readable than a chart where one author used a parallelogram for fun. Consistency beats stencil purity. I'll take a boring rectangle over a shape nobody can name in review.

I update the chart in the same pull request as the policy. A flow chart that lands a week later is a souvenir. Reviewers can tell. They stop reading it, and then you have text in the repo that contradicts the code with confidence.

Open the editor and type the question before you type the decorations. If you can't label both exits of the diamond, you don't have a flow chart yet. You have a topic. Write the topic as a sentence until the exits are real.