We create incredible neighborhoods and community spaces through meaningful shared events. You can find the deployed project at Community Calendar.
- Contributors
- Project Overview
- Build and Installation
- Environmental Variables
- Endpoints
- Available Scripts
- Testing
- Contributing
- Prismatopia
| Rachel Carter | Louis Gelinas | Kennith Howe | Daniel Prue | Josue Rodriguez | Minakshi Verma |
| Skyler Dowdy | Louis Gelinas | Lowell Jacobs | Mark King | Ben Rogers | Westley Strellis |
Product Vision on Notion.
Planned Releases on Notion.
The Community Calendar Backend repository contains code for four services in our stack.
-
An Apollo GraphQL service in the root directory that conducts business logic on GraphQL queries with data collected from the database and authentication services.
-
A Prisma Database ORM service defined in the /prisma/ directory. The prisma-client is ready for deployment on any Prisma implementation, including free deployment on Heroku through Prisma Cloud.
-
An Okta authentication application hosted on Okta.
-
An AWS deployment service
- Serve a list of community events
- Allow users to create accounts with Google, Facebook, or an email address
- Geocode event addresses into lattitude and longitude for location based searching
- Allow community members to create and update their own events
- Allow community members to RSVP to events
- Integrate user profiles for creating, saving, and managing events
- Integrate external event APIs from Ticketmaster, Facebook, and EventBrite
We chose an Apollo GraphQL server over a RESTful API for two reasons:
-
Allow web and mobile clients to request the exact event details they have space to render. This prevents overfetching and increases performance on mobile.
-
Allow the Community Calendar API to be seamlessly expanded to include integration of event data from external APIs in future releases
This back end API is consumed by two clients:
- Web application at React Front End Repository.
- iOS application at iOS Application Repository.
Our app is build on the Prismatopia framework, which includes a Makefile that integrates Docker and AWS Cloudformation templates to deploy the application to development, staging, and production environments.
If you would like to get your own development Community Calendar server running, you can deploy it to Docker containers on your local machine. Follow these steps:
- Clone this repo.
- Create a developer Okta account with a free authorization server.
- Within your Okta service, create Native Application using Client Authentication and create a test user with access to your application.
- Create a
.envfile in the root directory with all of the environmental variables listed in/examples/.env.examplefile. - Ensure Docker Desktop is running.
- Run
make local-upto install packages for each layer of the stack and deploy Community Calendar to Docker containers on your localhost. - Run
make local-prisma-deployto deploy the Prisma datamodel to your Prisma service. - Use
make local-prisma-tokento get a token to include in the HTTP Authorization header in the GraphQL playground of your Prisma service. - Use
make apollo-tokento get a token to include in the HTTP Authorization header in the GraphQL Playground of your Apollo service.
You Review the Prismatopia Documentation for additional information.
The /aws directory contains Cloudformation temples to deploy application level infrastructure to AWS as well as specific production and staging environments. Deploy the application to AWS with these steps:
- Copy
/examples/aws.communitycalendarinto the root directory and update it to reflect the correct environmental variables for your AWS service. - Run
make aws-deploy-appto deploy all of the application level infrastructure that's shared between different environments. - For production, copy the
/examples/aws.communitycalendar.productionfile into the root directory and update it to reflect the correct environmental variables. - Run
make aws-deploy-envto deploy all of the environment level infrastructure, including the Postgres database, Prisma service and Apollo service. - Once deployed, the production apollo server will be at
apollo.<your_domain>and the production prisma server will be hosted atprisma.<your_domain>.
In order for the app to function correctly in development, a .env file in the root directory with all environmental variables in the /examples/.env.example folder are required. All environment variables for use in the apollo server conform to the name APOLLO_VARIABLE_NAME. APOLLO_ is stripped out when injected into the apollo instance through the docker-compose.yml file
For deployment to production and staging environments on AWS, the same variables used for development must also be reflected in a aws.communitycalendar.production or aws.communitycalendar.stage file in the root directory.
Examples of how to format the variables for injection through the Cloudformation temples are in the /examples directory.
If you add an additional service of feature to the application that requires an environmental variables, the corresponding Cloudforamtion files must also be updated. When adding an environmental variable, follow these steps:
- Document the variable in
/examples/.env.examplefor development. - Update the variable in the appopriate Cloudformation script in the
/awsdirectory (most likelyenv-apollo.cf.yaml) - Document the variable in the
/examples/aws.communitycalendar.productionfile - Document the variable in the
/examples/aws.communitycalendar.stagefile
The GraphQL API consists of a single endpoint. In addition to the built-in documentation available from the GraphQL playground, the following queries and mutations can be consumed to conduct CRUD operations on the Community Calendar database:
| Query Name | Access Control | Description |
|---|---|---|
| users (...) | authenticated users | Returns a list of users |
| user (...) | authenticated users | Get user's information and events |
| checkId (...) | Okta service | Verify whether a user already exists |
| events (... | all users | Returns a list of community events |
| tags (...) | all users | Returns a list of tags in the database |
| Mutation Name | Access Control | Description |
|---|---|---|
| addUser (...) | Okta service | Creates a newly registered user |
| addEvent (...) | authenticated users | Create a community event |
| updateEvent (...) | event creator | Update community event details |
| deleteEvent (...) | event creator | Remove a community event from the database |
| eventRsvp (...) | authenticated users | Connect a user to event RSVPs |
| eventSave (...) | authenticated users | A user can save an event to their profile |
Most scripts are run through the make file
Launches the test runner in the interactive watch mode. First resets, regenerates, and redeploys a testing prisma service out of the apollo/testing directory.
Requires a testing instance of Prisma including a postgres database to be running and configured in ~/apollo/testing/prisma.yml.
Default configuration of the testing prisma.yml will work if you have Docker Desktop installed and are running a postgres database image along with a local prisma service at http://localhost:4466.
See the testing section for more information.
Our test runner is Jest for unit and integration tests.
For integration testing, we simulate queries and mutations on the server through the apollo-serving-testing library's createTestClient() function. There are queries and mutations to simulate the expected client server calls written in graphql-tag in the __tests__/__testMutation.js and __tests__/__testQuery.js files.
The test runner is configured by default to run the test suite against a prisma service hosted locally at http://localhost:4000 with an accompanying and postgres database mounted by Docker Desktop. Alternatively, you can configure the test runner to use a Prisma service deployed on the Prisma Cloud.
If you have Docker Desktop installed, you can set up your service and database by running docker-compose up from the apollo/testing folder of the repository. Use docker-compose up -d to run your instances in the background. You can find more information on the docker command line interface in their documentation.
If you've run docker instances with the Prisma CLI before, you may run into the error: ERROR: for prisma Cannot start service prisma: driver failed programming external connectivity on endpoint postgres_prisma_1 (b9aa3375c9374b77bab447b3777d1e5a7d78e0081106699b637065e6db4a5a88): Bind for 0.0.0.0:4466 failed: port is already allocated.
You can clear your Docker setup using the following commands: docker kill $(docker ps -aq) docker rm $(docker ps -aq)
After that, docker-compose up should put your back in business.
Further Prisma documentation for configuring local Prisma servers with Docker is available here.
If don't have to or can't run Docker Desktop, you can modify the endpoint and secret values in prisma-client/testing/prisma.yml to match your deployed Prisma Cloud service.
Our test architecture is set up so that each time you run npm run test it resets, regenerates and redeploys your prisma service defined in apollo/testing/prisma.yml so you start from an empty database/ORM.
To create a Apollo Server instance that you can test, call the constructTestServer() function defined in __tests/__testUtils.js. When writing tests for resolvers that require authentication, you must pass in a valid testUserId out of your database as a parameter for constructTestServer().
Since that database starts from empty for every test run, __tests/__testUtils.js also contains a prismaConnection() function that directly connects to your testing prisma service so you can create and delete test users during your setup and teardown.
Prisma does not provide a simple method for clearing all nodes from the service or data from the connected database, so every test must be written to "clean up" and created events or users when it is done running.
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
Please note we have a code of conduct. Please follow it in all your interactions with the project.
If you are having an issue with the existing project code, please submit a bug report under the following guidelines:
- Check first to see if your issue has already been reported.
- Check to see if the issue has recently been fixed by attempting to reproduce the issue using the latest master branch in the repository.
- Create a live example of the problem.
- Submit a detailed bug report including your environment & browser, steps to reproduce the issue, actual and expected outcomes, where you believe the issue is originating from, and any potential solutions you have considered.
We would love to hear from you about new features which would improve this app and further the aims of our project. Please provide as much detail and information as possible to show us why you think your new feature should be implemented.
If you have developed a patch, bug fix, or new feature that would improve this app, please submit a pull request. It is best to communicate your ideas with the developers first before investing a great deal of time into a pull request to ensure that it will mesh smoothly with the project.
Remember that this project is licensed under the MIT license, and by submitting a pull request, you agree that your work will be, too.
- Ensure any install or build dependencies are removed before the end of the layer when doing a build.
- Update the README.md with details of changes to the interface, including new plist variables, exposed ports, useful file locations and container parameters.
- Ensure that your code conforms to our existing code conventions and test coverage.
- Include the relevant issue number, if applicable.
- You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
These contribution guidelines have been adapted from this good-Contributing.md-template.
Prismatopia is a GraphQL API stack combining a bunch of super-awesome technologies: Apollo Server 2, Prisma, Postgres, Docker, AWS, OAuth, Make, Yeoman and more!
This API is built as a very specific stack of technologies. There no options, other than configuring the existing stack components or swapping them out in your own copy. Enjoy!
Here are the technologies in this stack...
- Provides a GraphQL server for resolvers, which is where your business logic lives
- Provides an ORM to translate from Graphql to Postgres, Apollo resolvers mainly call a Prisma Client to access data
- Provides persistent storage for data, this is managed by AWS RDS in production but is run in a container during local development
- Handles networking (ALB, VPC, etc.) and container management (ECS)
- Apollo is setup for validating JWTs from clients (Works with Okta out of the box)
- There's a local Docker Compose setup for easy development. Also, all AWS services (except Postgres) run in containers
MIT © Lambda School