flowchart-fun: the parser that defines the product is in another repository

The parser that defines the product is maintained elsewhere

The readme describes the application as a webapp for generating flowcharts from text, and then says what it is built with: React, and a graph library for rendering.

What it does not say in that sentence is where the text becomes a graph. That is answered later, in the contributing section, and the answer is a different repository. The underlying syntax parser is a separate project, and the invitation to contribute is aimed at that project rather than at this one.

So the distinctive part of this product, the mapping from indented English phrases to nodes and edges, is not in this repository. What is here is the interface around it: a React front end, a rendering layer, a serverless API, a shared package, and a package the readme calls formulaic that has to be built before anything runs.

That has two consequences worth stating plainly. For a user, the behaviour they care about can change without this repository changing, and the two are versioned independently. For a contributor, the most interesting work is pointed at elsewhere, which is why the contributing section spends its one substantive sentence on the other project rather than on this one.

It is not an abandonment. The parser is by the same organisation and is linked as a first-class part of the system. But it does mean that reading this repository tells you about the application and not about the language.

The one syntax example is shown without its result

Here is the entire syntax the readme teaches, and it is four lines:

Node A
  goes to: Node B
  and: Node C
    goes back to: (Node A)

Indentation does the structural work. Two spaces introduce a target, a further indent chains a sibling, and a parenthesised name on the way back creates the cycle back to the first node. There are three phrases in the whole vocabulary: go to, and, and goes back to.

That is the complete specification offered, which is either an admirably small design or an under-documented one depending on what you expected. Nothing states how a node name containing a colon is handled, what terminates a line, how a target that does not exist yet is treated, or how deep the nesting may go. Each of those is a question the parser answers somewhere, and the answers are not in this repository.

The example section then ends without showing anything. The sentence introducing it says the flowchart can be generated with a few clicks, and the next heading begins. So the reader is given input and never output.

That is an odd gap given the screenshots at the repository root, which are named for the application and for the example, and given that the hosted site exists to demonstrate exactly this. Those images exist; they are simply not placed in the section that needs them.

The login features exceed the free serverless function limit

There are two ways to run this locally, and they do not give you the same application.

One is the hosting provider's own local development command, and that path includes the login features. The other is a plain package-manager command that runs without them. The readme labels both explicitly, so the choice is not hidden.

The login path has prerequisites beyond the usual ones. You need an account with the hosting provider and its command-line tool installed, which is a heavier requirement than most local development setups and means your local environment is coupled to a hosted platform's emulator rather than to a standalone server.

The deployment constraint is stated more bluntly. To deploy the application you need a paid plan on that provider, because the app uses more serverless functions than the free tier allows. The readme gives the number it exceeds.

That single sentence is the most important line in the document for anyone considering running this themselves. The open-source repository is genuinely open, but the assembled application is not self-hostable on a free tier of the platform it was built for, and the reason is structural: there are more serverless endpoints than the free allowance permits.

So the realistic options are the paid plan, the hosted site, or running without the login features locally. What that removes is the scenario where an organisation runs its own instance on its own infrastructure, which for a diagram tool whose main asset is text input is arguably the least interesting thing to want anyway.

The development script alone will not produce a running app

Getting started is three steps: clone, copy the environment example to a real environment file, then install and run.

Then there is a note, and it is the step most likely to cost a newcomer an afternoon:

`pnpm -F shared build && pnpm -F formulaic build`

Two of the workspace packages must be built before the application will run at all, and the instruction to do so comes after the install step rather than as part of it.

The root build script already does this. It builds the formulaic package, then the shared package, then the app, in that order. So the manual command is a way of satisfying the same prerequisite that the root build would satisfy anyway, and someone who runs the root build never needs it.

The trap is the other root script. The development command is a filtered parallel run across every workspace package at once. That starts a watcher in each package rather than building them in dependency order, so it does not produce the artefacts the app needs to import. Running it after installing gives you a development environment that starts and then fails on a missing module.

