Repository Structure

Contains only files/folders that need to be in the root directory or that don’t make sense elsewhere. We should relocate anything that reasonably can be relocated to avoid bloat.

Any code that should be exposed for consumers of tilegroxy as detailed in the extensibility documentation.

Any deletion/rename/signature changes to code in this folder constitutes a breaking change. As such we should keep the code in this folder to the minimum necessary to be able to have a reasonable custom deployment of tilegroxy. Utility code should generally be left out of here.

This means pkg holds only what an extension needs to write its own entities:

Anything that constructs, wraps, or runs entities belongs in internal, even when an entity implementation needs it. When a Deps struct has to expose something from internal, expose it through a small interface declared in pkg rather than the concrete type.

The majority of code/business logic for tilegroxy should live in here. Code in here can’t be directly called by extensions of tilegroxy so it’s generally safe to modify without constituting a breaking change.

Contains a Helm chart for installing tilegroxy on kubernetes

Code specific for defining the CLI interface of tilegroxy go in here. We should try to keep these files minimal with just the necessary cobra scaffolding, the core logic should be placed in the internal packages with the cmd code being essentially just a CLI wrapper.

cmd.Execute and cmd.ExecuteArgs are the entry points for anyone building their own executable with tilegroxy as a library, so they are part of the public API alongside pkg.

Documentation lives here structured in Antora modules split into three separate sources: operation manual (user docs), development manual (these docs), and decisions (ADR record). The UI itself is built from a separate repository, see Documentation.

Contains dedicated files that provide examples of how tilegroxy can be used.

Contains end-to-end tests that run the compiled binary as a child process. Nothing in here is imported by the rest of the application, it exists solely to exercise the built artifact.

Contains the source data for images used elsewhere in the application or documentation. For example this might be a graphviz definition that is then turned into a PNG for the docs or a GIMP project file for our built-in images.

Contains Github Actions CI/CD workflows