chore: Create ARCHITECTURE.md

[PoignardAzur]

This helps people get a better sense of the project structure faster than by browsing all the code and documentation.

[blinding-pixels]

The section describing the accesskit crate is the strongest part of this document. It's clear, well organised, and the Node and ActionRequest examples in particular make the abstract concepts land. Those examples are exactly the kind of thing the rest of the doc could use more of

That said, a few structural things would help navigation:
One — The Data schema section describes the schema conceptually but never links to where it's defined — which is common/src/lib.rs. Add that link. The concept and its source are in separate sections that never reference each other.

The document could greatly benefit from inline-linked file sources.

Two — "Data schema" and "accessibility tree" are used loosely. From my understanding after digging into the code, the schema is the type definitions in common/src/lib.rs while the tree is the runtime structure you construct using those types. A newcomer can't tell if they're the same thing or different, or where the schema lives. Clarifying that distinction and stating plainly that the schema is defined in lib.rs would remove real confusion.

This is also present in the File structure section about Platforms and the later section called Platforms as its own heading. The platform section under the file structure refers to this crate having the backend but then later in its own section calls them adapters. These two sections could benefit from a merging and naming unification.

Three — Reading Structure — There are two main things that cause confusion with the reading order: the jumping between individual sections and the file structure section, and the use of crates and folders interchangeably. This could be remediated by replacing the file structure section with an index and unifying the content in the file structure section with its corresponding longer explanation later in the doc.

Four — The adapter section could have a list of the platforms that are currently supported. This would be a nice to have thing more than a necessity.

Confusion Remediation Suggestions —

I could not infer from the architecture doc alone what the files within the crates were responsible for and where to get started. Two concrete things that would make this easier in my opinion are:

One — An example of a data schema. This could either be a file in the repo or added at the bottom as an appendix to show a new user what the project means by defining a data schema with the given types. This along with restructuring the document could compound well.

Two — A file map at the bottom arranged by the headings given in this document would be really helpful either as a separate file or as an appendix at the bottom.

Hope this helps.

[PoignardAzur]

Thanks for the review!

One — The Data schema section describes the schema conceptually but never links to where it's defined — which is common/src/lib.rs. Add that link. The concept and its source are in separate sections that never reference each other.

I don't quite agree with your framing, but on reflection, I agree this section is unclear. It's copy-pasted almost verbatim from the README, but the README description isn't ideal either.

I don't think the solution is "link to this specific file/item" so much as "rewrite this section to make the dataflow clearer". I'd be inclined to leave it as a TODO for now, because I'd want to rewrite the README first.

The platform section under the file structure refers to this crate having the backend but then later in its own section calls them adapters. These two sections could benefit from a merging and naming unification.

I think I should just remove the word "backend", it's not used anywhere else in the documentation, "adapters" is the idiomatic term.

Three — Reading Structure — There are two main things that cause confusion with the reading order: the jumping between individual sections and the file structure section,

I'm not sure what you're referring to by "jumping around"; the two big sections are "File structure" and "accesstkit crate", which both have relevant subsections.

and the use of crates and folders interchangeably.

I disagree that this happens. There are three instances of the word "folder", each is a variant of "the x folder holds the y crate".

(We might remove some of them after we rename some folders.)

One — An example of a data schema. This could either be a file in the repo or added at the bottom as an appendix to show a new user what the project means by defining a data schema with the given types.

I think we might add this to the README down the line.

Four — The adapter section could have a list of the platforms that are currently supported. This would be a nice to have thing more than a necessity.

Two — A file map at the bottom arranged by the headings given in this document would be really helpful either as a separate file or as an appendix at the bottom.

In my opinion, you shouldn't add this level of detail to an ARCHITECTURE.md file.

ARCHITECTURE.md lists stable information, like the names of the most important types. Newcomers can find these types by symbol search, by grepping, or through docs.rs.

It's not meant to be exhaustive, especially since most users will only care about the accesskit crate. I could add a mention that most of the code is in lib.rs, though.

[PoignardAzur]

@DataTriny The CI is flaking. This is because the CI script uses the latest Rust version instead of a fixed one, and we just had a Rust release.

[blinding-pixels]

I'm not sure what you're referring to by "jumping around"; the two big sections are "File structure" and "accesstkit crate", which both have relevant subsections.

.

Noted on the file map. And on re-reading, I agree my crates/folders and 'jumping around' point wasn't clearly articulated. In an attempt to be more specific:

In the File structure list, the folders appear as common → platforms → consumer. But the detailed subsections right after cover them in the reverse-ish order (consumer, then platforms). That order flip is what threw me a little as a reader. Very minor and a matter of taste, though.
other thing, which might be the bigger source of it: common/ is in the File structure list, but unlike consumer and platforms it doesn't get a subsection there — its detail lives in the separate ## accesskit crate section later. So two of the three listed folders are explained inline and the main one is explained elsewhere. Again, minor , just naming what as a new comer made me flip between the doc and the code base to confirm things.

[PoignardAzur]

In the File structure list, the folders appear as common → platforms → consumer. But the detailed subsections right after cover them in the reverse-ish order (consumer, then platforms).

Oh, yeah, I see your point. Yeah, I could order this better.

[DataTriny]

@PoignardAzur Most of the CI jobs use our MSRV, I just like to have clippy run on the latest stable so contributors don't have to deal with warnings on their development environment. Warnings have been addressed in #744, you just haven't rebased ontop of latest main I think. CI doesn't matter for this specific PR though.