{"id":18230433,"url":"https://github.com/benc-uk/smilr","last_synced_at":"2025-04-03T15:30:25.553Z","repository":{"id":27713143,"uuid":"107663169","full_name":"benc-uk/smilr","owner":"benc-uk","description":"Microservices reference app showcasing a range of technologies, platforms \u0026 methodologies ","archived":false,"fork":false,"pushed_at":"2024-03-23T13:02:04.000Z","size":47417,"stargazers_count":99,"open_issues_count":33,"forks_count":43,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-19T05:42:49.798Z","etag":null,"topics":["azure","cosmos-db","kubernetes","microservice","monogdb","nodejs","vue-spa","vuejs"],"latest_commit_sha":null,"homepage":"http://smilr.benco.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benc-uk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-10-20T10:07:52.000Z","updated_at":"2024-09-29T14:38:57.000Z","dependencies_parsed_at":"2023-10-20T18:21:40.240Z","dependency_job_id":null,"html_url":"https://github.com/benc-uk/smilr","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fsmilr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fsmilr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fsmilr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fsmilr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benc-uk","download_url":"https://codeload.github.com/benc-uk/smilr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027632,"owners_count":20871566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure","cosmos-db","kubernetes","microservice","monogdb","nodejs","vue-spa","vuejs"],"created_at":"2024-11-04T11:04:10.992Z","updated_at":"2025-04-03T15:30:22.632Z","avatar_url":"https://github.com/benc-uk.png","language":"JavaScript","funding_links":[],"categories":["📦 Legacy \u0026 Inactive Projects"],"sub_categories":[],"readme":"# Smilr - Microservices Reference Project\r\n\r\nSmilr is a multi component application \u0026 reference architecure. It has been designed to showcase microservices design patterns \u0026 deployment architectures. It consists of a front end single page application (SPA), two lightweight services, supporting database and back end data enrichment functions.\r\n\r\nThe Smilr app is simple, it allows users to provide feedback on events or sessions they have attended via a simple web \u0026 mobile interface. The feedback consists of a rating (scored 1-5) and supporting comments.\r\n\r\n- The user interface is written in Vue.js and is completely de-coupled from the back end, which it communicates with via REST. The UI is fully responsive and will work on on both web and mobile.\r\n- The two microservices are both written in Node.js using the Express framework. These have been containerized so can easily be deployed \u0026 run as containers\r\n- The database is a NoSQL document store holding JSON, provided by MongoDB and/or *Azure Cosmos DB*\r\n\r\nThe app has been designed to be deployed to Azure, but the flexible nature of the design \u0026 chosen technology stack results in a wide range of deployment options and compute scenarios, including:\r\n- Containers: *Azure Kubernetes Service (AKS)* or *Azure Container Instances* \r\n- Platform services: Regular Windows *Azure App Service (Web Apps)* or Linux *Web App for Containers*\r\n- Serverless compute: *Azure Functions*\r\n- Virtual Machines: Sub-optimal but theoretically possible\r\n\r\nThis application supports a range of demonstration, and learning scenarios, such as:\r\n - A working example of microservices design\r\n - Use of containers, Docker \u0026 Kubernetes\r\n - NoSQL and document stores over traditional relational databases\r\n - Development and deployment challenges of single page applications \r\n - RESTful API design \r\n - Platform services for application hosting\r\n - Using serverless technology to support or provide services\r\n - DevOps practices, automated CI build, test \u0026 release pipelines \r\n - Use of an open source application stack such as Node.js\r\n - The Actor model as an alternative to a traditional data model\r\n - CQRS (Command \u0026 Query Responsibility Segregation) as a possible pattern to separate read and write actions and stores \r\n\r\n---\r\n\r\n# Table of Contents\r\n\r\n- [Architecture \u0026 Core App Components](#architecture--core-app-components)\r\n- [Getting Started](#getting-started)\r\n- [Repository Structure](#repository-structure)\r\n- [Reference Implementation](#reference-implementation)\r\n- [Fundamentals](#fundamentals)\r\n- [Containers \u0026 Kubernetes](#containers--kubernetes)\r\n- [Deploying to Azure](#deploying-to-azure)\r\n- [DevOps \u0026 CI/CD](#devops--cicd)\r\n- [Experimental Implementations](#experimental-implementations)\r\n- [Changelog](#changelog)\r\n\r\n---\r\n\r\n\r\n# Architecture \u0026 Core App Components\r\n![arch](./etc/img/architecture.png){: .framed .padded}\r\n\r\n## Logical Components\r\nThe app consists of four logical components\r\n- **Client Vue.js SPA** - The primary web user interface, as a single page application (SPA)\r\n- **Frontend Service** - Serves the above client SPA and acts as runtime config API\r\n- **Data API Service** - Main REST API used by the app for all data access\r\n- **Database** - Backend MongoDB database \u0026 persistent store\r\n- **Sentiment Service** - *Optional* service for sentiment scoring of user feedback comments. Only used when deploying to Kubernetes. [Read more](kubernetes#optional-appendix---enable-sentiment-microservice)\r\n\r\n## Screenshot\r\n![screenshot](./etc/img/screen.png){: .framed .padded}\r\n\r\n# Getting Started\r\nThere are a number of ways to get started with this project depending on your goals. Below are some suggestions and pointers\r\n- [Running Smilr locally with Node.js](./docs/local-dev.md) - If you're a developer interested in the building and running Node.js and/or Vue.js components locally, this is a good place to start.\r\n- [Deploying to Azure from pre-built images](./azure/templates/aci-quickstart) - Probably the quickest way to deploy Smilr is using ARM templates \u0026 Azure Container Instances running from pre-built images\r\n- [Deploying to Kubernetes](./kubernetes) - This project is an ideal candidate for running in Kubernetes. Step by step documentation is provided to walk through deployment to Kubernetes and Azure Kubernetes Service\r\n\r\n\r\n# Repository Structure\r\nThis is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) so contains multiple discreet but loosely dependant projects. The top levels of the repository directory tree are laid out as follows \r\n```\r\n/\r\n├── archive            Older and experimental code archive \r\n│   ├── mobile             Nativescript + Vue.js mobile client \r\n│   └── go                 Work in progress re-write of the main services in Go\r\n├── azure              Supporting files for Azure deployment etc\r\n│   ├── functionsv2      Azure Functions serverless implementation\r\n│   ├── pipelines        Azure Pipelines for CI/CD\r\n│   └── templates        Example ARM templates\r\n├── docs               Documentation\r\n├── docker             Docker compose files, Note. Dockerfiles are elsewhere \r\n├── etc                Supporting files, pictures and other artefacts \r\n├── kubernetes         Docs and files to support deployment to Kubernetes \u0026 AKS\r\n│   ├── helm             Helm chart for deploying Smilr with Helm\r\n│   ├── advanced         Deployment YAML for use with Ingress, SSL and persistence\r\n│   └── basic            Simple deployment without Ingress or persistence\r\n├── node               Main microservices, written in Node.js\r\n│   ├── data-api         Data API service source code\r\n│   └── frontend         Frontend service source code\r\n├── orleans            Orleans actor based implementation of the Data API\r\n├── testing            Mock test data, API tests and load test scripts\r\n└── vue                The main app frontend, a Vue.js SPA\r\n    ├── src              Source code of Vue.js app\r\n    └── mock-api         Provides a fake API and database for local testing\r\n```\r\n\r\n\r\n# Reference Implementation\r\nThe reference implementation of the Smilr app consists of the frontend server \u0026 data-api written in Node.js and the client as a SPA written in Vue.js. There are alternative versions (detailed below) but currently the core of the project is represented this implementation:\r\n\r\n#### [:page_with_curl: Vue.js SPA - Documentation](./vue/) \r\n#### [:page_with_curl: Frontend Server - Documentation](./node/frontend) \r\n#### [:page_with_curl: Data API - Documentation](./node/data-api) \r\n\r\n### Notes on Security\r\nAs Smilr is commonly used in demos, workshops/labs and for self learning, it defaults to being unsecured and open. This makes it easier to deploy without additional configuration or authentication complications.\r\n\r\nShould you want to secure Smilr, typically because you want to have a permanent \"live\" version hosted and accessible, this is also possible. Securing both single page applications and REST APIs presents some interesting challenges. The approach taken was to use [Azure Active Directory v2 for identity](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-overview), the OAuth2 Implicit Grant flow for authentication and OAuth2 bearer tokens for validation\r\n\r\n- [Securing the Vue.js SPA](./vue/#security) \r\n- [Securing the Data API](./node/data-api#security) \r\n\r\n\r\n# Fundamentals\r\nThese docs covers some of the fundamental aspects of Smilr, which are independent of any particular implementation\r\n#### [:page_with_curl: API Reference \u0026 Data Model](./docs/api-model.md) \r\n#### [:page_with_curl: Database Notes](./docs/database.md) \r\n\r\n## Runtime Configuration \u0026 Settings\r\nThe primary configuration mechanism for this project is system environmental variables (or env vars). These env vars are used with the Node.js services, container runtime, Docker tools and helper scripts. This gives a flexible and cross platform way to inject runtime settings, it is also widely supported in Azure (e.g. Azure App Service Settings) and Docker/Kubernetes.\r\n\r\nThere are numerous ways to set \u0026 override environmental variables; in the operating system, the user profile or from command line tools. For local development purposes it is strongly recommended you create \u0026 use `.env` files. These are simple text files containing `var=value` pairs. Sample files named `.env.sample` are provided within the project, which you can rename and use. *Note.* `.env` files can often contain secrets so they are prevented from being committed to Git\r\n\r\n\r\n# Containers \u0026 Kubernetes \r\nAs containers and Kubernetes represents such an important build \u0026 deployment scenario, they have dedicated guides and documentation\r\n\r\n#### [:page_with_curl: Building Smilr as Containers](./docker)\r\n#### [:page_with_curl: Running and deploying in Kubernetes](./kubernetes)\r\n\r\n### Public Images\r\nPre built images are available on Dockerhub. Using these will naturally mean you can get started deploying/running Smilr without needing to do anything. However building your own is still recommended, especially if you want to understand the build process in more detail. \r\n\r\nImages for the Node.js data API and frontend (serving the Vue.js client) are available. \r\n- The `stable` tag is only pushed after some manual validation and testing,\r\n- `latest` is auto-pushed with latest code every night\r\n\r\n##### [Smilr on Dockerhub 🡽](https://hub.docker.com/u/smilr)\r\n\r\n\r\n# Deploying to Azure \r\nSee provided Azure Resource Manager (ARM) templates to allow you to deploy the complete Smilr app and all components to Azure. As all deployment scenarios are container based you also need to refer to the containers section described above\r\n\r\n#### [ARM Deployment Templates](./azure/templates)\r\n\r\n\r\n# DevOps \u0026 CI/CD\r\nAutomated CI/CD pipelines have been created using Azure Pipelines. These automatically build the various components as containers and releases them to Azure for testing. The current status of these builds \u0026 releases is shown below\r\n\r\n| Automated Build | Status |\r\n|---|---|\r\n|Linux Images \u0026 Tests|[![Build Status](https://dev.azure.com/bencoleman/Smilr/_apis/build/status/Build%20to%20ACR%20and%20Deploy%20to%20ACI?branchName=master)](https://dev.azure.com/bencoleman/Smilr/_build/latest?definitionId=73\u0026branchName=master)|\r\n|Windows Images \u0026 Dockerhub|[![Build Status](https://dev.azure.com/bencoleman/Smilr/_apis/build/status/Build%20to%20ACR%20and%20Deploy%20to%20ACI?branchName=master)](https://dev.azure.com/bencoleman/Smilr/_build/latest?definitionId=73\u0026branchName=master)|\r\n\r\n\r\nYou can visit the Azure Devops Public Project where these pipelines reside, although keep in mind the source code repo remains here on GitHub.\r\n##### [DevOps Public Project - Smilr 🡽](https://dev.azure.com/bencoleman/Smilr)\r\n\r\nIf you want to try using Azure DevOps to build Smilr, [the pipelines are provided as YAML for your own use](./azure/pipelines). An Azure DevOps account/organisation is required to use these, but can be setup for free.\r\n\r\n\r\n# Sub Projects\r\nThere are several sub-projects and re-implementations of the Smilr architecture. Either at the backend, providing an API compatible with the data-api REST specification. Also the frontend has been implemented as a mobile app. All of these alternatives are considered experimental and for technology demo use cases \r\n\r\n- [**Serverless - Azure Functions**](./azure/functionsv2)\r\n- [**Go aka Golang**](./go)\r\n- [**Native Mobile App**](./mobile)\r\n\r\n\r\n# Changelog \r\nHigh level project changes and overall history are recorded here:\r\n\r\n- *Jan 2020* - Rewrote Node.js data API, using MVCS pattern\r\n- *Jul 2019* - Start of Go implementation. Archived old sub-projects\r\n- *Jun 2019* - Security improvements, MSAL and token validation\r\n- *Dec 2018* - Total rewrite of SPA in Vue.js and proper AAD security\r\n- *May 2018* - Major updates for Kubernetes deployment \u0026 Angular 6\r\n- *Mar 2018* - Switched to MongoDB for database\r\n- *Jan 2018* - Simple onetime password security added to API\r\n- *Dec 2017* - Name changed to Smilr\r\n- *Nov 2017* - Switched to CosmosDB SQL API (aka DocumentDB)\r\n- *Oct 2017* - Project created, using Azure Table storage\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenc-uk%2Fsmilr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenc-uk%2Fsmilr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenc-uk%2Fsmilr/lists"}