Why is the .upsun.app.yaml file separate from the .upsun folder?

The files in .upsun control the environment at a cluster level. They define what services should be in the cluster.

The .upsun.app.yaml file defines the behavior of one single application container, with your custom code.

You can have multiple applications in the same project, with their own code, but having multiple directories each with their own .upsun.app.yaml file.

Any directory that contains a .upsun.app.yaml file becomes an application container, configured by that file. If there’s only one application then the degenerate case is to just make that the repository root, which is fine. To have multiple application containers, you would do something like:

/
  .upsun/
    routes.yaml
    services.yaml
  app1/
      .platform.app.yaml
  app2/
      .platform.app.yaml

And then app and app2 would become entirely separate application containers with the code in those respective directories.