Home & Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
The RoundingWell Frontend project is a web application designed for Care Team Operations. It serves as the user interface for clinicians to manage patient care flows, actions, and programs. The project is built using a classic JavaScript stack centered around Backbone.js and Marionette.js, utilizing a modular architecture with shared packages and a robust suite of testing and deployment scripts.
The application emphasizes an "open source by default" culture, leveraging custom libraries such as marionette.toolkit, backbone.store, and Backbone.Radio to manage complex application trees, state synchronization, and decoupled communication. Sources: README.md:1-12, README.md:92-96, README.md:213-215
Tech Stack & Core Dependencies
The project relies on a specific set of libraries to manage the DOM, application state, and utility functions.
Architecture Components
- Backbone & Marionette: The foundational framework for models, views, and application structure. Sources: README.md:92-94, AGENTS.md:14-15
- Marionette.Toolkit: Extends Marionette by providing an
Appclass for lifecycle management and aComponentclass for encapsulated widgets like datepickers. Sources: README.md:95-117 - Backbone.Store: Ensures singleton instances of models in memory, facilitating synchronization between server models and application state. Sources: README.md:123-125
- Backbone.Radio: A pub/sub library used for decoupled communication across different modules. Sources: README.md:94, src/js/README.md:87
- Underscore.js: The primary utility library for data manipulation and functional programming. Sources: README.md:92, src/js/README.md:46-47
Build & Tooling
- Vite: The build tool and development server. Sources: package.json:115, README.md:68-71
- npm Workspaces: Manages shared packages located in the
packages/directory. Sources: package.json:10-18 - Sass (SCSS): Styles are managed via SCSS following BEM (Block, Element, Modifier) naming conventions. Sources: src/scss/README.md:21-25
- Handlebars: The templating engine used for rendering views. Sources: src/js/views/README.md:36-39
| Dependency | Purpose | Source |
|---|---|---|
marionette.toolkit | Application trees and lifecycle | README.md:95 |
backbone.store | Model instance management | README.md:123 |
Backbone.Radio | Pub/sub messaging | README.md:94 |
Underscore | Data manipulation | README.md:92 |
Vite | Build and Dev Server | README.md:68 |
Project Structure
The repository is organized into distinct directories for source code, styles, tests, and configuration.
The application structure separates data access, business logic (Apps), and UI presentation (Views). Sources: AGENTS.md:14-17, src/js/README.md:4-36, test/README.md:28-30
Development & Lifecycle Management
Application Tree
The marionette.toolkit App class is used to build the application tree. Each App manages a lifecycle and an attached state model. Apps typically request data, package it, and choose which views to display. Sources: README.md:96-98
In this program, Apps are made asynchronous by default, meaning they wait for data resolution before completing the start lifecycle. Sources: README.md:100-101, README.md:103-115
Data Access
All AJAX and data-fetching logic must be routed through the entities-service. Direct fetch logic within views or components is prohibited to maintain clear boundaries. Sources: README.md:195, AGENTS.md:26-27
Frontend Conventions
Import Order
A strict import order is followed to maintain consistency:
- Third-party libraries (e.g., Underscore, Marionette)
- Global SCSS/CSS
- Utilities and i18n
- Base classes
- Apps and Controllers
- Views and Components
- Templates and local SCSS
Sources: src/js/README.md:4-36, AGENTS.md:38-46
Styling
Sass follows the BEM format. Selectors used for JavaScript logic must be prefixed with .js- (e.g., .js-submit). State-specific classes use the .is- or .has- prefix (e.g., .is-selected). Styles specific to a set of views are colocated with the view file. Sources: README.md:189, src/scss/README.md:4-25, src/scss/README.md:73-77
Security
The project treats all API data as hostile. Handlebars escaping {{ }} is used by default. When raw HTML must be rendered using {{{ }}}, the data must be explicitly escaped using _.escape to prevent XSS. Sources: src/js/views/README.md:7-14
Testing Strategy
The project employs two primary testing frameworks:
- Vitest: Used for unit testing pure functions and logic. Tests are colocated with source files as
*.test.js. Sources: test/README.md:21-22, src/js/utils/README.md:11-12 - Cypress: Used for both component testing (
*.cy.js) and integration/E2E testing (test/integration/**). Sources: AGENTS.md:18-21, test/README.md:23-24
The repository enforces a 100% coverage baseline for statements, functions, lines, and branches. Sources: test/README.md:11-15
Release and Deployment
Releases are tag-based using the format vYYMMDD.N. The release process is managed via scripts that ensure a clean working tree and sync with upstream branches.
- Release Command:
npm run release - Deployment: Managed by
scripts/deploy.js, which interacts with AWS CloudFormation, S3 (Website Buckets), and CloudFront for invalidations.
Sources: README.md:37-52, package.json:52, scripts/deploy.js:14-18
The deployment process queries CloudFormation stacks for a WebsiteBucket output and uploads the built dist/ directory to S3. Sources: scripts/deploy.js:27-31, scripts/deploy.js:160-165
Conclusion
The RoundingWell app-frontend is a structured Backbone/Marionette application that prioritizes modularity and testing. By utilizing custom tools like marionette.toolkit and strict data-access patterns via entities-service, the project maintains a clear separation of concerns suitable for a large-scale care operations platform. Sources: README.md:95-98, AGENTS.md:26-27, src/js/README.md:4-36