Reads a repository and reports what it actually says about itself.
No models. No network. No guessing.
Part of the Flui ecosystem.
Before anything can be deployed, someone has to answer a plain question: what is in this repository, and what does it need in order to run? Cartographer answers it by reading — the manifests, the container recipes, the composition files, the framework configuration — and reporting what it found, along with where it found it.
It is the first step of turning a repository into a running application on Flui, and it is deliberately the least clever one.
A deployment that fails is readable. You look at the logs, you fix the cause, you try again.
A tool that states something false is not. A health path that was invented rather than found fails every probe and rolls the deploy back with no obvious reason. A database inferred from a weak hint gets provisioned, billed, and wired to nothing. Both look like the tool worked.
So Cartographer is built around one rule: it would rather admit a gap than fill it. When a value cannot be found, it is reported as not found — never replaced with a plausible one.
For any repository it is pointed at:
- What the project is — language and framework, decided by weight of evidence rather than by the first file that matches. A build script in a PHP project does not make it a JavaScript one.
- What can be deployed — one application, or several. Monorepos hold both applications and libraries, and only some of them are meant to run.
- How it is built — which container recipe, and when several exist, that several exist. A repository with a development recipe and a release recipe is not ambiguous by accident, and picking one silently is how the wrong image reaches production.
- How it is reached — the port it listens on, the routes it serves, and which of those routes is a genuine health endpoint.
- What it depends on — the databases, caches, queues, search engines and object stores the project declares, mapped to the services Flui can provision.
- What it needs from you — the values no tool can derive: credentials, keys to third-party services, anything private.
- What stands in the way — hardware, privileges or services that cannot be satisfied, reported as an obstacle with its reason rather than discovered at deploy time.
Nothing is reported as a bare value. Each fact names the file and the line it came from, so it can be checked rather than believed — by a person reading a summary, or by a machine reopening the line.
Facts also carry how firmly they are held, and the difference is not cosmetic:
- Declared — the project states it outright, in a place meant to state it.
- Derived — it follows from something the project states, but the project never said it.
- Circumstantial — a hint worth surfacing and not worth acting on alone. A client library in a dependency list suggests a database; it does not establish one.
Corroboration does not promote a hint. Two weak signals remain weak.
Knowing that nothing was found is only useful alongside knowing that someone looked. Cartographer reports the extent of its own reading: which files it opened, what it searched them for, and what it did not search for at all.
This is what separates "this project needs no database" from "nobody checked" — two answers that look identical until one of them costs you a production incident.
Cartographer sits underneath the parts of Flui that need to understand a repository: reading a project before its first deploy, checking whether an existing manifest still matches the code it describes, and mapping declared dependencies onto the Flui catalog.
It knows nothing about clusters, credentials or deployment. It reads, and it reports. What to do with the answer is someone else's decision — which is why the same answer can be shown to a person for confirmation instead of acted on silently.
- cartographer (you are here) — deterministic repository reading
- flui-core — the Flui control plane: API and CLI
- flui-dashboard — the Flui dashboard
- flui-spec — open specification of the
flui.yamlmanifest format
More at github.com/flui-cloud.
Released under the Apache License 2.0.