In Stage 2, my goal is to come up with a UI that showcases the theory from Stage 1. A base version of the idea would be essentially the Github UI except every file and folder now contains information about its dependencies, dependents and a description:

An app is shown simply on the screen

Clicking on it reveals the files and folders it contains

A single click on a folder reveals a description for the folder, its dependencies and dependents. Here its revealed that the purpose of the image folder is just to store images used in the README.

Double clicking on a folder takes me inside. Here you can see by the breadcrumb on the top left that I've gone inside "PokeDex".

Finally, clicking on a file actually takes you inside the file, except that the dependencies, dependents and description are still visible.

This idea very directly applies the theory from Stage 1, and it has a few benefits. It's not that different from the Github UI, making it intuitive to use for people who are already familiar. It's also not requiring a new format for how open source projects are uploaded and used; the dependencies and dependents can be inferred by the system rather than the uploader needing to type them in manually. The descriptions will need to be user input, but it's a small ask and could also be generated by including READMEs inside sub folders.

The problems with this approach is that I think it approaches the problem tangentially. It shows the explicit dependencies of a file but it doesn't explain the nature of that relationship. Of course, code the way developers write it will never explain the reason for a dependency (comments help but there's no standard format or even expectation to provide them) so if we want to envision a more revolutionary experience, we can't use the usual format of a code repository.

There was something else I realized as I built this: typically a very large codebase will have many layers of "containers". Something like vapor is an organization containing 61 repositories, the main of which is vapor/vapor. The repo contains many layers of folders and files. Each file itself can also be thought of as a "container" containing classes or functions. Even a class in a sense is just a container for its functions and properties. The idea of a "container" seems to persist all across a codebase. And that's natural obviously. If all the code in a codebase was just laid out in one giant file, it would be impossible to understand. Splitting our code across modules gives us less things to reason about at any given time.

I tried to come up with a different approach based on splitting the folders into their purpose rather than just their name.

Here, opening the app reveals "containers" organized by their description and purpose rather than a name. The design is actually to encourage pseudo-code like structures.