A simple, responsive web application to take notes, built with JavaScript, designed as starting point to build complex web applications. Each application in the system can be run independently with Docker or npm. Unit, integration and end-to-end (e2e) tests are available. Development, release, integration and e2e test environments can be simulated with Docker Compose.
This project is a modernized version of cloud-apps, hosted on AWS. The upgrade introduced new technology to the stack, including React + Next, GraphQL, Automated database tests & migrations, and Playwright end to end tests.
- Quickstart
- Usage instructions
- Core Concepts
- Application docs
- How to contribute
- Tools and frameworks
- License
Docker is required.
docker-compose -f dev.yaml up
docker-compose -f release.yaml up
docker-compose -f integration-tests.yaml up --exit-code-from integration
docker-compose -f e2e-tests.yaml up --exit-code-from e2e
docker-compose -f migrations.yaml up
docker-compose -f data-tests.yaml up --exit-code-from data_tests
Node.js v20.9.0 or higher and Docker are required.
npm run dev
npm run start
npm run integration-tests
npm run e2e-tests
npm run migrations
npm run data-tests
Find detailed instructions on how to run each application within the Application docs.
A new note can be created in a few simple steps:
As a modernized version of cloud-apps, this project introduces new concepts that should facilitate development for complex use cases, including:
- Hosted on AWS
- Enterprise-grade blueprint for CI/CD with CircleCI
- End to end tests with Playwright
- Automated database migrations & tests
- Lightweight dependencies for fast build and test times
- GraphQL to simplify RESTful endpoints
In addition to the new core concepts, this project shares the same core concepts as cloud-apps, including:
- Container orchestration for scale
- Automated test pyramid
- Blueprint for automated tests with CircleCI
- Full stack system built with JavaScript
- Starting point for more complicated use cases
The project's Client, API and Database are hosted on AWS. Leveraging CircleCI, the Client and API Docker images are built & deployed to AWS' Elastic Container Registry(ECR), then hosted with Elastic Container Service (ECS) and Fargate. The database is hosted on AWS' Relational Database Service(RDS).
The diagram below outlines how network connections are managed between resources in AWS:
A cloud-like network can be simulated with Docker Compose. The diagram below outlines Docker Compose network connections:
Unit tests for the Client, API and Database are run on every pull request to Github, using CircleCI. Once the unit tests have passed, integration tests are run, validating API and Database updates. After integration tests pass, e2e tests are run, validating that the Client, API and Database work as expected with the new updates. Once all tests have passed, the pull request can be merged to the main
branch, which kicks off deployments.
Deployments begin by simultaneously running the jobs to build & deploy application Docker images and Database migrations. Once Docker images have been deployed to ECR, CircleCI updates ECS with the new Docker images, performing rolling deployments for the new application versions.
Following the fail-fast automated testing approach, the system provides a starting point (or blueprint / boilerplate) as-is for more complex automated testing requirements. The diagram below outlines how code updates are validated then deployed with Github and CircleCI:
Playwright is a popular end to end testing framework, allowing developers to write tests in JavaScript, Python, Java, or .NET. Helpful tools like the UI mode make it easy to debug web applications in real time.
This project provides a starting point for Playwright end to end tests with JavaScript, leveraging page object models. Basic smoke and health tests are provided. To learn more, feel free to read the end to end tests docs.
Playwright simplifies the required infrastructure to run e2e tests, since the library provides out-of-the-box browsers and connects to browsers internally without the need of a seperate hub.
The diagram below outlines the simplified network created by Docker Compose, for e2e tests, including application connections, ports, routes and tools:
Automated database migrations are available to facilitate database integrity and updates with automation.
To accompany programmatic database schema and structure updates, database updates are validated with unit tests using the Jest and pg npm libraries. Tests are provided for health checks, migrations and common queries.
Build times are improved through NPM's development only installations , production only installations, CircleCI caching and Docker. Build & run times for each test application is less than a minute, with the exception of end to end tests, which install and run the entire system.
GraphQL simplifies the code required manage RESTful API endpoints and responses. Apollo Server provides helpful tools to debug, and simplify maintenance of GraphQL APIs.
Client
API
Database
Integration tests
End to end tests
Node.js
Docker
CircleCI
AWS
React
Next.js
GraphQL
Apollo Server
PostgreSQL
Jest
Supertest
Playwright
Our commits follow the Angular commit styleguide. Each commit should be carefully thought out and only contain files affected within the scope of the commit message.
A branch's name should reference a story and the type of work being committed.
Each pull request must pass a review from another contributor and all automated tests.
Feel free to open an issue ticket, please leave a screenshot and a detailed instructions on how to replicate the issue.
This repository is protected under the MIT License.