Skip to content

Commit 07edba7

Browse files
junaiddshaukatjunaiddshaukat
committed
contributing guidelines
1 parent 7169372 commit 07edba7

3 files changed

Lines changed: 357 additions & 19 deletions

File tree

‎.env.example‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
NEXT_PUBLIC_GA_ID=
2+
CLOUDINARY_CLOUD_NAME=
3+
CLOUDINARY_API_KEY=
4+
CLOUDINARY_API_SECRET=
5+
JWT_SECRET=
6+
NODE_ENV=production
7+
ADMIN_ACCESS_CODE=devweekends
8+
MENTOR_ACCESS_CODE=devweekends
9+
AMBASSADOR_ACCESS_CODE=devweekends
10+
MONGODB_URI=

‎CONTRIBUTING.md‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
## Contributing to Dev Weekends Web Platform
2+
3+
Thank you for your interest in contributing to the **Dev Weekends** web platform!
4+
This project powers the public site and internal portals (admin, mentors, ambassadors, mentees) for the Dev Weekends community.
5+
6+
This document explains how the project is structured, how to run it locally, and the conventions to follow when you open a PR.
7+
8+
---
9+
10+
## Project Overview & Structure
11+
12+
This is a **Next.js 15** application using the **App Router**, **TypeScript**, **Tailwind CSS**, and **MongoDB (via Mongoose)**.
13+
14+
High‑level layout:
15+
16+
- **`app/`**: Next.js App Router structure.
17+
- **`app/page.tsx`**: Landing page.
18+
- **`app/about`, `app/community`, `app/fellowship`, `app/mentorship`, `app/resources`, `app/sessions`, `app/mindmaster`, etc.**: Public marketing and community pages.
19+
- **`app/admin/*`**: Admin dashboard (mentors, mentees, tags, tasks, sessions, resources, activity log, etc.).
20+
- **`app/ambassador/*` & `app/mentor/*`**: Ambassador and mentor portals (login, dashboards, mentees management, etc.).
21+
- **`app/api/*`**: API routes for authentication, mentors/mentees, sessions, resources, tags, tasks, file uploads, etc.
22+
- **`app/layout.tsx`**: Root layout, global metadata/SEO, theme provider, navbar/footer, analytics, and social modal.
23+
- **`components/`**: Reusable UI and domain components.
24+
- **Top‑level components** such as `navbar`, `footer`, `analytics`, `MentorshipGraph`, `MentorsPage`, `TagAssignment`, `google_calender`, etc.
25+
- **`components/ui/`**: Primitive UI building blocks (buttons, inputs, dialogs, tabs, badges, etc.), largely based on Radix UI + Tailwind.
26+
- **`lib/`**:
27+
- **`db.ts`**: MongoDB connection helper (Mongoose) with connection caching and model preloading.
28+
- **`auth.ts`, `jwt.ts`**: Authentication and JWT helpers.
29+
- **`analytics.ts`, `resources-*.ts`, `utils.ts`**: Misc. shared utilities and data.
30+
- **`models/`**: Mongoose models such as `Admin`, `Mentor`, `Mentee`, `Ambassador`, `CoreTeamMember`, `ActivityLog`, `Session`, `Resource`, `Tag`, `Task`, `MindMaster`, etc.
31+
- **`public/`**: Static assets (images, icons, manifest, favicons).
32+
- **`styles & config`**:
33+
- **`app/globals.css`**: Global styles and Tailwind layers.
34+
- **`tailwind.config.ts`**, **`postcss.config.mjs`**: Tailwind/PostCSS configuration.
35+
- **`tsconfig.json`**: TypeScript configuration with `@/*` alias to the project root.
36+
- **`next.config.*`**: Next.js configuration.
37+
38+
If you’re adding a new page, it should usually go under `app/`. For reusable UI, prefer `components/` (or `components/ui/` for primitives).
39+
40+
---
41+
42+
## Prerequisites
43+
44+
- **Node.js**: Use a recent LTS version (e.g. Node 20+ recommended).
45+
- **Package manager**: `npm` (repo includes a `package-lock.json`), but `yarn`, `pnpm`, or `bun` can also work if you prefer.
46+
- **MongoDB**: Access to a MongoDB instance (local or hosted).
47+
48+
Global tools like `git` and a code editor with TypeScript support (VS Code, etc.) are strongly recommended.
49+
50+
---
51+
52+
## Environment Setup
53+
54+
1. **Clone the repository**
55+
56+
```bash
57+
git clone <your-fork-or-origin-url>
58+
cd web-platform
59+
```
60+
61+
2. **Install dependencies**
62+
63+
```bash
64+
npm install
65+
```
66+
67+
3. **Configure environment variables**
68+
69+
- Create a `.env.local` file at the project root.
70+
- Use `.env.example` (if present in the repo) as a reference for required variables.
71+
- At minimum, you will need:
72+
- `MONGODB_URI` – MongoDB connection string (required by `lib/db.ts`).
73+
- Any analytics / auth / third‑party keys used in layout or API routes (for example `NEXT_PUBLIC_GA_ID` as referenced in `app/layout.tsx`).
74+
75+
4. **Run database locally or connect to a remote cluster**
76+
77+
- If running MongoDB locally, ensure it is started before you run the app.
78+
- If using a hosted solution (e.g. MongoDB Atlas), ensure your `MONGODB_URI` is correct and IP‑whitelisted.
79+
80+
---
81+
82+
## Running the Project
83+
84+
From the project root:
85+
86+
- **Development server**
87+
88+
```bash
89+
npm run dev
90+
```
91+
92+
Open `http://localhost:3000` in your browser.
93+
94+
- **Production build**
95+
96+
```bash
97+
npm run build
98+
npm start
99+
```
100+
101+
- **Linting**
102+
103+
```bash
104+
npm run lint
105+
```
106+
107+
Please make sure your code passes `npm run lint` before pushing or opening a PR.
108+
109+
---
110+
111+
## Coding Guidelines
112+
113+
- **Language & framework**
114+
- Use **TypeScript** for new code (`.ts` / `.tsx`).
115+
- Follow **Next.js App Router** conventions (server components by default, client components only when needed).
116+
- Prefer **server actions / API routes** for backend logic instead of calling the database from the client.
117+
118+
- **Project structure**
119+
- Place **pages and route handlers** under `app/`.
120+
- Place **shared UI components** under `components/` (or `components/ui/` for primitives).
121+
- Place **business logic & helpers** under `lib/` (auth, DB helpers, utilities).
122+
- Define or reuse **Mongoose models** under `models/` and ensure you use the shared `connectDB` helper from `lib/db.ts`.
123+
124+
- **Styling**
125+
- Use **Tailwind CSS** and existing utility classes.
126+
- Prefer existing utility and component patterns for consistency.
127+
128+
- **TypeScript & strictness**
129+
- The project uses **`strict`** TypeScript.
130+
- Avoid `any` wherever possible; define proper types or interfaces.
131+
- Keep props and return types explicit for exported functions and components.
132+
133+
- **Imports & paths**
134+
- Use the `@/*` path alias when importing from within this repo:
135+
136+
```ts
137+
import Navbar from "@/components/navbar"
138+
import connectDB from "@/lib/db"
139+
```
140+
141+
- **API & models**
142+
- Reuse existing patterns in `app/api/*/route.ts` for:
143+
- Connecting to the database with `connectDB`.
144+
- Handling errors and returning `NextResponse`.
145+
- Using centralized models from `models/`.
146+
147+
---
148+
149+
## Git & Branching Workflow
150+
151+
1. **Fork or branch**
152+
- If you are an external contributor: fork the repository, then create a feature branch from `main`.
153+
- If you are in the core team: create a branch from `main`.
154+
155+
2. **Create a descriptive branch name**
156+
157+
Examples:
158+
159+
- `feature/add-mentor-dashboard-filtering`
160+
- `fix/ambassador-login-redirect`
161+
- `chore/update-tailwind-config`
162+
163+
3. **Make focused commits**
164+
165+
- Keep commits small and focused on a single concern.
166+
- Use clear, descriptive commit messages (e.g. “Fix mentor session filtering bug” rather than “fix stuff”).
167+
168+
4. **Keep your branch up to date**
169+
170+
- Regularly pull from `main` and rebase or merge as appropriate to avoid large drift.
171+
172+
---
173+
174+
## Pull Request Guidelines
175+
176+
Before opening a PR, please ensure:
177+
178+
- **Build & lint pass**
179+
- `npm run build`
180+
- `npm run lint`
181+
182+
- **Scope is clear**
183+
- The PR addresses a single feature, fix, or refactor.
184+
- Large refactors should be split into smaller PRs where possible.
185+
186+
- **Description**
187+
- Clearly describe:
188+
- What you changed.
189+
- Why you changed it.
190+
- How to test it (steps, relevant pages, and any required env variables).
191+
192+
- **Screenshots / GIFs (recommended)**
193+
- For UI changes, include before/after screenshots or GIFs in the PR description.
194+
195+
- **No sensitive data**
196+
- Make sure no secrets, tokens, or private data are committed.
197+
198+
---
199+
200+
## Adding or Updating API Routes
201+
202+
If you introduce or modify an API route under `app/api/`:
203+
204+
- Use `connectDB` from `lib/db.ts` for any database access.
205+
- Reuse existing response patterns and status codes from similar routes.
206+
- Validate input payloads to avoid runtime errors.
207+
- Ensure authentication/authorization is respected for admin/mentor/ambassador endpoints.
208+
209+
---
210+
211+
## Adding or Updating UI Pages/Components
212+
213+
- Follow existing layout and design patterns (Tailwind + existing components).
214+
- Prefer composition over duplication: extract shared parts into reusable components under `components/`.
215+
- Make sure pages are responsive (mobile‑first) and accessible where possible (ARIA attributes, semantic HTML, keyboard navigation, etc.).
216+
217+
---
218+
219+
## Questions & Support
220+
221+
If you’re unsure about where to place code, how to name something, or what pattern to follow:
222+
223+
- Look for similar existing pages/components/routes and mirror their approach.
224+
- If you’re contributing as part of the Dev Weekends community, reach out to the maintainers or core team in the relevant communication channel.
225+
226+
We appreciate every contribution that helps improve the platform for learners, mentors, and ambassadors. 🚀
227+
228+

