[DRAFT] Musings on AC architecture and its evolution

[chuckadams]

Work In Progress. GH doesn't have a concept of a draft discussion or issue, so you're getting the raw feed as I save it and switch my attention to other distractions

Given that the count of current regular contributors to AC numbers three people, I may be shouting into the wind with this or any other discussion topic, but I really do want to invite comments from anyone with any interest: I'd like to look at the bigger picture of AC's architecture, where it's doing well, and where it could be improved. I have no shortage of opinions which I'm happy to share, and hope others will do the same.

TL;DR Bullet Points

The Good

• 👍 Postgres
• 👍 Immutable data
• 👍 Monolithic codebase
• 👍 Use of strongly-typed DTOs for requests/responses

The Bad

• 👎 Not keeping historical revisions of immutable data (see Keep historical Plugins/Themes/Packages #392)
• 👎 Using Eloquent models as actual domain objects
• 👎 Lack of any domain separation (but I don't want full-blown DDD either!)

The Ugly

• Eloquent in general.
• Other Laravel magic (facades mostly, we avoid most other magic)
• required base class for DTOs (currently beacon-hq/bag)

Overview

AC is currently designed as a fairly run-of-the-mill monolith application based on Laravel, using a single Postgres database and Redis for cache and queuing (which currently isn't even being used), and a single web listener with a bit of routing for admin endpoints and the bare stub of web UI that does exist (which is basically out-of-the-box Jetstream via Inertia+Vue). I find this design to be more than adequate, but what we do within the expansive borders of the monolith could use some stronger definition, so I'll throw out a few different areas as headers to spark more discussions

Data Model

AC being created to serve the legacy read-only wp.org api API, our data model reflects that: our central models are Plugins, Themes, and Packages, where Plugins and Themes are the base source of truth, and most Packages tend to be backed by a Plugin or Theme (free-floating packages can exist, but there's currently no API for discovering them -- you have to know its DID or it effectively doesn't exist for you). Also floating around are supplementary data like Tags (completely separate ones for plugins, themes and packages) and Authors. Nothing surprising here.

The AC data model stresses immutability: models are created and never subsequently altered, only replaced entirely by a new instance with a new ID (currently a uuid7). We're not currently keeping historical revisions, so the overall picture of the AC database is one of mutable state rather than an append-only log, but we're looking at fixing that in #392.

However, the data model is currently based on using Laravel Eloquent's Model objects as domain objects. While we do have a well-developed DTO layer (more comments on that later) for responses and some request objects, we do not transform Models themselves to DTOs except at the time of constructing responses, and in the meantime they carry along all the baggage of Eloquent with them. Just dumping an Eloquent model without calling ->toArray() on it first results in unreadable vomit.

🌶️ Thoughts on Domain-Driven Design

I like the overall idea of DDD, but I'm not joining the cult, largely to avoid being steered into designs and implementations that seem more driven by goofy and vague terminology than actual applicability to the problem at hand. No one seems to nail down what makes an architecture "hexagonal", other than throwing out "ports" and "adaptors" without any solid meaning attached to those terms either. Any implementation I see look like an overengineered mess of OO abstractions without any thinking as to the typed functional abstractions beneath. Shades of "enterprise" architectures from JavaEE. What even is an "aggregate root" when data is only ever replaced and not updated? And if there's one piece of jargon I never ever want to see become ubiquitous, it's "ubiquitous language".

That said, a modular design coupled by reusable abstractions is a fine goal. I disbelieve that an app can be neatly divided into Domains that break down neatly over every use case, but some areas are definitely more isolated than others, and the hierarchical organization of our code that namespaces and the filesystem forces on us should reflect that reality. I just don't want the Procrustean solution that forces everything into hierarchy that only satisfies a notion of "clean" that has to immediately be dirtied up when it touches the real world.

Possible "micro"-services [need feedback]

Given that our active developer team can be counted on one hand, the monolith is working out fine for organizing the codebase. But we should consider whether we want to deploy AC in separate instances with different "facets", such as a fully separated download service, or a FAIR-only config separate from the legacy API. This could complicate routing for sure, but also allow for better privilege separation in the deployments.