open-source-programs icon indicating copy to clipboard operation
open-source-programs copied to clipboard
verified publisher icon TBD54566975

[PROPOSAL] - Getting Started Application

Open ALRubinger opened this issue 2 years ago • 9 comments

Getting Started Experience

Desired outcome Meet the needs of those curious about building Web5 Applications: get them going. 3 minutes to their first win. Scale as the point of entry for new applications for newcomers and experts alike. Create a robust experience for making Web5 applications: using software launchers (webapp and command-line), sample application, scaffolding for new applications, and playgrounds. A comprehensive, joyful experience which bridges software and services used to make new Web5 apps, supporting documentation, stores of examples and feature scaffolds, and playgrounds.

Tagline: "Your fully-working new Web5 Application, in 3 minutes."

Principles:

  • User-first design
  • Invest 3 minutes, you get everything working out of the box.
  • All code given to users is documented and may link to additional references - the "polished" experience
  • Target demographic: Web5 Application Builders and Web5 Platform Contributors
  • "Design for 'wow'" - the experience should make clear the real-world importance of each feature
    • Must make clear the why each feature is important
    • ...but frame examples to clearly show what Web5 and Decentralization do that traditional web programming can't.

Current Gaps Right now: contributors and builders alike, including those on our team, don't yet have a clear understanding how to create a new Web5 application.

  • What code scaffolding is needed?
  • What features are available - what intrinsic value can builders get?
    • We need a clear "wow" (Bobbilee) or "what's in it for me"
    • Bobbilee notes D's example: showing Alice and Bob getting an employment verification: so what?
  • What do users want to do with Web5?
  • Angie observation from folks: "Web5 sounds cool, how do I get started building my app? I don't need all this education and abstract materials on DIDs and DWNs, etc - show me the code."
  • Angie: "I'm the developer who wants to build my app - get me started"
  • Nick: "I don't want to look at docs; I want a running application so I'm dropped in, and I'll learn as I go"
    • "...and as I go along, I'll run into issues where I want docs, so point me there so I can make this work for me"

Implementation Suggestions This section will need to be prioritized and scoped into Phases. Brainstorming only:

  • We could off with a generic starter repo for getting up and running with a Web5 project. Eventually we can have a create-web5-app command
  • A low-level option is to do this strictly in docs: creating tutorials oriented around "How to build a Web5 Application" and start up an Examples bank to support.
  • In a mature system, architectural pieces:
    • Repositories for:
      • Sample Applications
      • Feature Scaffolding
        • The pieces of code which enable a feature
        • Concretely from @csuwildcat: "You import a SCRIPT tag, call the Web5.connect(), and you're off to the races with the Web5 SDK."
        • PWA Scaffolding, from @csuwildcat example here
      • Playgrounds

User Input Suggestions From brainstorming w/ @michaelneale @csuwildcat:

  • Choose your type of app:
    • Greenfield - New Web5 Application
      • Non-PWA Webapp
      • DWA - PWA example w/ SCRIPT tag and the most powerful example
    • Existing web site
      • Give them scaffolding instructions to "Web5-ize their existing apps", adding a SCRIPT tag, documenting the Web5 SDK calls to make, how they must have a wallet
      • And how to call upon that to do some test message sending or something
    • If you want to add DID Authentication to a website
      • Tutorial set for integrating ID with nonce of existing site

Architectural Design to Consider

  • Backend
    • Responsible for taking user inputs, assembling the codebase we'll give them, and returning it to them either as a compressed file or directly into GitHub.
      • If directly into GitHub we can also build/deploy the example for them using Actions.
  • Backing "store" repositories
    • Sample applications
    • Scaffolding code pieces
    • Playgrounds?
      • Or are these simply deployed and available, and we link to them from the developer site? Are they "launched" to the user in software?
  • Frontends
    • Web Application
    • Command-line Application (npm? Rust?)

General Remits Defined as light guidance for slicing and parallelizing work

  • Open source engineering: Labs, proof of concepts, core software releases
  • Developer Relations: Example applications bank and tutorials
  • Programs: Webapp, command-line app, launching infrastructure, DRI of the collective experience

