Seeking feedback: Guidelines for new edx-platform applications

The architecture squad at edX is seeking feedback for an upcoming ADR (architectural design record) meant to codify where to add new applications to the platform, with respect to edX’s long-standing goal of transforming the monolith into a more extensible core model.

In the current formulation of the ADR, any new app that is added directly into the edx-platform repository must have an accompanying ADR explaining why it cannot be created as a separate plugin or library.

Outside plugins or libraries should not import from within edx-platform, so that would count as sufficient reason to add a new application within the edx-platform repository if the dependency itself cannot be easily extracted into its own plugin or library.

If a new application is added to the edx-platform repository explicitly to avoid having to import from edx-platform, both the new application and its dependency should be added to a central list, probably stored as a sub-document of the ADR. This will assist the Open edX maintainers in prioritizing applications to be broken out of the edx-platform repository.

Please let us know your thoughts, especially with respect to more specific guidelines about when to add to edx-platform vs when to create a new repository.

3 Likes

Hi there @Rebecca_S_Graber :wave:t3:

Outside plugins or libraries should not import from within edx-platform, so that would count as sufficient reason to add a new application within the edx-platform repository if the dependency itself cannot be easily extracted into its own plugin or library.

What if we want to create a report-plugin, that generates reports for users, enrollments, and certificates (i.e needs to import code from the platform). Should we create a new application for it within the platform? Even though is as simple as returning objects formatted? Isn’t this damaging for breaking the core?

Hm that is a very good point. Maybe we need to make a distinction between apps that rely on core models vs those that only rely on things that are in other apps.

To further clarify, I think the issue here is what to do with applications in general that are not themselves part of the core functionality but rely on core models.

@mgmdi one way that I could imagine solving that problem here would be to have those apps in the edx-platform expose any data you need via api.py and then the new reporting plugin could rely on those without being in the platform. I believe our current thought on returning querysets from api.py is that it’s acceptable.

In general, I’m super excited about this new guideline.

I agree with the overall idea that new apps in edx-platform should explain why they have to be there. I also agree that needing to import from edx-platform is a valid reason to keep things in edx-platform.

My understanding is that the main tension we’re trying to navigate is between having too much complexity in edx-platform vs. detecting regressions when we break compatibility (i.e. improving maintainability of these add-ons). Using formally defined api.py files helps with this issue, mostly because we’re making a promise to keep that portion of the code more stable. Similarly, we can get away with doing direct model imports sometimes because we’re importing things that are unlikely to drastically change, like CourseOverviews. So I agree there’s a fuzzy line here, and it’s probably best to keep from having fast and hard rules and allow folks to make individual tradeoffs based on their situation.

That being said, I think the long term solution involves self-contained repos that edx-platform uses, but that are separately importable and usable by extensions, like openedx-events. I think one of the most fundamental issues we’ve been bashing our heads against for years is that edx-platform is built to be a site and was modified to have things plug into it, rather than being a set of apps that people could build on top of.

Making apps that fit into that kind of world requires having largely self-contained data models, and making the dependency on edx-platform thin and explicit. For instance, by pushing data into the app on publish, rather than having the app know how to query for the data it needs. You’re left with a few places in edx-platform that have to know about the app specifically (unless there’s some separate plugin mechanism), but it gives that app much more flexibility to be developed externally and linked to integrations externally. Again, with openedx-events as an example of this pattern.

2 Likes

The ADR is up for review here docs: ADR with guidance for new applications by rgraber · Pull Request #30053 · openedx/edx-platform · GitHub