Describe user group package hierarchy

[datasalaryman]

Motivation

I'm updating the CONTRIBUTING.md here - #1427 to give contributors a walkthrough of the various packages on this project. I've been looking at the package dependency trees and feel like the user and developer experience could be improved.

It seems like all the packages depend on each other whenever, and as needed. This creates confusion as to what packages are flexible building blocks vs. APIs for framework authors and end users (e.g. #1428).

Details

It could be clearer which packages should be dependencies for others by sorting them into user groups. I'm proposing the hierarchy described by the chart below.

Obviously, nothing here is final. Within this framework, packages need to be created, moved around, and rethought. Happy to discuss further.

┌──────────────────────────────────────────┐
│           @solana/kit                    │
│    What non-framework developers         │
│         install and use                  │
│  (Re-exports everything below)           │
└─────────────────┬────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────┐
│     Packages for Framework Authors       │
│  Examples:                               │
│  • @solana/codecs                        │
│  • @solana/addresses                     │
│  • @solana/accounts                      │
└─────────────────┬────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────┐
│   Building Blocks for Kit Contributors   │
│  Examples:                               │
│  • @solana/codecs-core                   │
│  • @solana/codecs-data-structures        │
│  • @solana/codecs-numbers                │
└──────────────────────────────────────────┘


┌──────────────────────────────────────────┐
│           **Helper Packages              │
│    (Used by all levels)                  │
│                                          │
│  Examples:                               │
│  • @solana/errors                        │
│  • @solana/nominal-types                 │
│  • @solana/assertions                    │
│  • @solana/webcrypto-ed25519-polyfill    │
└──────────────────────────────────────────┘

[lorisleiva]

Hi there, I think anything that could help developers understand the big picture with these packages is helpful. I would just say that in practice (especially when you start digging into the RPC packages) it's not quite as easy to define such cleaning defined groups but there's still plenty of value in doing it IMO.

[datasalaryman]

@mcintyre94 what do you think?

[mcintyre94]

Hmm I'm not sure we have a good way to draw boundaries between things that frameworks use and things that apps use.

We do have some code, especially more recently, that is intended to support higher level use cases, like the recent improved transaction errors and improvements to transaction plan APIs. But these don't really sit neatly in the category of framework or app, they could be useful for either. Obviously more useful for an app that's not using an opinionated framework, but even then I don't think there's a strong boundary.

I think that even with something like plugins that we explicitly designed to support frameworks, there are still perfectly good use cases for apps to write their own if that helps them.

I think we should do a better job of documenting and explaining our package hierarchy, but I'm not sure that discouraging apps from using certain packages is the way to do that. There's also the issue of how meaningful this would be - it's all re-exported from Kit and your tooling isn't going to tell you what you should and shouldn't be using if we draw these boundaries.

I think in general it's important that we keep the use case of writing extremely customised apps that strip away opinionated features in mind too.

One other thing I'd point out is we kind of tried this with some of the wallet-standard stuff - and people rightly complain about importing functions named DO_NOT_USE_OR_YOU_WILL_BE_FIRED to do things that they actually want their app to be able to do without an opinionated library in between.

[datasalaryman]

I'm not sure that discouraging apps from using certain packages is the way to do that

This isn't the intention of the proposal. If stakeholders want to go one level lower than the intended design, they are of course free to do so, at their own risk.

The proposal is more about setting a vision of what APIs we're designing for each user group and then iterating from there. Right now, no such vision exists. The benefit here is that when we get feedback, it becomes clearer at what level the changes to be made.

[datasalaryman]

I've changed the issue title to reflect the idea better. Hope that clarifies things.

[datasalaryman]

@mcintyre94 @lorisleiva let me know if this makes things a lot clearer

[babuClawd]

I took a pass at this and drafted a docs-only approach locally.

Proposed change:

• add a new docs/content/docs/concepts/package-architecture.mdx page
• add it to docs/content/docs/concepts/meta.json

The page frames the repo in practical guidance layers rather than hard boundaries:

1. @solana/kit as the default application entry point
2. domain packages like @solana/rpc, @solana/signers, @solana/transactions, etc.
3. lower-level building blocks like the codecs and RPC spec packages
4. shared helper packages that cut across layers

I think this matches the discussion here pretty well because it helps contributors build a mental model of the repo without implying that lower-level packages are off-limits for advanced apps.

I wasn't able to open a PR from this environment because I don't have push permissions to this repo, but I did prepare the change locally on commit:

• ed5ef36f — docs: add package architecture guide

One small follow-up I'd suggest if this direction sounds right: explicitly call these "guidance layers" in the docs so users don't read them as strict package boundaries.