logo logo
Design: Decisions

  1. Userbase ↗︎ holds engagement data
    To meet requirement 1 Securepub keeps all engagement data in Userbase, an open-source ↗︎ service which runs on Amazon EC2 ↗︎ in the us-east-1 region providing key management and encrypted storage above Amazon DynamoDB ↗︎ and Amazon S3 ↗︎.

    As operators of their respective services, Userbase and Amazon can terminate user access and delete user data stored on their systems. They can also observe metadata such as Userbase usernames and storage details such as the size of encryped data, how often it's accessed, the amounts read and written and so forth. But Userbase's encryption ensures neither Userbase nor Amazon can decypher or use the end-user's encrypted data without their credentials.

  1. Zola ↗︎ provides the overall site
    Zola is a good complement for Userbase. Both are designed for simple static sites. The pages generated by Zola need no server apart from a hosting provider and Userbase only needs access to userbase.com. Zola templating ensures all pages have common styles and resources.

    While Zola has its quirks, the author appreciates the attention Zola gives to performance and details like building internationalized versions of pages.

  1. Bulma ↗︎ provides CSS styling
    Securepub's author is not skilled at CSS and styling. Bulma provides simple examples for common scenarios and has been around long enough to have gathered a helpful community and knowledge base on Stack Overflow ↗︎.

  1. Elm ↗︎ modules provide most but not all dynamic behavior
    The Elm architecture helps ensure model updates are handled properly and data is correctly transformed into HTML. While Elm code can be repetitive and verbose, the end result is very maintainable.

    That said, Elm is not without problems and Securepub departs from Elm in places where it is simpler to use Javascript or Typescript or to use third-party components and libraries. Furthermore Securepub post-processes Javascript code generated by the Elm compiler in order to work around limitations of Elm views.

  1. Elm flags, Zola configs and frontmatter ↗︎ handle internationalized text
    Elm offers no support for internationalized text so Securepub modules obtain text strings and display parameters from flags passed to the Elm init api. Data for the flags comes from json files generated from Zola page frontmatter keeping all static internationalized text together.

    Securepub generates Json decoders with a vendored fork of json-to-elm ↗︎.

  1. Typescript ↗︎ data access modules manage Userbase data
    Elm provides only a rudimentary interface to Javascript so something more is needed to mediate between Elm modules and the Userbase APIs. Userbase operations can also introduce unwanted latency so caching is needed to keep the interface responseive. Typescript data access modules provide this missing functionality. Although less safe then Elm, Typescript's compiler and type system catch many kinds of small errors and helps ensure Securepub behaves properly.

  1. Effect-ts ↗︎ provides workflows, hubs, streams and views
    Effect helps ensure Securepub behaves reasonably when errors occur. The Effect Stream API provides helpful primitives to simplify maintaining views updated by asynchronous callbacks from Userbase which enable database changes to propagate immediately to all client views.

  1. Zod ↗︎ provides schemas
    Userbase provides no schema or structured query language to read and write data so all items read or written to Userbase databases are first parsed by Zod schemas. Zod schemas are also used to parse all messages exchanged between Elm and Effect modules.

  1. Workflow progress descriptions from yaml files
    Securepub has no monitoring systems, logging servers or operators standing by to diagnose problems when things go wrong so application pages include diagnostic progress displays to help users troubleshoot issues. These progress displays show diagrams and messages from the yaml files based on progress messages the Effect-ts workflows send to Elm.

  1. Service Workers ↗︎ serve content
    Securepub relies on a Service Worker to serve shared content to users. Hosts may need to adjust content they share to work within the Service Worker.

  1. GitLab ↗︎ hosts Securepub repositories and website
    GitLab hosts source repositories and GitLab pages hosts the site.
    GitLab also hosts a cstate ↗︎ repository and site for Securepub status.
          Securepub site:  https://gl2401.securepub.org
 Securepub secure origin:  https://gl2401s.securepub.org

       Source repository:  https://gitlab.com/securepub/r2401
Secure origin repository:  https://gitlab.com/securepub/r2401s

   Securepub status site:  https://status.securepub.org
       Status repository:  https://gitlab.com/securepub/status
  1. Sourcehut ↗︎ hosts Securepub mailing lists
    Public discussions and problem reports are maintained on Sourcehut mailing lists.
      General discussion:  ~securepub/discuss@lists.sr.ht
         Problem reports:  ~securepub/problems@lists.sr.ht