💞 Velora

Version 5.1 — Because love, too, can be engineered.

Velora is a full-stack matchmaking and real-time social interaction platform built with Next.js, Express.js, PostgreSQL, and Nginx.

It provides user registration, intelligent matching, real-time chat, and notifications inside a secure, scalable, and production-ready architecture.

---

⚙️ Tech Stack

Layer	Technology	Purpose
Frontend	Next.js	Modern SSR/CSR React application
Backend	Express.js	REST API + Socket.IO real-time layer
Database	PostgreSQL	Users, chats, matches data storage
Proxy / Deployment	Nginx	Reverse proxy, SSL, production routing

---

🧱 Architecture Overview

Velora is designed as a modular full-stack system:

• Frontend communicates via centralized API layer
• Backend follows MVC architecture
• Real-time communication handled via Socket.IO
• Nginx manages routing and production traffic

---

🧱 Development Workflow

Branching Model

• main → Production-ready stable release
• dev → Active integration branch
• feature/<name> → New features
• fix/<name> → Bug fixes

---

Workflow Steps

1. Create a Linear issue (feature or bug)
2. Create a feature branch from dev:

git checkout -b feature/LIN-123-chat-system

3. Implement feature following project standards
4. Push branch and open a PR into dev

---

Pull Request Rules

• PR title must include Linear ID:

LIN-123: Implement chat system backend

• Link issue in description:

Closes LIN-123

✔ Automatically closes issue when merged

---

🧠 Commit Standards

Follow Conventional Commits:

feat: add matchmaking algorithm
fix: resolve socket disconnect issue
refactor: optimize user query logic
docs: improve API documentation

Rules:

• One logical change per commit
• Keep messages clean and meaningful
• Always run:

pnpm lint && pnpm format

---

🧩 Backend Architecture (Express)

Structure:

server/
├── models/
├── controllers/
├── routes/
└── middlewares/

Rules:

• Keep controllers lightweight
• Use parameterized queries or Prisma/Sequelize
• Validate inputs using middleware
• Centralized error handler required

---

🎨 Frontend Architecture (Next.js)

Structure:

• components/
• pages/
• hooks/
• lib/

Rules:

• Prefer server components when possible
• Centralize API calls in /lib/api
• Tailwind CSS for consistent UI system
• Fully responsive by default

---

🗂️ Task Management (Linear)

Workflow

• Backlog → Not started
• Todo → Ready
• In Progress → Active development
• Review → PR under review
• Done → Merged

Priority Levels

Level	Meaning
🔥 High	Core / blocking features
⚙️ Medium	Enhancements / UI updates
🧹 Low	Minor fixes / cleanup

---

Linking Work

Every feature MUST:

• Have a Linear issue

• Use issue ID in:

  • Branch name
  • PR title
  • Commit messages

Example:

Closes LIN-123

---

🔐 Security Rules

• Passwords hashed with bcrypt
• Authentication via JWT
• Protect all private routes
• Never commit .env files
• Validate all inputs (prevent SQLi + XSS)
• HTTPS required in production (Nginx)

---

🧰 Setup Instructions

Install dependencies

pnpm install

---

Environment variables

DATABASE_URL=postgres://user:password@localhost:5432/velora
JWT_SECRET=your_secret

---

Run development

pnpm -C backend dev
pnpm -C frontend dev

---

🚀 Production (Nginx)

• /api → Express backend
• / → Next.js build

Ensure SSL is configured in:

/etc/nginx/sites-enabled/

---

🧩 PR Checklist

• Code builds successfully
• No console logs / debug code
• Follows naming conventions
• Security checks passed
• Linked to Linear issue
• Tested locally

---

🤝 Contributing

1. Assign yourself a Linear issue
2. Create a feature branch
3. Follow commit + code standards
4. Open PR to dev
5. Fix review comments
6. Merge after approval

---

🧾 License

Private project — educational use only.

---

💬 Maintainers

Velora Core Team Built with ❤️ using Next.js, Express.js, PostgreSQL, and Nginx

---