The workspace has four packages: the app, the api, the shared one, and the formulaic one. The naming is not self-explanatory, since nothing in the readme says what formulaic is or why it is a separate package rather than part of shared. For someone deciding whether to depend on any of them, that is a gap the readme does not close.

Premium features need four vendor accounts and a pricing plan is committed

The prerequisites section says that developing the premium features requires accounts with four separate companies: the hosting platform, a database provider, a payment processor, and a transactional email provider.

Four accounts is the honest cost of a small team running a commercial product, and listing them is more useful than a vague reference to environment variables. What it also does is draw the shape of the business model: payments and email are the two that exist to sell something to users, and the database is where a login-enabled product keeps its state.

Two details make the commercial side concrete. The free plan of the hosting platform is insufficient for deployment, as the function count already showed, so the free tier does not cover running the product. And the repository root contains a file whose name is a plan for redesigning pricing.

A pricing plan committed at the root of a public repository is unusual in the other direction from most of what is here. Everything else in the tree is infrastructure: workflow configuration, ignore rules, a licence, an agent configuration file, a pull request template, two screenshots, a workspace manifest. A product strategy document sits among them, which tells you the repository is used as the working directory for the whole business rather than only for the code.

Environment values are not hand-written either. There is a root script whose job is to pull them from the hosting platform into the app's environment file, which means the local configuration is derived from a project hosted there rather than maintained in the repository.

Contributors are pointed at a dev branch while the default is main

The contributing section says to fork the dev branch and start developing and testing a feature there.

The default branch of this repository is main. So the instruction to work from dev names a branch that is not the one the repository is built from, and the readme gives no indication of what dev contains, whether it is long-lived, or how it merges back.

This is a small thing on its own, and the kind of instruction that ages quietly: a project that once developed on a dev branch and later switched its default to main will leave the sentence behind. The cost is a first-time contributor forking the wrong base and producing a diff against a branch whose contents they cannot see from the readme.

The same section links a discussion server and describes the community as welcoming contributions of any size, then points at the external parser project for anything about the syntax. That split is coherent with what the repository actually contains.

Translations are handled the same way, with a defined path rather than an open invitation: message files live in per-language directories inside the app, and adding strings is followed by a compile command scoped to the app package. So a translator edits a gettext catalogue and runs a build step, rather than editing a locale module directly.

The root test command runs the API check and the unit tests but not the browser tests

Testing is split across two frameworks. Unit tests use one runner, end-to-end tests use a browser automation tool, and each has its own scoped command inside the app package.

The root test command does not run both. It invokes a check in the api package and then the unit tests in the app package:

`pnpm -F api check && pnpm -F app test`

So a full test run at the repository root covers the server side and the unit layer, and the end-to-end suite is something you have to ask for by name. That is a reasonable default, since browser tests are slow, but it means the root command is not a complete verification of the repository and the distinction is easy to miss.

The root scripts are otherwise well organised for a workspace. The root build runs the three buildable packages in dependency order rather than in parallel, which is the correct contrast to the root development command discussed earlier. There is a root lint and format pair that delegates into the app package, and a pre-commit setup that runs the same lint and format pair on staged files in the app directory.

Three development dependencies sit at the root: the hook installer, the staged-file runner, and a browser process polyfill. That last one is the unusual entry in a repository whose application is browser code and whose tooling runs in Node. The engine field pins Node to a major version, and a separate file at the root pins it more precisely.

Editorial conclusion

Flowchart Fun suits someone who wants a diagram from a rough outline in under a minute and does not mind the syntax, and it suits a contributor who wants to work on graph layout rather than on the web application. It does not suit someone who needs self-hosted deployment on a free tier, since the login features exceed the serverless function limit of the free plan. Three things to check before committing. Whether the parser project is one you would also depend on, since that is where the behaviour you are buying actually lives. Whether the two local build steps are done, because the development script alone will not produce a running app. And whether your text is better served by a diagram tool with a visual editor, since this one has no canvas to click on.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tone-row/flowchart-fun on GitHub