Skip to content

Commit 6586846

Browse files
fadymasfadymas
authored
Revise README with project details and setup guide
Updated README.md to include project description, setup instructions, technical decisions, and tech stack.
1 parent 5402872 commit 6586846

1 file changed

Lines changed: 167 additions & 20 deletions

File tree

‎README.md‎

Lines changed: 167 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,183 @@
1-
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
1+
# DevOverflow
22

3-
## Getting Started
3+
> A community-driven Q&A platform built for developers, by developers.
44
5-
First, run the development server:
5+
---
6+
7+
## 📖 Project Description
8+
9+
DevOverflow is a Q&A platform for developers where they can ask programming questions, share knowledge, and help each other solve technical problems. It is designed for programmers, students, and anyone learning or working in software development. Users can post questions with rich-text formatting, browse answers from the community, and get AI-assisted help — all in one place. The platform also features a reputation and badge system that rewards contributors based on their activity and impact, encouraging a healthy and engaged community.
10+
11+
---
12+
13+
## 🚀 Setup Instructions
14+
15+
Follow these steps to run DevOverflow locally.
16+
17+
### Prerequisites
18+
19+
- Node.js (v18 or higher)
20+
- npm or yarn
21+
- A MongoDB database (local or [MongoDB Atlas](https://www.mongodb.com/atlas))
22+
- A Google and GitHub OAuth app (for social login)
23+
- A Gmail account with an App Password enabled (for email sending)
24+
- A TinyMCE API key
25+
- A Gemini API key
26+
27+
### 1. Clone the repository
28+
29+
```bash
30+
git clone https://github.com/your-username/devoverflow.git
31+
cd devoverflow
32+
```
33+
34+
### 2. Install dependencies
35+
36+
```bash
37+
npm install
38+
```
39+
40+
### 3. Set up environment variables
41+
42+
Create a `.env.local` file in the root of the project and add the following:
43+
44+
```env
45+
# TinyMCE Editor
46+
NEXT_PUBLIC_TINY_EDITOR_API_KEY=your_tinymce_api_key
47+
48+
# MongoDB
49+
MONGODB_URL=mongodb+srv://your_user:[email protected]/devoverflow
50+
51+
# Better Auth
52+
BETTER_AUTH_SECRET=your_random_secret_string
53+
BETTER_AUTH_URL=http://localhost:3000 # Base URL of your app
54+
55+
# Google OAuth
56+
GOOGLE_CLIENT_ID=your_google_client_id
57+
GOOGLE_CLIENT_SECRET=your_google_client_secret
58+
59+
# GitHub OAuth
60+
GITHUB_CLIENT_ID=your_github_client_id
61+
GITHUB_CLIENT_SECRET=your_github_client_secret
62+
63+
# Email (Nodemailer via Gmail)
64+
[email protected]
65+
PASS=your_gmail_app_password # App password from Gmail account settings
66+
67+
# App URL
68+
NEXT_PUBLIC_SERVER_URL=http://localhost:3000
69+
70+
# Gemini AI
71+
GEMINI_API_KEY=your_gemini_api_key
72+
```
73+
74+
> **Note:** For Gmail, you need to enable 2-Step Verification and generate an App Password from your Google Account settings. Do not use your regular Gmail password.
75+
76+
### 4. Run the development server
677

778
```bash
879
npm run dev
9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
1580
```
1681

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
82+
The app will be running at [http://localhost:3000](http://localhost:3000).
83+
84+
---
85+
86+
## 🏗️ Architecture Overview
87+
88+
DevOverflow is a full-stack application built entirely within Next.js — there is no separate backend server.
89+
90+
```
91+
┌─────────────────────────────────────────────────┐
92+
│ Browser (Client) │
93+
│ - React components + Tailwind CSS + shadcn/ui │
94+
│ - Forms handled by React Hook Form + Zod │
95+
│ - TinyMCE rich text editor │
96+
│ - Better Auth client (login/session triggers) │
97+
└────────────────────┬────────────────────────────┘
98+
│
99+
▼
100+
┌─────────────────────────────────────────────────┐
101+
│ Next.js (Server Layer) │
102+
│ │
103+
│ Server Actions ──────────────► MongoDB │
104+
│ (CRUD operations, data logic) │
105+
│ │
106+
│ API Routes: │
107+
│ - /api/email ──────────────► Nodemailer │
108+
│ - /api/ai ──────────────► Gemini API │
109+
│ │
110+
│ Better Auth (server-side session validation) │
111+
└─────────────────────────────────────────────────┘
112+
```
113+
114+
**How it connects:**
115+
- The frontend triggers **Server Actions** for all database operations (fetching questions, posting answers, voting, etc.). No REST API is needed for these.
116+
- **API Routes** handle email sending via Nodemailer and AI requests via the Gemini API.
117+
- **Better Auth** handles authentication flows. Login and registration are triggered from the client, but session validation and access to protected data happen server-side.
118+
- All data is stored in **MongoDB**, taking advantage of its flexible document structure for nested data like questions, answers, tags, and comments.
119+
120+
---
121+
122+
## 🧠 Technical Decisions
123+
124+
### 1. MongoDB over a relational database
125+
Since DevOverflow is a Q&A platform, the data is naturally nested and flexible — questions have answers, answers have comments, and tags connect across many questions. MongoDB's document model made it straightforward to store and query this kind of data without the overhead of complex joins. Its scalability also makes it a strong fit for a growing community platform.
126+
127+
### 2. Better Auth over NextAuth
128+
Rather than reaching for the most popular solution, I chose Better Auth to deepen my understanding of how authentication actually works. This decision pushed me to learn about session management, email verification flows, and OAuth integrations at a lower level. The result was a stronger grasp of auth fundamentals rather than treating it as a black box.
129+
130+
### 3. Custom Badges & Reputation System
131+
Rather than using a third-party library, I built a custom badge and reputation system from scratch. Users earn Bronze, Silver, and Gold badges based on six tracked metrics: question count, answer count, question upvotes, answer upvotes, and total profile views. Each metric has tiered thresholds, and badges are recalculated automatically as a user's activity grows. Reputation points are also awarded for positive contributions, giving the community a clear signal of who the most helpful and active members are. Building this myself gave me full control over the logic and made it a natural fit within the existing MongoDB data model.
132+
133+
### 4. Next.js Server Actions over a traditional REST API
134+
Instead of building a separate API layer, I used Next.js Server Actions to handle all database logic. This keeps the codebase clean and organized — backend logic lives alongside the frontend but runs exclusively on the server. It also improves security since database credentials and operations are never exposed to the client.
135+
136+
---
137+
138+
## 📸 Screenshots
139+
140+
> Replace the placeholders below with actual screenshots of your app.
141+
142+
### Home Page
143+
<img width="1920" height="1312" alt="image" src="https://github.com/user-attachments/assets/665d4bed-e13e-45db-bae5-6f9d9b709e72" />
144+
145+
*Browse the latest questions from the community*
146+
147+
### Question Detail Page
148+
<img width="1920" height="1693" alt="image" src="https://github.com/user-attachments/assets/ececdfed-2270-461e-975e-54ef7322f08d" />
149+
*View a question, read answers, and contribute your own*
18150

19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
151+
### Ask a Question
152+
<img width="1920" height="1375" alt="image" src="https://github.com/user-attachments/assets/b8de2c2d-3bf8-47b4-8ddb-7605a1db867d" />
153+
*Rich text editor powered by TinyMCE for writing detailed questions*
20154

21-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
155+
### User Profile
156+
<img width="1920" height="1461" alt="image" src="https://github.com/user-attachments/assets/157db376-ac22-42d8-a66f-85a9d87c7545" />
157+
*Track your questions, answers, and reputation*
22158

23-
## Learn More
159+
### Mobile View
160+
<img width="443" height="2466" alt="image" src="https://github.com/user-attachments/assets/7501afae-5549-4f3b-8e65-a8ea0adddca7" />
161+
*Fully responsive design across all screen sizes*
24162

25-
To learn more about Next.js, take a look at the following resources:
163+
---
26164

27-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
165+
## 🛠️ Tech Stack
29166

30-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
167+
| Layer | Technology |
168+
|---|---|
169+
| Framework | Next.js (App Router) |
170+
| Language | TypeScript |
171+
| Styling | Tailwind CSS + shadcn/ui |
172+
| Forms | React Hook Form + Zod |
173+
| Rich Text Editor | TinyMCE |
174+
| Database | MongoDB |
175+
| Authentication | Better Auth |
176+
| Email | Nodemailer (Gmail) |
177+
| AI | Google Gemini API |
31178

32-
## Deploy on Vercel
179+
---
33180

34-
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
181+
## 📄 License
35182

36-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
183+
This project is open source and available under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)