Skip to content

Commit e21d95e

Browse files
rootcode-creatorrootcode-creator
committed
fix(README): overhaul project documentation for clarity and completeness
1 parent 6f9466e commit e21d95e

File tree

1 file changed

+229
-19
lines changed

1 file changed

+229
-19
lines changed

‎README.md‎

Lines changed: 229 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,245 @@
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+
# match-me — README
22

3-
## Getting Started
3+
Modern full-stack matchmaking application built with Next.js App Router, Prisma, PostgreSQL, NextAuth v5, and real-time messaging/notifications with Pusher.
44

5-
First, run the development server:
5+
## Table of Contents
6+
7+
- [🚀 Project intro](#-project-intro)
8+
- [📁 Project structure](#-project-structure)
9+
- [⭐ Differentiators](#-differentiators)
10+
- [🔧 Features](#-features)
11+
- [🧰 Tech stack](#-tech-stack)
12+
- [⚙️ Install methods](#️-install-methods)
13+
- [📦 npm / Node](#-npm--node)
14+
- [🔐 Environment variables](#-environment-variables)
15+
- [🗄️ Database structure](#️-database-structure)
16+
- [📜 Available scripts](#-available-scripts)
17+
- [🚀 Deployment notes](#-deployment-notes)
18+
- [🤝 Contributing](#-contributing)
19+
- [📄 License](#-license)
20+
21+
## 🚀 Project intro
22+
23+
`match-me` is a role-aware matchmaking platform with:
24+
25+
- Email/password + social authentication (Google/GitHub)
26+
- Profile onboarding and completion flow
27+
- Member discovery with filters/pagination
28+
- Likes (including mutual likes)
29+
- Real-time chat and real-time notifications
30+
- Admin photo moderation
31+
32+
It is designed as an MVP-friendly production-ready foundation for social/match applications.
33+
34+
## 📁 Project structure
35+
36+
```txt
37+
match-me/
38+
├── prisma/
39+
│ ├── schema.prisma
40+
│ ├── seed.ts
41+
│ └── migrations/
42+
├── public/
43+
│ └── images/
44+
├── scripts/
45+
│ ├── checkCounts.js
46+
│ └── with-db-env.mjs
47+
├── src/
48+
│ ├── app/
49+
│ │ ├── (auth)/ # login/register/verify/reset/profile-complete
50+
│ │ ├── actions/ # server actions (auth/member/like/message/admin)
51+
│ │ ├── admin/moderation/
52+
│ │ ├── api/ # auth, health, pusher-auth, sign-image
53+
│ │ ├── lists/
54+
│ │ ├── members/
55+
│ │ └── messages/
56+
│ ├── components/
57+
│ ├── hooks/
58+
│ ├── lib/
59+
│ ├── auth.ts
60+
│ ├── auth.config.ts
61+
│ ├── middleware.ts
62+
│ └── routes.ts
63+
├── package.json
64+
└── README.md
65+
```
66+
67+
## ⭐ Differentiators
68+
69+
- Server Actions first approach for core domain operations
70+
- Auth.js + Prisma adapter with role and profile-completion-aware middleware guards
71+
- Real-time UX via Pusher (chat updates, likes, presence-style notifications)
72+
- Practical Neon/Vercel database env fallback handling (`DATABASE_URL`/`DIRECT_URL` auto-resolution)
73+
- Admin moderation workflow for uploaded photos
74+
75+
## 🔧 Features
76+
77+
### Core features
78+
79+
| Feature | Status | Notes |
80+
| --- | --- | --- |
81+
| Credentials auth | ✅ Current | Register, login, email verification, password reset |
82+
| Social auth | ✅ Current | Google + GitHub providers (optional via env vars) |
83+
| Profile completion flow | ✅ Current | OAuth users are redirected until profile is completed |
84+
| Member browsing | ✅ Current | Filter by age/gender/photo + pagination |
85+
| Likes & lists | ✅ Current | Source likes, target likes, mutual likes |
86+
| Messaging | ✅ Current | Real-time thread updates + inbox/outbox view |
87+
| Photo uploads | ✅ Current | Cloudinary upload + signed API route |
88+
| Admin moderation | ✅ Current | Approve/reject pending photos |
89+
| Health endpoint | ✅ Current | DB connectivity check (`/api/health/db`) |
90+
91+
### Route protection behavior
92+
93+
- Public route: `/`
94+
- Auth routes: `/login`, `/register`, `/register/success`, `/verify-email`, `/forgot-password`, `/reset-password`
95+
- All other app routes require authentication
96+
- `/admin/*` routes require `ADMIN` role
97+
- OAuth users with incomplete profile are redirected to `/profile-complete`
98+
99+
## 🧰 Tech stack
100+
101+
- **Framework:** Next.js 16 (App Router), React 19, TypeScript
102+
- **Auth:** NextAuth/Auth.js v5 + Prisma Adapter
103+
- **Database:** PostgreSQL + Prisma ORM
104+
- **UI:** HeroUI + Tailwind CSS 4
105+
- **Forms/Validation:** React Hook Form + Zod
106+
- **Realtime:** Pusher + pusher-js
107+
- **Media:** Cloudinary + next-cloudinary
108+
- **Email:** Resend
109+
110+
## ⚙️ Install methods
111+
112+
### 📦 npm / Node
113+
114+
Prerequisites:
115+
116+
- Node.js 20+
117+
- PostgreSQL database (local or hosted, e.g. Neon)
118+
119+
```bash
120+
git clone <your-repo-url> match-me
121+
cd match-me
122+
npm install
123+
```
124+
125+
1) Create your `.env` file (see [Environment variables](#-environment-variables)).
126+
127+
2) Apply migrations:
128+
129+
```bash
130+
npx prisma migrate dev
131+
```
132+
133+
3) Seed sample data:
6134

7135
```bash
136+
npx prisma db seed
137+
```
8138

9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
139+
4) Start development server:
140+
141+
```bash
142+
npm run dev
15143
```
16144

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
145+
Open `http://localhost:3000`.
146+
147+
## 🔐 Environment variables
148+
149+
Create a `.env` in project root:
150+
151+
```env
152+
# Database (minimum)
153+
DATABASE_URL="postgresql://..."
154+
DIRECT_URL="postgresql://..."
155+
156+
# Optional DB fallbacks supported by this repo
157+
POSTGRES_PRISMA_URL=""
158+
POSTGRES_URL=""
159+
POSTGRES_URL_NON_POOLING=""
160+
NEON_DATABASE_URL=""
161+
NEON_POSTGRES_URL=""
162+
163+
# Auth.js / NextAuth
164+
AUTH_SECRET="your-random-secret"
165+
NEXTAUTH_URL="http://localhost:3000"
166+
167+
# Credentials email flows
168+
RESEND_API_KEY=""
169+
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
170+
171+
# Optional social providers
172+
GOOGLE_CLIENT_ID=""
173+
GOOGLE_CLIENT_SECRET=""
174+
GITHUB_CLIENT_ID=""
175+
GITHUB_CLIENT_SECRET=""
176+
177+
# Cloudinary (upload + signature)
178+
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=""
179+
NEXT_PUBLIC_CLOUDINARY_API_KEY=""
180+
CLOUDINARY_API_SECRET=""
18181
19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
182+
# Pusher (real-time)
183+
PUSHER_APP_ID=""
184+
NEXT_PUBLIC_PUSHER_APP_KEY=""
185+
PUSHER_APP_SECRET=""
186+
187+
# Optional diagnostics
188+
DEBUG_ERRORS="false"
189+
```
190+
191+
Notes:
192+
193+
- `src/lib/prisma.ts` and `scripts/with-db-env.mjs` auto-map several Vercel/Neon env names into `DATABASE_URL` and `DIRECT_URL`.
194+
- If Pusher env vars are missing, real-time features will fail where server/client instances are required.
195+
196+
## 🗄️ Database structure
197+
198+
Prisma models in this repo:
199+
200+
- `User` (role, profile completion, auth data)
201+
- `Member` (public profile, demographic details)
202+
- `Photo` (member media + moderation state)
203+
- `Like` (source/target relation; composite PK)
204+
- `Message` (thread messages with soft-delete flags)
205+
- `Token` (email verification + password reset tokens)
206+
- `Account` (OAuth account linkage)
207+
208+
Enums:
209+
210+
- `Role`: `ADMIN`, `MEMBER`
211+
- `TokenType`: `VERIFICATION`, `PASSWORD_RESET`
212+
213+
## 📜 Available scripts
214+
215+
```bash
216+
npm run dev # start dev server
217+
npm run build # production build
218+
npm run start # run production server
219+
npm run lint # lint project
220+
npm run vercel-build # prisma generate + migrate deploy + seed + build
221+
```
20222

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.
223+
Utility scripts:
22224

23-
## Learn More
225+
- `node scripts/checkCounts.js` — quick sanity counts for `User` and `Member`
226+
- `node scripts/with-db-env.mjs <command>` — run command with DB env fallbacks resolved
24227

228+
## 🚀 Deployment notes
25229

26-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
27-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
230+
- The `vercel-build` script is configured for deploy-time Prisma generation, migration, seeding, and Next.js build.
231+
- Seed creates demo users and an admin account:
232+
- Admin email: `admin@test.com`
233+
- Default seed password: `password`
234+
- Rotate seed credentials and production secrets before public deployment.
28235

29-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
236+
## 🤝 Contributing
30237

31-
## Deploy on Vercel
238+
- Fork the repository and create a feature branch.
239+
- Keep pull requests focused and include verification steps.
240+
- Never commit secrets or real credentials.
32241

33-
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.
242+
## 📄 License
34243

35-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
244+
No license file is currently present in this repository.
245+
If you want this project open-source, add a `LICENSE` file (for example MIT).

0 commit comments

Comments
 (0)