Development Priorities

URSYS is a "build framework" for web applications for individuals unfamiliar with program development as part of their job. Instead of pursuing a "no-code" approach, though, the URSYS framework instead tries to introduce programming concepts using a so-called "literate" or "fluent" approach that is more like learning how to write a good essay than memorizing the mechanics of programming; the URSYS doctrine is at heart human-centered and principles-first.

The developer experience goal is to provide immediate gratification and feedback in the development cycle:

• "I can clone the source code from git, do a one-line install, and it runs immediately without other setup".
• "I can modify the source code as the program runs results in instant feedback"
• "I can understand data structures and infer how the program works without 10 years of programming experience plus a CS degree"

I try our best to provide solid patterns that are easy to read and reason about, with full access to the source code within a single monorepo. This is a codebase that is intended to be the common framework for sharing code with others, and learning how it works.

Historical Working Constraints

URSYS grew out of meeting the software needs of Learning Sciences research grants which affects many of its operational decisions. For example, the tools and commands are frequently used by by research primary investigators and graduate students in live sessions with study participants, and it's important that the tools can be used without special knowledge of server administration or software development beyond the absolutely minimum.

Here's the list of considerations that have shaped the development of URSYS and continue to be a priority support constraint:

• Software is designed for use in (1) customizable LAN-based classroom deployments in different institutions and (2) online demo. In 2024 our researcher clients added (3) ease of deploying from servers on the Internet that are accessible from school networks.
• Our target users are academic researchers in Learning Sciences conducting trials in classrooms with teachers and student from the K-12 through undergraduate college level. The software operators have a sophisticated grasp of data collection, media preparation, analytic software, and conducting live trials with teachers and students. They are not generally experienced programmers or system administrators, and are not usually experienced with developer concepts like source control, installing servers, or managing processes. We provide recipes for doing daily operations in the accompanying software Wiki for each project, and hide as much of that detail from them as possible.
• Software servers can run on Macbook Pros running Macos. Web clients can run on Chromebooks and tablets. In 2024 we added Linux (specifically Digital Ocean) support after unofficially maintaining compaatibility.
• Easy file-based data management: this includes databases, templates, location-specific configuration, app runtime settings, session datasets across multiple days, and runtime activity logging. Saving and restoring state can be done through ZIP archives.
• Minimal installation needs: Requirements are Git and Node Version Manager, then git clone followed by npm ci && npm start. Our software is generally command-line based, which requires some training.
• As needed, classroom and student login and session administration tools are provided alongside the software.
• Installation and runtime operational "guardrails" to help non-technical users figure out what's wrong.
• Software "polish" is not a strict requirement as we are not selling this software; it is all open source due to the nature of grants. We therefore choose libraries that have permissive licenses like MIT, and release our source code under the same license.
• Due to the fast pace of development to reach "usable prototype stage" quickly so the researchers can design their trial curriculum around available features, much of the code remains "prototype level". The metric for delivery is that researchers report that they can work around it. Adding feature needs as they emerge through the process is very common.

The software codebase is accessible by the research teams at all phases of development via Github or equivalent repo, and we encourage them to try modifying the code if they are curious. We'd like the "interesting" parts of the codebase to be understandable by people familiar with programming but are not expert in Javascript.

Developer Context

As a standalone framework and library, I have multiple development priorities and directives. Let's start with our developer experience goals for using URSYS:

• Projects are standalone, one-command install and startup without additional configuration needed to “just see something happen” immediately.
• Projects can be built on a Macbook with our minimum installation requirements (xcodeselect to add git and nvm to provide node version control)
• No need to install external servers (e.g. using a self-contained database like sqlite or lokijs instead of mongodb) requiring any deep knowledge of the operating system, package managers, etc in the base tool; "Five minute installation" is the goal.
• Standardize on free tools and code editors to make installation quick and accessible for students and researchers, with standardized config of workspace via prettier, eslint, editorconfig, .gitignore, the vscode .code-workspace and .vscode/settings.json, and nvm.
• Use hot reloading servers wherever possible when any file is touched.

These directives are for providing a uniformly good editing experience for everyone who is touching the source code.

• We enforce source code formatting on save with the prettier configuration file and the VSCode Prettier extension.
• Linting is handled with our custom set of ESLint rules in the editor with the VSCode ESLint plugin.
• Use human-readable data formats in file-based configuration separate from source code
• Accessible folders and files that are in human readable formats for easy “copy and paste” archiving by academic users
• Generally use MIT-licensed libraries, and release under MIT license
• Configure all editors to live-format and flag errors at edit time so users see their mistakes immediately, emphasizing “live-reload” and “live-linting” tools in the code editor
• Enforce (or flag) use of the source code-workspace project file, so recommended VSCode extensions are installed by users
• Provide runtime status messages in the browser javascript

These directives are for maintaining clarity of the source code and program operation for people who are exploring parts of it for the first time.

• System features should be autoconfiguring on startup without need for explicit calls. If they are managing dynamic data, they maintain a collection of a guaranteed up-to-date data in their buffers. Importing a module of this type should handle its connections through the lifecycle interface.
• Leave breadcrumbs that refer to other necessary files or information so new users/researchers can find the relevant related areas, but we try to avoid having too many indirect jumps.
• If multiple files are part of the same system or module, name them so they sort alphabetically together and be consistent with other patterns in the source code
• Add runtime error detection and helpful reporting as confusion and installation errors are noted in supporting the code
• Double-check for clear and consistent technical system naming, avoiding use of words that are overused like “type”, “module”, “feature”, etc as much as possible.

These directives fix coding style that ignores other developers' needs to understand the code and how it works.

• Study the Guide: Codestyle for our module format and required autoformatting support
• Don’t leave debug comments in the source code before making an official pull request
• Don’t leave testing stuff in the Javascript console
• Don’t leave flagged bugs in the code
• Don’t leave unused source code, functions, or API calls. Mark them as unused or deprecated in the function signature or first line of function
• Ensure the build process does not emit ANY warnings; resolve them immediately
• Follow module commenting style and naming conventions defined in .vscode/module.code-snippets
• Check your method names, variables, parameters, and API calls for grammatical and spelling consistency.
• Avoid "tricky code" that uses esoteric knowledge of the language that may be unclear to intermediate-level programmers
• Avoid premature optimization that makes . Optimize when performance becomes an issue.
• Avoid indirect access or multi-hop data lookups/invocations as much as possible. If you are passing the same operation or parameters more than once under different names, try to simplify it.

These directives address repo commits and documentation.

• Describe commits using a human-centered terms as to the effect of your change (providing context) and the technical justification for the change if it tricky or relevant.
• Bug reports should not make assumptions or armchair debug the problem, because they are misleading. Describe ONLY steps to reproduce the bug, then what you expected to happen, followed by what actually happened including a screenshot of what was seen. Because users have such different mental images of how the code works, guessing about the cause in a bug report is not generally helpful even when made by experienced programmers.