Topcoder platform helper app

Ghostar

I'm sketching out some details below as I think through how I'd like our dev environment detailed and a potential idea for an internal app that we could use to consolidate a bunch of this stuff, and provide guidance as we move to the micro front ends architecture.

You can see the current MarvelApp we've created here:
https://marvelapp.com/prototype/15di52b9/screens

Problem

Currently, we have a problem on the platform in that there's a huge learning curve to the platform in general, and it's really, really difficult to get up to speed with the different API versions (v3,4,5), the different web apps, and how the user moves through the various apps on the site. That's not even accounting for how the different apps use the various APIs, and how each of the various apps are deployed, where they sit in Git, etc...

Potential

I see some potential here for a web app being built through the community that could really help with this.

I'm thinking a visual web app with some key features would be really useful for onboarding new folks into development, ensuring we can cycle new members in quickly and get them up to speed.

What I'd like to see is a graphical overview of the site. This would start at the UI level, where we see the various MFE / UI apps. Clicking on a UI app would then take us to a details level where we could see:

• Copilots / activity for the app
• The Github link to the code for that app
• The MarvelApp link for the design for that app (optional)
• Any wireframe or additional information (optional)
• How that app is deployed, including the link to CircleCI to monitor the deployment status. I think this can just be a textual description of the deploy, like “CircleCI” or “Github Actions” and then a link. Here’s an example CircleCI link: https://app.circleci.com/pipelines/github/topcoder-platform/forums

• Instructions on how to run the app locally, including fully standing it up and testing it, from essentially nothing to being able to run the app locally. This will likely just be a link to a markdown file in Github. I would expect this to just be a simple link called “Deployment instructions” that then opens up the linked file.

  • Example: https://github.com/topcoder-platform/topcoder-x-ui/blob/develop/TopcoderXDeploy.md

• Links to each environment where the app is deployed - dev, staging, prod, testing, qa, etc… These would be links to various Topcoder URLs. For instance, prod is “topcoder.com”, but dev is “topcoder-dev.com”. We also have various QA environments and “platform.topcoder.com”. For some other apps, like Work Manager, they are sub domains, like “challenges.topcoder.com” for prod and “challenges.topcoder-dev.com” for dev

• Instructions on how to test the various pieces of the app Again, I think this would be a link out to a markdown file in Github, maybe something like this: https://github.com/topcoder-platform/topcoder-x-ui/blob/develop/docs/RenewGitToken.md
• And, most importantly, we would have sub-links from the UI project to the various APIs consumed, including the individual endpoints and potential test data. I would expect there to be a list of sub-projects or related projects to the project being viewed. Clicking on one would link to the same information above, but for the linked project / sub-project instead. For instance, the community app uses the member API, which is a completely separate repository, codebase, etc…, but that will have the same information above for environment, deployment, instructions, etc… It’d be good to be able to drill down.

Search

It would be a great feature if the app was "smart" in that we could enter a URL from the site (prod, dev, etc...) and it would know what path / domain was in the URL and direct the user to the specific UI project that "hosts" that path. I know for myself, and for new devs, it can be really hard to figure out what pages / views are coming from which projects, and that will only increase in complexity as we transition to micro front ends.

I had that problem with the registration pages recently - I had to ask a lot of questions from Topcoder admins to figure out where things "lived" in Git and the site.

Take the challenge details page for example:
https://www.topcoder.com/challenges/461c6274-3abc-4e1a-bc5d-71a65fd324c6
It'd be great if I could just copy / paste that URL into the search bar and it would automatically show the details for the community app ( https://github.com/topcoder-platform/community-app)

Or, a WM link, like: https://challenges.topcoder.com/projects/28151/challenges
And it would bring up the details for the work manager UI
https://github.com/topcoder-platform/work-manager

Configuration / setup

This could all just be driven by JSON files in Github, making it easy to update as we go, and the copilot of each application would be responsible for keeping the JSON config file up to date. The app would just read in the JSON file from git every day and cache / update the record associated with the application.

Just some thoughts - I think a developer-focused tool like this could be really useful for everyone. A great way to consolidate a birds-eye view of our app.

maxceem

I really like the idea.

Some thoughts:

• I'm not sure if this is already an intention, though it would be great to store such a JSONs inside each repo and the Tool would only have the repo list and get details from each repo JSON file. This way such JSON could be included into requirements to be supported up to date, same like we do for README files. Otherwise there is a risk that we would forget to update these JSON files if we store all of them in some central repo. Also, it would be harder to update multiple repos than update only one.
• Another benefit of storing JSON files inside the repo, is that there could be some tool, which could render such files inside the repo for preview the info we provide there. For example, here we use GitHub pages to host Swagger file https://topcoder-platform.github.io/taas-apis/ and this is automatically updated if we change Swagger file inside the repo. So the same could be done with such JSON file, some page could be generated so copilots could preview the information which would be provided in the Tool.

Ghostar

Yeah, I absolutely intend to store these in the individual repos, not in a central location, for that very reason. It would be too hard to have one centralised location because no on would "own" those details very well and things would get stale. If a copilot / PM is responsible for the file, it's more likely it'll be kept up to date. The only configuration I really want to have for the main app is just a list of repos, and then it goes into each one and pulls out the JSON.