This document focuses frontend and backend development of Purpie project and gives information about Purpie Tech Stack.
git clone https://github.com/doganbros/purpie cd purpie
Set environment variables into .env file:¶
cp .env.example .env
Then make changes to the boilerplate provided
Setting web server and routing¶
If Purpie is installed on your local computer, you will need to add the following line to your hosts file. The hosts file for Unix based system including MacOs is
/etc/hosts where as on Windows, it is
Visit http://purpie.localhost:3000 (3000 is the default port) and create your super admin user.
Node.js. (>= 10.13.0, except for v13) (Windows Build Tools for Windows systems)
First steps are same with fronted setup.
Create Postgres database¶
Please follow the steps below to get a development Postgres server running. The easiest way to use docker. If you have running Postgres database server you can skip these steps and simply create an Purpie database.
Make sure you have docker installed on your computer. If you do not have docker already on your computer, Go to https://www.docker.com/get-started, choose your platform and click download. Follow the simple steps to get docker installed on your computer.
Open your terminal (command prompt or preferably powershell on windows).
Enter the command
docker run --name purpie-postgres-dev -e POSTGRES_PASSWORD=YOUR_DB_PASSWORD -p 5432:5432 -d postgres
Postgres docker image will be downloaded and Postgres Docker container with the name purpie-postgres-dev will up and serve from port 5432 after this command.
To connect your Postgres database.
docker exec -it purpie-postgres-dev psql -U postgres
To create your Purpie database.
CREATE DATABASE purpie;
\qto quit from Psql and Docker container.
To run backend server in production
To run backend server in development
Visit http://purpie.localhost:8000/swagger/ to try out some backend APIs.
Typescript (Strict Mode)
yarn for package management
Handlebars for rendering email templates
NestJS is the main framework
Postgresql is the database used
TypeORM is the database ORM used
Class Validator is used to validate request body.
helmet is used to set http headers correctly.
dotenv is used to load .env variables
Monitoring with pm2
Open Source Technologies used¶
🏠 represents client side
🖥️ represents server side
This is a single page web application, that is it handles routing at the
client-side without the need to refresh the entire page. All http
requests are done using
data exchange format used between this app and the server is
HTML is rarely used in this app. It is primarily used to setup the
main index file that is responsible for loading the main javasript of
the app. It loads the css and display the initial title of the app.
This app uses no
Typescript is the main programming language used on the server and
for building the user interface.
Frameworks and Libraries¶
Nestjs is a progressive Node.js framework for building efficient, reliable and scalable server-side applications. It works well with typescript and follows the SOLID principle
The OpenAPI specification is a language-agnostic definition format used to describe RESTful APIs. Nest provides a dedicated module which allows generating such a specification by leveraging decorators.
Handlebars is used to render email templates before they are sent to clients.
SendGrid is the main service used for sending emails.
Allows use of decorator and non-decorator based validation. Internally uses validator.js to perform validation.
Axios is a promise based HTTP client used in this app. All AJAX
requests are handled with
axios. Their interceptors really help to
avoid redundancy in most part of the app.
This app uses no
CSS (Although it compiles to css in the long run).
SCSS is rearely used in this app. It is used to style a large
portion of the app.
SCSS Modules is recommended if
SCSS is used.
node-sass is the library responsible for compiling the app’s
This app uses the latest version of
React Framework (Library) in
all the components. Only Functional Components are allowed for
writing all React Components.
Grommet is a
React styled-component library that helps in building
responsive and accessible mobile-first projects for the web. Since this
framework provides lots of styled-components, writing
scss is often
not required at all. Developers are required to use most of the features
of Grommet without writing lots of
React Router (Its DOM binding
React Router DOM) is the library
used to for handling all the client side routing of this app. Note
that instead of using the library’s main
components, AnchorLink and NavLink are used respectively. This is to
make it compatible with the Grommet library. To navigate to other paths
of the app inside a component, the
useHistory hook is used. Routing
done in other parts of the app app (especially in a Redux action) uses
appHistory helper function insead.
Apps. This is the main state management library used in the app. Mostly
states that are shared across multiple components of the app use redux.
Also all network-related states are handled here.
react-redux is the
library that helps in binding redux to react.
the redux middleware that helps the app to deal with asynchronous
dispatches in redux actions.
React-i18next is a powerful internationalization framework for React / React Native which is based on i18next. Our goal is to support as many languages as possible with the help of this framework and community.
Eslint statically analyzes the application code to quickly find
problems. It helps in maintaining the usage of Airbnb coding style guide
and the similarity of code written by different develops at a time. Run
yarn analyze or
npm analyze to let eslint analyze and report all
errors made. If you are using editors like vscode please install the
eslint extension to help you in automatically detecting errors.
Prettier is an opinionated code formatter that helps the app to
format the code written to comform to the rules of eslint. Run
yarn format or
npm format to do a quick format of the entire
While using nestjs at the server-side, One must follow these guidelines.
NestJS pattern must be followed strictly. For example controllers should be used to handle only http requests, services must be used to generate data or communicate with the database, guards must be used for securing routes etc.
controllers and providers should reside in controllers and services directories respectively.
Implement global providers if they are needed only. This will help other developers know from which modules those services are imported from. Example authentication and exceptions would be needed in the entire application but zone service wouldn’t.
@IsAuthenticated()decorator should be used to validate the current user’s token. Also permissions could be passed in as paremeters if they are needed.
Document the controllers written extensively (using decorators provided by Nestjs for OpenAPI). This helps other developers to make requests very easily without reading the source code.
The built in NestJS exceptions must be used accross the entire application. The first paramter must be a message about the error. And the second parameter must be an error code. For example while generating an error for invalid bearer authentication token, the example below is used.
throw new UnauthorizedException( 'You not authorized to use this route', 'NOT_SIGNED_IN', );
While using TypeORM at the server-side, One must follow these guidelines.
The models designed must be relational. That means you must use
ManyToManyrelation when it is necessary.
When models, fields, column, etc. are added a migration script must be written in respect of that. This is because we are not using syncronization as it not good for production. Note that nestjs will run pending migrations when the application is booted automatically.
Guards In This Application and their usage¶
This section introduces the main guards used in this application
The AuthGuard validates the current bearer token passed to the server when making requests. It sets the payload of the user to
req.user. It also thows an
UnauthorizedExceptionexception when the token is invalid.
The UserZoneGuard validates the current user’s authorization to the zone that he/she is requesting. It sets the user zone to
req.userZone. Other permissions can be passed in using the
SetMetadatadecorator. It also throws an
NotFoundExceptionexception when the user is not authorized.
Pipes in this application and their usage¶
This section introduces the main pipes used in this application
The ParseTokenPipe is used to parse a JWT. If it succeeds it passes the payload to the parameter. Otherwise it will throw an
Decorators in this application and their usage¶
This section introduces the main decorators used in this application
The IsAuthenticated decorator wraps over the AuthGuard to avoid writing lots of boilerplates while passing permissions to the AuthGuard.
The UserZoneRole decorator wraps over the UserZoneGuard to avoid writing lots of boilerplates while passing permissions to the it. It also extends the IsAuthenticated decorators so if you do not need to specify it while using it on a route.
The UserZoneRole decorator wraps over the UserChannelGuard to avoid writing lots of boilerplates while passing permissions to the it. It also extends the IsAuthenticated decorators so if you do not need to specify it while using it on a route.
The CurrentUser decorator is helper to retrieve the current user’s jwt payload
The CurrentUserZone decorator is helper to retrieve the current user zone. Notice that it zoneId or userZoneId must be set as params in order to retrieve this.
The CurrentUserChannel decorator is helper to retrieve the current user channel. Notice that it channelId or userChannelId must be set as params in order to retrieve this.
Middlewares Used in this application¶
This section introduces the main middlewares used in this application.
The PaginationMiddleware parses all get requests’ pagination query paramters. All get requests pass through this middleware. This means that, the pagination query parameters
req.query.skipare passed to controllers automatically (Global middleware for get requests). It can in turn be used in paginating records. When no values for limit and skip query parameters are passed by the user, limit is set to a default of 30 and skip is also set to a default of 0. Limit cannot be greater that 100. The type
PaginationQuerycan help in intellisense.
This app interacts with a stateless http server. Authentication is realized by sending a JSON Web Token (By the way this is one of my favorite technologies) to the server. The steps for authenticating users are listed below.
When it is the first time the user is visiting the app or the returning user is not authenticated, React Router will redirect the user to the login page.
The User will either login or create a new account
The app sends the authentication information to the server
If the server successfully authenticates the user, a json web access token and its refresh token is created on the server and sent as an http only cookie to the client
By default the access token only lasts an hour. After this if the refresh token is still valid, the server will generate a new access and refresh tokens to the client
In subsequent requests, the app will send the access token stored in the cookies to the server to identify the user making the request.
If the token expires or becomes invalid the user will automatically be redirected to the login page. Thanks to the
If the user returning to the app is already authenticated react router will redirect the user to the main application page.
Authentication persistence through subdomains¶
Since this app allows users to create subdomains, it needs to persist
authentication through the main domain and subdomains. This is one of
the main reasons why cookies are been used. For cookies to persist
authentication through domains and subdomains, the main domain parameter
supplied while creating them must be valid. One of the rules for its
validity is that it must have at least one dot. Due to this, localhost
will not work. Read this
to learn more. Even though developers can still use localhost but if
another subdomain is visited, authentication would be required again.
Developers can therefore set a different domain other than localhost in
/etc/host ( or
windows) file. The domain recommended is octopus.localhost. This is
because it allows all subdomains to see the cookie as well. #
├── README.md ├── SOFTWARE-SPEC.md ├── appspec.yml ├── package-lock.json ├── package.json ├── scripts │ ├── after_install.sh │ ├── before_install.sh │ └── start.sh ├── server │ ├── README.md │ ├── dist │ ├── entities │ │ ├── Channel.entity.ts │ │ ├── Invitation.entity.ts │ │ ├── Post.entity.ts │ │ ├── User.entity.ts │ │ ├── UserChannel.entity.ts │ │ ├── UserChannelPermission.entity.ts │ │ ├── UserZone.entity.ts │ │ ├── UserZonePermission.entity.ts │ │ ├── Zone.entity.ts │ │ ├── base │ │ ├── data │ │ └── repositories │ ├── helpers │ │ ├── jwt.ts │ │ └── utils.ts │ ├── migrations │ │ └── 1625561314952-InitialMigration.ts │ ├── ormconfig.ts │ ├── src │ │ ├── app.module.ts │ │ ├── auth │ │ ├── mail │ │ ├── main.ts │ │ ├── typeorm-exception.filter.ts │ │ ├── utils │ │ ├── views │ │ └── zone │ ├── test │ │ ├── app.e2e-spec.d.ts │ │ ├── app.e2e-spec.js │ │ ├── app.e2e-spec.js.map │ │ ├── app.e2e-spec.ts │ │ └── jest-e2e.json │ ├── tsconfig.build.json │ ├── tsconfig.json │ ├── tsconfig.tsbuildinfo │ └── types │ ├── Post.ts │ ├── PaginationQuery.ts │ ├── UserPayloadRequest.ts │ └── UserZoneRequest.ts ├── src │ ├── App.tsx │ ├── assets │ │ ├── background.png │ │ └── logo.png │ ├── components │ │ ├── layouts │ │ └── utils │ ├── config ├──i18n │ └── [language].json │ │ ├── app-config.ts │ │ └── http.ts │ ├── helpers │ │ ├── history.ts │ │ ├── utils.ts │ │ └── validators.ts │ ├── hooks │ │ └── useTitle.ts │ ├── index.tsx │ ├── layers │ │ ├── meeting │ │ └── zone │ ├── models │ │ ├── form-submit-event.ts │ │ └── response-error.ts │ ├── pages │ │ ├── Private │ │ └── Public │ ├── react-app-env.d.ts │ ├── routes.ts │ ├── scss │ │ └── index.scss │ └── store │ ├── actions │ ├── constants │ ├── reducers │ ├── services │ ├── store.ts │ └── types └── tsconfig.json
This is the main readme file of the application
This is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.
Lists all the dependencies, author, version, etc of the app.
This is where the main index.html file that loads the react app lives.
This is where most backend work is done in this app.
Typescript compiles to this directory.
This is directory hosts all the typeorm model definitions. All typeorm entities must end with
This directory hosts the typeorm models that will be inherited by other models. For example the
RecordEntitydefines most of the repeating fields in records such as
This directory hosts the default data used by some entities.
This directory hosts all the utilities functions of the application.
This directory hosts all the migration scripts used by typeorm. To create a new migration please use the script
yarn migration:create. NestJS automatically runs all pending migrations when it is booted. While creating migrations, typeorm driver must be prefered to raw sql. This helps in migrating to other databases in the future.
This directory hosts all the utility typescript types used in the application.
This is the directory that hosts all end-to-end testing scripts.
This is the directory where most of the work is done. It hosts all the NestJS controllers, modules, services, pipes, guards, middlewares etc. Note that, scripts other than NestJS specific shouldn’t be put here.
The root module of the application. All other modules are imported into this file.
The entry file of the application which uses the core function NestFactory to create a Nest application instance.
This directory hosts the module used for sending mails in this application. To send a mail, a view is created inside the views directory. The
MailModuleis imported into the current module and the
MailServiceis injected into the current service. Using the
sendMailByViewmethod of the mail service emails can be sent using sendgrid.
The src directory hosts all the nestjs modules in this application. To create a new module, a new directory with the same name is created. It is recommended that the nest cli is used to generate modules, controllers, services etc. The nest cli command
nest g module [module_name]generates a new module. This creates a new directory inside the src folder and a new module named
[module_name].module.ts. All directories created inside this must not be empty.
All decorators for this module is created in this directory.
All dtos for this module is created in this directory. A DTO is an object that defines how the data will be sent over the network. This is especially useful in
PUTrequests. The class validator decorators can also help in validating payload fields. All dtos must end with
All pipes for this module is created in this directory. Pipes are used to transform input data coming from
req.paramsetc. All pipes must end with
All guards for this module is created in this directory. Guards determine whether a given request will be handled by the route handler or not, depending on certain conditions (like permissions, roles, ACLs, etc.) present at run-time. All guards must end with
All interfaces for this module is created in this directory. Note: All interface must be declared using
classbut not the
All exceptions for this module is created in this directory. Nest comes with a built-in exceptions layer which is responsible for processing all unhandled exceptions across an application. When an exception is not handled by your application code, it is caught by this layer, which then automatically sends an appropriate user-friendly response. All exceptions must end with
If multiple controllers are used in this module, it is recommended to put them in the controllers directory. Otherwise there is no need to create this directory for them. All controllers must end with
If multiple services are used in this module, it is recommended to put them in the services directory. Otherwise there is no need to create this directory for them. All services must end with
This is the file that all providers, controllers etc of this module are imported into. This is then imported into the
This is the file that contains all the configuration of the application’s database. It is used by typeorm to create migrations and connect to the database.
This is the file that contains the typescript configuration for the server. The configuration used in this app is in strict mode.
This is where most frontend work is done in this app.
This is the main component that loads the app routes and run initial scripts (eg. retrieving current user)
This directory contains all the static assests used in the app
This directory contains most of the helper components used in the app
This directory contains all the configuration files of the app
This directory contains all the utilities functions of the app
This directory contains all the general react hooks used in the app
This is the main script and starting point of the app responsible for bootstrapping the react app
This is the directory where layers (modals) used in the app are stored
This is the directory where typescript types used accross the entire app are declared.
This is the directory where pages served in the browser are stored
All Privates Pages are stored in this directory.
All Public Pages are stored in this directory.
This is a generated file coming with create react app
This is the file where all public and private routes are decalared. All public and private routes live in the publicRoutes and privateRoutes array respectively. Make sure you put the route in the correct context. All private routes require that users are authenticated, otherwise they will be redirected to the login page
The directory that hosts all the scss for the app
This is the directory that is used to handle everything to do with the app’s redux store.
All actions of the store are declared in this directory. Every action ends with
.action.ts. This is to make all actions easier to search. Also all action functions end with
All constants used in the store is declared in this directory. End all constants with
.constant.ts. This is to make all constants easier to search.
All reducers of the store are declared in this directory. Every reducer ends with
.reducer.ts. This is to make all reducers easier to search.
All services of the store are declared in this directory. Every service ends with
.service.ts. This is to make all services easier to search. The
httphelper function must be used to make http requests
This is the script that creates the main store of the app.
All typescript types of the stored are declared in this directory. Every type file ends with
.types.ts. This is to make all types easier to search.
This is the file that contains the typescript configuration for the app. The configuration used in this app is strict
Server run and build commands are included in this folder files for installing requirements and ci cd auto deployment.
file contains scripts files calls for ci cd auto deployment into aws instance