Types of Web5 applications

  • Samples
    • Fully-working, illustrative of solving a use case, and are "high polish": meaning, they're very documented at the code level as to what's going on and why, and additionally points to reference material explaining more either in tutorials or api-docs.
    • From an "app store" of examples we can build out over time
  • Playgrounds
    • An online service where you can write, compile, and run - and see the impact of those changes live.
  • Scaffold/skeleton new Applications from Features
    • User selects from a list of features they'd like to scaffold out
    • Are given the selected features alongside a console application which runs them

Example Web5 Application Ideas

  • Technical Areas to Highlight:
    • The power of DIDs
      • Access features from different sites based on DID
    • Visualizing VCs
    • Demo of Web5.connect(): web5-wallet-browser

Similar Approaches to Build Off

  • start.spring.io
    • Web application which, based on user inputs, scaffolds out a new application and makes it available as a download.
  • create-react-app
    • Node module to scaffold a new application directly in the filesystem as a command-line utility
  • Ionic Framework
    • A meta framework for getting started with popular web frameworks (React, Vue, Angular)

ALRubinger avatar Feb 09 '23 20:02 ALRubinger

Open for ideas and more input!

After that:

  • Aligning on the Big Deliverable
  • Breaking it down into a Phased delivery approach or Roadmap
  • Decomposing into actionable pieces of work

ALRubinger avatar Feb 09 '23 21:02 ALRubinger

Updated description to reflect additional inputs from @csuwildcat @michaelneale

ALRubinger avatar Feb 10 '23 00:02 ALRubinger

Some building-block-apps that I personally would love to see on a getting started experience like this one:

  1. Create a "Sign in with your DID" button, to be integrated in a webpage.

  2. How to make two DIDs send messages to each other.

  3. How to Issue a VCs after passing a CAPTCHA or something.

  4. How to send a file to your DWN and store it there. How to get the file from there.

  5. How to create a bash script that does point 4) automatically for a folder.

Simple stuff like these are really really helpful. The examples create something that one can use, but more importantly they give you the building blocks for your Web5 app.

pippellia-btc avatar Feb 10 '23 08:02 pippellia-btc

Maybe a tutorial along the lines of the following:

A PWA that walks through a brief outline of a DID and then creates one and stores the details such as the tutorial here https://github.com/frankhinek/did-ion-examples. Then a brief outline of a DWN and then a form to create a record entry sent to a hosted DWN set up by TBD. Then a talk through the ways to query the DWN and a form to do so for a pre-prepared entry that allows access (and maybe an example for one where they don't have access). Then finally a talk through how VCs work and then one is issued to the user to finish the tutorial. So at the end of it they can download their DID info and VC in a text file so that they can perhaps use them for their own attempts, or just have something concrete to show how it all worked.

nearlyjuly avatar Feb 10 '23 11:02 nearlyjuly

I like @pippellia-btc list above. #2 is addressed in a way by: https://github.com/TBD54566975/dwn-cli so that is good.

They are all nice ways to break it down into examples that someone can build from that are relevant to them.

michaelneale avatar Feb 13 '23 02:02 michaelneale

Some building-block-apps that I personally would love to see on a getting started experience like this one:

  1. Create a "Sign in with your DID" button, to be integrated in a webpage.
  2. How to make two DIDs send messages to each other.
  3. How to Issue a VCs after passing a CAPTCHA or something.
  4. How to send a file to your DWN and store it there. How to get the file from there.
  5. How to create a bash script that does point 4) automatically for a folder.

Simple stuff like these are really really helpful. The examples create something that one can use, but more importantly they give you the building blocks for your Web5 app.

excellent list! 🎯

angiejones avatar Feb 14 '23 00:02 angiejones

  • How to accept VCs within my app

angiejones avatar Feb 14 '23 00:02 angiejones

Some ideas from the team this week on the getting started code block...

Either of these...

  1. Generate a DID, store private keys
  2. Set up local DWN (instantiate DWN)
  3. Write first record to DWN
  4. Usage of record interface method
  5. Protocols
  6. For a credential application or presentation exchange:
    • set up server (create identities)
    • build your flow (create schemas, presentation definition)
    • test your presentation (issue yourself some credentials and submit)
    • open it to the public

bobbilee19 avatar Feb 14 '23 17:02 bobbilee19

Closely related work, perhaps even to be aligned as pieces of one Workstream:

ALRubinger avatar Feb 16 '23 01:02 ALRubinger