‎README.md‎

Lines changed: 119 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,136 @@
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+
## Dev Weekends Web Platform
2+
3+
This repository contains the **Dev Weekends** web platform – the public site and internal portals (admin, mentors, ambassadors, mentees) for the Dev Weekends community.
4+
5+
It is built with **Next.js 15 (App Router)**, **React 19**, **TypeScript**, **Tailwind CSS**, and **MongoDB via Mongoose**.
6+
7+
---
8+
9+
## Tech Stack
10+
11+
- **Framework**: Next.js (App Router)
12+
- **Language**: TypeScript
13+
- **UI**: React, Tailwind CSS, Radix‑based UI components
14+
- **Database**: MongoDB (via Mongoose)
15+
- **Auth / Tokens**: Custom auth using JWT
16+
- **Other**: Google Analytics, Cloudinary for media, role‑based access for Admin / Mentor / Ambassador
17+
18+
---
219

320
## Getting Started
421

5-
First, run the development server:
22+
### 1. Prerequisites
23+
24+
- Node.js (LTS, e.g. 20+ recommended)
25+
- npm (or another package manager; this repo ships with `package-lock.json`)
26+
- Access to a MongoDB instance (local or hosted)
27+
28+
### 2. Install dependencies
29+
30+
```bash
31+
npm install
32+
```
33+
34+
### 3. Environment variables
35+
36+
Create a `.env.local` file in the project root.
37+
Use `.env.example` as a reference – it includes all the required keys, for example:
38+
39+
```bash
40+
NEXT_PUBLIC_GA_ID=
41+
42+
CLOUDINARY_CLOUD_NAME=
43+
CLOUDINARY_API_KEY=
44+
CLOUDINARY_API_SECRET=
45+
46+
JWT_SECRET=
47+
48+
NODE_ENV=production
49+
50+
ADMIN_ACCESS_CODE=devweekends
51+
MENTOR_ACCESS_CODE=devweekends
52+
AMBASSADOR_ACCESS_CODE=devweekends
53+
54+
MONGODB_URI=
55+
```
56+
57+
> **Note**: Do **not** commit your real `.env.local` or any secrets.
58+
59+
### 4. Run the development server
660

