Logos Ecosystem Development

Sample Apps

4 min read

Sample Apps

Sample apps are PoC applications that are for testnet purposes only (aka, not mainnet). They are created to demonstrate the feasibility of a desired project. They can become a template for developer to build said desired projects and push it to production/mainnet. They can also serve as:

  • Example on how to build on the Logos stack.
  • Demo applications
  • Dogfooding vector to test specific features of the Logos stack

A sample app may have several versions. Each version moves through three phases: Scope, Build, and Document. Each phase has its own deliverables and team review expectations, and the deliverables below are scoped to a single version.

Scope

The scope is agreed upon and reviewed before building starts. It is produced as a PR on the sample app’s repo so the team can review it. Keep it light and nimble. The goal is to agree on a clear, limited scope, trim off any excess, and know when building is “enough”.

The functional scope is what this version will do, captured as FURPS+ or user stories. Lives in a SCOPE.md alongside the sample app.

Sample apps need a clear, limited scope because they exist to:

  • Explore and PoC specific boundaries and designs.
  • Demonstrate what is possible to users.
  • Provide developers a canonical way to build on Logos.
  • Dogfood our documentation, stack and devkit: sample apps are meant to be built using the resources we give to developers, identifying and correcting any issue or gaps.

The functional scope must be reviewed by the team (i.e. as a PR).

Build

The sample app is built against the scope above, in a public repo with the right licensing.

  • The built module is published to the Eco Dev Eng Logos module repo (repo: TBD).

Building involves exploration, so the design and dependency decisions are captured as part of this phase, not up front.

ADRs

Architecture Decision Records documenting why we built it this way, conveying how to use the Logos stack. Lives in an ADR.md alongside the sample app.

The SCOPE.md documents behaviour; ADRs document the reasoning behind design and protocol choices. As we build sample apps, we make decisions to use Logos components (delivery, storage, etc.) in specific ways. We document those decisions so that developers using sample apps as inspiration or examples understand why we did so. For example:

  • In chat, we send messages over delivery because it gives us better latency.
  • But we send images over storage, and then the CID over delivery, because delivery has a small message size (150KiB) and is rate limited (RLN).
  • Justifying why we use the Zone SDK (new zone) vs LEZ.

ADRs must be reviewed by the team (i.e. as a PR).

Dependencies

What the sample app uses: the specific components and design patterns of the Logos stack it depends on. Captured in a Dependencies section of the README.md. Written once here, then reused as the basis for “what the code demonstrates” in the doc-packet.

This makes it easier for a developer to find an example for a specific use case. For example:

  • Upload encrypted data to storage, exchanging the data address (CID) in an e2ee chat.
  • Upload clear data to storage, indexing it in a custom Logos zone.
  • Write an LEZ program that composes with a TWAP oracle program.

Document

Once built, a documentation packet (“doc-packet”) is handed off to the doc team via the doc-packet issue template in the logos-co/logos-docs repo. It covers:

  • How to install (via the Logos module repo) and use it.
  • What the code demonstrates, drawing on the Dependencies above, so developers can find the example matching their use case.

A GUI doc-packet does not need screenshots and can be very light.

The documentation must be reviewed by the team.

Definition of done

A version is shipped once all three phases are complete and reviewed:

  • Scope: functional scope reviewed and merged (PR).
  • Build: sample app built against scope, in a public repo with the right licensing, module published to the Eco Dev Eng Logos module repo (TBD), ADRs reviewed and merged (PR), dependencies documented.
  • Document: doc-packet filed via the logos-docs issue template and reviewed by the team.

Tracking

Each version of a sample app is tracked with two issues on the present repo:

  1. Scope: opened with the Sample App Scoping issue template in this repo. Covers the functional scope.
  2. Build, publish and document: opened with the Sample App Build issue template in this repo. Covers building the app, publishing the module, the ADRs and dependencies, and filing the doc-packet.

Graph View

Backlinks