SNOMED CT Authoring UI
The Authoring UI is an AngularJS-based single-page web application that powers the front-end of the SNOMED CT Authoring Platform. It provides concept search, editing, project management and review workflows for authors and reviewers while integrating with a rich ecosystem of backend services (Authoring Services, Snowstorm, CIS, ActiveMQ, AWS S3, Consul, Vault ...).
This document explains how to run the UI locally and the engineering conventions you should follow when working on the code-base.
1 High-Level Architecture
flowchart TD
Browser["Web Browser"] --> |HTTPS| Nginx[(Nginx)]
Nginx --> AuthoringUI["Authoring UI (AngularJS SPA)"]
AuthoringUI --> |REST & WebSocket| Gateway[(Authoring-Services)]
Gateway --> |REST| Snowstorm[(Snowstorm Term Server)]
Gateway --> |REST| CIS[(CIS)]
Gateway --> |REST| IMS[(IMS)]
Gateway --> |REST| Jira[(Jira)]
Gateway --> |JMS| ActiveMQ[(ActiveMQ)]
subgraph External Config & Secrets
Consul[(Consul)]
Vault[(Vault)]
end
AuthoringUI -. consumes .-> Consul
Browser["Web Browser"] --> |HTTPS| Nginx[(Nginx)]
Nginx --> AuthoringUI["Authoring UI (AngularJS SPA)"]
AuthoringUI --> |REST & WebSocket| Gateway[(Authoring-Services)]
Gateway --> |REST| Snowstorm[(Snowstorm Term Server)]
Gateway --> |REST| CIS[(CIS)]
Gateway --> |REST| IMS[(IMS)]
Gateway --> |REST| Jira[(Jira)]
Gateway --> |JMS| ActiveMQ[(ActiveMQ)]
subgraph External Config & Secrets
Consul[(Consul)]
Vault[(Vault)]
end
AuthoringUI -. consumes .-> Consul
Typical Editing Session
sequenceDiagram
participant Author as Author (browser)
participant UI as Authoring UI
participant Gateway as Authoring-Services
participant Snowstorm as Snowstorm
Author->>UI: Search concepts
UI->>Gateway: /api/search?term=heart
Gateway->>Snowstorm: /browser/...
Snowstorm-->>Gateway: JSON results
Gateway-->>UI: Normalised search results
Author->>UI: Open concept editor
UI-->>Gateway: WebSocket subscribe /concept/{id}
Author->>UI: Save changes
UI->>Gateway: PUT /concept/{id}
Gateway--)ActiveMQ: publish concept.updated
ActiveMQ-->>UI: WS event - live update
participant Author as Author (browser)
participant UI as Authoring UI
participant Gateway as Authoring-Services
participant Snowstorm as Snowstorm
Author->>UI: Search concepts
UI->>Gateway: /api/search?term=heart
Gateway->>Snowstorm: /browser/...
Snowstorm-->>Gateway: JSON results
Gateway-->>UI: Normalised search results
Author->>UI: Open concept editor
UI-->>Gateway: WebSocket subscribe /concept/{id}
Author->>UI: Save changes
UI->>Gateway: PUT /concept/{id}
Gateway--)ActiveMQ: publish concept.updated
ActiveMQ-->>UI: WS event - live update
Key points:
- Stateless front-end - all state resides in backend services, enabling horizontal scaling.
- Grunt & NPMher drive the build pipeline; assets are bundled as a static site.
- WebSockets (STOMP) deliver live task/status updates without polling.
- Built artefacts are served via Nginx or any static web-server and can be cached aggressively.
2 Feature Highlights
- Component Search & Filter - powerful term + ECL search with language reference-set filters ( @https://github.com/IHTSDO/authoring-ui/blob/master/app/shared/search/search.js ).
- Concept Editing - full SNOMED CT concept editor with axioms, descriptions, relationships ( @https://github.com/IHTSDO/authoring-ui/blob/master/app/components/edit/edit.js ).
- Project & Task Management - create, merge and review authoring tasks ( @https://github.com/IHTSDO/authoring-ui/blob/master/app/components/project/project.js ).
- Batch Editing & Template Authoring - bulk operations and domain templates with validation ( @https://github.com/IHTSDO/authoring-ui/blob/master/app/shared/batch-editing/batchEditing.js ).
- Classification & Integrity Checks - client-side dashboards for Snowstorm classification runs ( @https://github.com/IHTSDO/authoring-ui/blob/master/app/shared/classification/classification.js ).
- Responsive Layout - Bootstrap 3 and custom SCSS for desktop & tablet workflows.
- End-to-End Tests with Cypress ( @https://github.com/IHTSDO/authoring-ui/blob/master/cypress/e2e/test.cy.js ) and unit tests with Karma/Jasmine ( @https://github.com/IHTSDO/authoring-ui/blob/master/test/karma.conf.js ).
- Structured Logging via
$logservice wrappers. - Consul & Vault support - runtime config and feature-flags fetched at start-up.
3 Project Layout
app/
index.html - entry-point & ng-view outlet
app.js - root module & route config
components/ - feature modules (edit, project, ...)
shared/ - cross-cutting services & directives
styles/ - SCSS source
images/ fonts/ - static assets
cypress/ - e2e tests
Gruntfile.js - build & dev-server tasks
package.json - JS dependencies
Naming conventions:
components/**Feature-scoped MV* modules (HTML, JS, SCSS colocated).shared/**Reusable services, directives and filters.utilities/**Helper scripts consumed across components.
4 Getting Started Locally
4.1 Prerequisites
- Node 18+ with npm (use nvm).
- Grunt CLI -
npm install -g grunt-cli. - Backend services reachable on the default local URLs (Authoring-Gateway -
localhost:8080).
Hint: A lightweight docker-compose stack for the backend is under discussion - contributions welcome.
4.2 Clone & Install
git clone @https://github.com/IHTSDO/authoring-ui.git
cd authoring-ui
npm install # installs node & bower dependencies
cd authoring-ui
npm install # installs node & bower dependencies
4.3 Run in Development Mode
grunt serve # opens http://localhost:9000 with LiveReload
- Edits to HTML/JS/SCSS trigger automatic reloads.
- API calls are proxied to
localhost:8080- adjust inGruntfile.jsif required.
4.4 Build for Production
grunt build # outputs minified site to dist/
Copy the contents of dist/ behind any static web-server (Nginx, S3, CloudFront ...).
5 Testing
- Unit Tests -
npm testruns Karma/Jasmine suites located underapp/**/*.spec.js. - End-to-End -
npx cypress openlaunches Cypress with tests incypress/e2e/.
6 Deployment
- Run
grunt buildto create the production bundle. - Upload the
dist/folder to your static hosting provider (Nginx root, S3 bucket, Azure Blob ...). - Configure cache-busting headers - files are fingerprinted by
grunt-filerev. - Behind an Nginx ingress add:
location / {
try_files $uri $uri/ /index.html; # SPA fallback
}