[RFC] Solidground development environment (wiki)

Solidground
#1

This is a wiki post for collecting notes on the RFC, that anyone can edit.

Considerations

  • Find proper split wrt front-end / back-end code vs. component-oriented development.

Prioritize MLP over MOS

Building a “Moldable Operational System” constitutes a paradigm shift that must be gradually introduced. At this early stage of the project the amount of unknowns are so many, that the MOS concept can only be elaborated at a higher conceptual level. It’s design should inform project direction on an ongoing basis.

Priority is to work towards offering a “Minimum Lovable Process” to stakeholders, which adds value to their solution design process. Napkin sketch of this MLP is taking shape in the documentation, starting from the Social experience design page. Focus is on offering “minimum” functionality first.

This prioritisation trades off initial productivity and time to familiarize with the techstack, with additional refactoring to be postponed to future iterations. In terms of product decisions this entails:

  • Adopt Wasmcloud as-is according to best-practices and as a solution designer.
    • Wasmcloud is undergoing major changes for a 1.0 release, going from Smithy to WIT.
    • Doing: Deploy a Wasmcloud lattice and use NATS in the cluster.
    • Doing: Use wash CLI as documented for Wasmcloud operation.
    • Doing: Containerize Wasmcloud deployment where needed, to the extent needed.
    • Not doing: Make Solidground weave the only CLI that is needed by creators.
    • Not doing: Spin up a “minimal-Wasmcloud” directly from crates (i.e. “Small-tech deployment”).
  • Adopt Nix and std project to the extent where value-add are low-hanging fruit.
    • Nix is complex technology and requires time to familiarize with properly.
    • Doing: Add a flake.nix in the project root, set up using std best-practices.
    • Doing: Use std CLI as documented, and use the TUI where beneficial.
    • Not doing: Make Solidground weave the only CLI that is needed by creators.
    • Not doing: Nix process automations that are too time-consuming or experimental.
    • Beware: Keep watch on Nix community governance & health issues.

Monorepo folder layout

We may start by mapping tool suite and living documentation directly to top-level folders…

/docs
/floorplanner
/groundwork
/taskweave
/weave-cli
/weave-sdk

This is not a good option, for various reasons:

  • Docs in root are easily findable, but living docs are part of the component they belong to.
  • Does Taskweave engine need to be root? It is always hosted somehow.
  • Floorplanner is a just another SX solution and will consist of multiple Service components.
    • Solutions and components should be treated equally whether Solidground or creator owned.
    • Solutions are designed using Workspaces and Projects. How does Floorplanner map to that?
  • Weave CLI and SDK can be aggregated under one top folder.

Elaborating the breakdown to:

/components
  /living-docs
  /workspaces
  ...
/groundwork
  /localhub
  /serverhub
  /taskweave
/solutions
  /design-hub
  /floorplanner
  ...
/weave
  /cli
  /sdk

This design is better in a number of ways:

  • components: To contain a growing list of service components, often reusable, evolving separately, and each representing a discrete bounded context that exists in one or more solutions. The living-docs service component is the framework for building and compiling integrated collaborative documentation facilities. The docs content itself exists in individual components and solutions.
  • groundwork: To contain anything that is core to Solidground MOS. It contains localhub that allows solutions to be hosted within Tauri, serverhub for headless deployment of wasmcloud, and taskweave library/framework for process automation of these hubs. Additional common components may be added to this folder.
  • solutions: To contain a growing list of creator solutions, including Floorplanner itself. The subfolders map directly to the solution blueprint, and will mostly contain config files, build and test scripts as well as docs content created during the Social experience design process. Solidground comes with two solutions, namely Floorplanner Designer and the Solidground Design Hub.
  • weave: Both the command-line interface, and the artifacts and templates that are manipulated by the CLI (or by Floorplanner UI) are together, clearly branded as “Weave”: Core developer tools.

Some open issues are:

  • Component layout (see below).
  • Related. How are front/back-end projects tied into this hierarchy?
    • They may come separate, or bundled in one component.
    • Components may contain multiple (internal) crates/packages. Unless undesirable?
  • Related. Same for living documentation.
    • Ideally bundled with components, but MVP can have docs in one single place.
  • Vendored dependencies (see below). Where do they live?
    • Given that groundwork literally is the foundation, it should be groundwork/vendors only.

Development environment

Moldable development on Solidground MOS involves the ability to evolve solutions while they are in production. The development environment is part of the same social network as the solutions it creates.

Solidground SX offers creators a local development environment. Objective is to bring along the Solidground project itself to be part of the creator’s set up, and make it really easy to contribute upstream. Based on FOSS Development Recommendations wiki and discussions in Guild Alpha chatroom, we have following preferences:

  • In preparation of having fully reproducible builds we want to support Nix package manager.
  • However, for a gentle intro to Nix and good choice for a MVP we start with Devenv.
    • Complete package to get started with reproducible developer environments.
    • Consists entirely of Nix scripts, so has minimum lock-in.
  • We will consider using Direnv to auto-switch developer environments when entering subdirs.
    • Enables use of nix-shell (based on Bash), manages all shell configuration.
    • With polyglot monorepo sub-projects can be great for ease-of-use and overall DX.
    • Might install with Starship to configure beautiful tailored prompts.
  • We will support launching container-based development environments.
  • When it comes to container runtime we favor Podman and not Docker.
    • Our starting point is standards compliance, in this case Open Containers.
    • Podman is community-driven, non-corporate (more small-tech) FOSS project.
    • Ease-of-install, better security (rootless, no deamon, user profiles).
  • Consider using agenix to manage/deploy secrets in Nix environment (uses age encryption).
  • Vendor deps via .nix files that exist in subdirs of vendors (seen in monorepo of monorepos).
    • This way the monorepo size isn’t increased, with Nix dependencies cached on the machine.

With the above, the Getting Started / Installation instructions get quite involved. Could we still have:

git clone solidground.git
cd solidground
./weave start

And let weave go through first-time install guidance on the command line at a clean machine?

Service component folder layout

For service components it is not yet decided how they are bundled. The assumption is that a combination of both front-end (Typescript React app) and back-end artifacts (Rust compiled to WebAssembly) are compressed in an archive using a particular format (TBD).

:point_right:  Service component layout must be separate RFC to tackle after more foundations are laid.

1 Like