761
```bash
862
npm run dev
9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
1563
```
1664

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
65+
Then open `http://localhost:3000` in your browser.
66+
67+
For a production build:
68+
69+
```bash
70+
npm run build
71+
npm start
72+
```
73+
74+
To run linting:
75+
76+
```bash
77+
npm run lint
78+
```
79+
80+
---
81+
82+
## Project Structure
83+
84+
High‑level overview of important directories:
85+
86+
- **`app/`** – Next.js App Router structure.
87+
- Public pages such as `page.tsx`, `about`, `community`, `fellowship`, `mentorship`, `resources`, `sessions`, `mindmaster`, etc.
88+
- Authenticated portals under `admin`, `ambassador`, and `mentor` for dashboards, mentees, tags, tasks, sessions, and resources.
89+
- API routes under `app/api/*` for auth, mentors/mentees, ambassadors, sessions, tags, resources, tasks, uploads, etc.
90+
- `app/layout.tsx` sets global metadata/SEO, theme, navbar/footer, analytics, and social modal.
91+
- **`components/`** – Reusable React components, including:
92+
- Site‑wide components like navbar, footer, analytics, MentorshipGraph, MentorsPage, TagAssignment, Google calendar integration, etc.
93+
- `components/ui/` contains primitive UI components (buttons, inputs, dialogs, tabs, etc.).
94+
- **`lib/`** – Shared logic/utilities:
95+
- `db.ts` (MongoDB connection via Mongoose with connection caching),
96+
- `auth.ts`, `jwt.ts` for authentication and token helpers,
97+
- Analytics helpers, resources data, and general utilities.
98+
- **`models/`** – Mongoose models for Admin, Mentor, Mentee, Ambassador, CoreTeamMember, ActivityLog, Session, Resource, Tag, Task, MindMaster, etc.
99+
- **`public/`** – Static assets (images, icons, manifest, favicons).
100+
- **Config** – `tsconfig.json`, `tailwind.config.ts`, `postcss.config.mjs`, `next.config.*`, etc.
101+
102+
---
103+
104+
## Development Notes
105+
106+
- The project uses **strict TypeScript** – prefer strongly‑typed code and avoid `any` when possible.
107+
- Use the `@/*` path alias for imports within the repo (configured in `tsconfig.json`), for example:
108+
109+
```ts
110+
import Navbar from "@/components/navbar"
111+
import connectDB from "@/lib/db"
112+
```
18113

19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
114+
- Database access should use the shared `connectDB` helper from `lib/db.ts` and the centralized Mongoose models in `models/`.
115+
- New features should follow existing patterns in pages/components/API routes whenever possible.
20116

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.
117+
---
22118

23-
## Learn More
119+
## Contributing
24120

25-
To learn more about Next.js, take a look at the following resources:
121+
Contributions are welcome from the Dev Weekends community and beyond.
26122

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.
123+
- Please read **`CONTRIBUTING.md`** for:
124+
- Development environment setup,
125+
- Coding standards and project structure,
126+
- Branching / PR workflow,
127+
- How to add or modify pages, components, and API routes.
29128

30-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
129+
If you’re unsure how or where to implement a change, open an issue or discuss it with the maintainers before starting work.
31130

32-
## Deploy on Vercel
131+
---
33132

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.
133+
## License
35134

36-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
135+
Unless otherwise specified by the maintainers, this project is proprietary to **Dev Weekends**.
136+
Please contact the core team if you’d like to use or redistribute any part of this codebase.

0 commit comments

Comments
 (0)