Skip to content

Commit 9ec664d

Browse files
maxralph1maxralph1
committed
updated README.md
1 parent cdadf7f commit 9ec664d

File tree

132 files changed

+19942
-1219
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

132 files changed

+19942
-1219
lines changed

‎README.md

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Frends Social Media Application 
2+
3+
Guide to (usage and description of) the Frends social media application.
4+
5+
**Table of Contents**
6+
7+
1. [What Frends Is](#what-is-frends)
8+
2. [Features of the application](#features-of-the-application)
9+
3. [Technical Features of the Application](#technical-features-of-the-application)
10+
4. [Technologies Utilized in Crafting Frends](#technologies-utilized-in-crafting-frends)
11+
1. [Server-side](#server-side)
12+
2. [Client-side](#client-side)
13+
5. [API Documentation](#api-documentation)
14+
6. [Database Structure](#database-structure)
15+
7. [How to Install and Run the Frends Application Locally On Your Device](#how-to-install-and-run-the-frends-application-locally-on-your-device)
16+
1. [Requirements](#requirements)
17+
2. [Installation Procedure](#installation-procedure)
18+
1. [Server-side Terminal](#server-side-terminal)
19+
2. [Client-side Terminal](#client-side-terminal)
20+
8. [How to Generate Keys for your Environment Variable (.env) File](#how-to-generate-keys-for-your-environment-variable-env-file)
21+
9. [Footnotes !important](#footnotes-important)
22+
23+
## What Is Frends?
24+
25+
Frends is a social media application where users can make friends, find/search their old friends, and keep in touch with current friends.
26+
27+
(gif image showing working application comes here)
28+
29+
## Features of the application
30+
31+
The app has general feeds page, profile page, and several other pages.
32+
33+
1. There are 3 roles: individual, business and admin.
34+
2. A user can choose to register as an individual or business.
35+
3. Users can add and remove friends. They can also follow and unfollow other people/businesses.
36+
4. Logged in users / public can search for people.
37+
5. Logged in users can add posts (with/without images), comment on posts, like posts, like comments, delete comments. They can also comment on other users' profiles.
38+
39+
[Click for more details on other features and admin functions](https://nodejs.org/).
40+
41+
## Technical Features of the Application
42+
43+
1. Authentication
44+
2. Authorization (multiple roles)
45+
3. JWT tokens (access and refresh tokens)
46+
4. Rotating refresh tokens
47+
5. Registration link (via email) verification on registration
48+
6. Soft-delete function so that data is never really lost (all deleted data can be retrieved/re-activated)
49+
7. Image upload to the cloud (cloudinary)
50+
8. All incoming requests are validated multiple times on both client side and server-side.
51+
9. Detailed custom logs using morgan.
52+
10. API requests rate-limiting to prevent attacks.
53+
11. Other security measures in place to prevent attacks.
54+
12. Multiple error handlers (for both planned and unplanned errors) to catch all errors properly.
55+
13. Plus much more...
56+
57+
## Technologies Utilized in Crafting Frends
58+
59+
Frends is crafted in the following programming languages/frameworks and technologies:
60+
61+
### **Server-side:**
62+
63+
1. **Express.JS (Node.JS)** on the server-side.
64+
65+
1. **Jest** (for writing tests for the application)
66+
2. **Joi** was used for additional server-side form validation.
67+
3. **ApiDoc** for generating the API Documentation.
68+
69+
2. **MongoDB** (for database).
70+
1. **Mongoose** (for communicating with the MongoDB database)
71+
3. **Cloudinary** (for cloud file/image storage).
72+
4. **Nodemailer** (for email notifications).
73+
74+
### **Client-side:**
75+
76+
1. **React.JS (JavaScript)** library on the client-side
77+
2. **Tailwind CSS** for styling
78+
3. Vanilla **CSS3** for custom styling.
79+
80+
## API Documentation 
81+
82+
Here is a link to the API documentation: https://frends-api-documentation.vercel.app/
83+
84+
## Database Structure
85+
86+
![image for the database structure of Frends](./frends_database_schema.png)
87+
88+
## How to Install and Run the Frends Application Locally On Your Device
89+
90+
### Requirements:
91+
92+
1. You must have Node.JS installed on your device. Visit the [official Node.JS website](https://nodejs.org/) and follow the steps for download and installation. Preferably, go for the LTS version amongst the two options.
93+
2. After installing Node.JS, download and install a text editor (e.g. [VS Code](https://code.visualstudio.com/Download)) if you do not have one.
94+
95+
### Installation procedure:
96+
97+
Then go to your terminal and follow these steps:
98+
99+
1. From your terminal, cd (change directory) into your favorite directory (folder) where you would like to have the application files
100+
101+
```
102+
cd C:\Users\maxim\Desktop>
103+
```
104+
105+
Here I changed directory into my personal Desktop space/folder on my Windows Computer. And then;
106+
107+
2. Clone this repository from here on Github using either of the 2 commands on your terminal:
108+
109+
```
110+
git clone https://github.com/maxralph1/frends.git
111+
```
112+
113+
or
114+
115+
```
116+
git clone git@github.com:maxralph1/frends.git
117+
```
118+
119+
3. And to end this section, CD into the newly installed "Frends" application file with the following commands.
120+
121+
```
122+
cd frends
123+
```
124+
125+
At this point, you must have 2 terminals running (server-side (to run to server side code)  and client-side (to consume the server-side API)).
126+
127+
#### Server-side Terminal 
128+
129+
1. On the first terminal, change directory into the server file
130+
131+
```
132+
cd server
133+
```
134+
135+
2. From here, use the command below to install all dependencies I utilized in this application as can be seen from my 'server/package.json' file
136+
137+
```
138+
npm i
139+
```
140+
141+
3. Spin up the server with the command:
142+
143+
```
144+
npm run devstart
145+
```
146+
147+
#### Client-side Terminal
148+
149+
1. On the second terminal, change directory into the server file
150+
151+
```
152+
cd client
153+
```
154+
155+
2. Use the command below to install all dependencies I utilized in this application as can be seen from my 'client/package.json' file
156+
157+
```
158+
npm i
159+
```
160+
161+
3. Spin up the client-side (front-end) to consume the back-end API using the following command:
162+
163+
```
164+
npm run dev
165+
```
166+
167+
Your application should be up on http://localhost:5173/ if you have nothing previously running on the port. Check your terminal to confirm the actual port.
168+
169+
## How to Generate Keys for your Environment Variable (.env) File
170+
171+
Rename the "server/env.example" to "/server/.env" or create the new file. 
172+
Below are the steps you could take to populate the "/server/.env" file variables.
173+
174+
### NODE_ENVLeave this as the default, "development" or "production" 
175+
176+
### DATABASE_URI
177+
178+
This is the database connection key from Mongo DB. Go to the [official MongoDB website](https://www.mongodb.com/) and either use the Atlas or have it downloaded locally.
179+
180+
You may also wish to use another database provider. But you must modify the MongoDB database connection logic. 
181+
For ease, stick with MongoDB.
182+
183+
### ACCESS_TOKEN_SECRET, REFRESH_TOKEN_SECRET, EMAIL_VERIFY_TOKEN_SECRET, PASSWORD_RESET_TOKEN_SECRET
184+
185+
Provide random string or use any token generation library. I used Node's Crypto library from a node command line like so:
186+
187+
```
188+
require('crypto').randomBytes(64).toString('hex')
189+
```
190+
191+
### EMAIL_ADDRESS, EMAIL_PASSWORD 
192+
193+
### HOST, SERVICE, USER, PASS
194+
195+
These are for production. This is enabled when you are on "production". You can use GMail service for mail notifications to populate the fields.
196+
197+
### PORT, BASE_URL
198+
199+
The port on development or URL on production.
200+
201+
## Footnotes !important
202+
203+
This application is strictly for demonstration purposes. It is not yet production-ready and should never be used as such.
204+
205+
I will continue to gradually update this project in my free time.
206+
207+
\*\*On the general pattern of coding, if you noticed, the entire application has a specific approach in structure. I however decided to deviate (bring in several flavors) a little (but paid attention not to deviate too much) from these principles so as to showcase my skills. In a real-world application, I would stick to a particular pattern.
208+
209+
Finally, contributions/suggestions on how to improve this project, are welcome .

‎client/.eslintrc.cjs

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
module.exports = {
2+
env: { browser: true, es2020: true },
3+
extends: [
4+
'eslint:recommended',
5+
'plugin:react/recommended',
6+
'plugin:react/jsx-runtime',
7+
'plugin:react-hooks/recommended',
8+
],
9+
parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
10+
settings: { react: { version: '18.2' } },
11+
plugins: ['react-refresh'],
12+
rules: {
13+
'react-refresh/only-export-components': 'warn',
14+
},
15+
}

0 commit comments

Comments
 (0)