AgencyOs

# AgencyOS — Mostaql Listing

> A complete, production-ready MERN SaaS platform for digital agency management.

---

## 🇺🇸 English Listing

### Title (الإنجليزي)

**AgencyOS — Full MERN SaaS Platform for Digital Agencies (Auth, Clients, Projects, Tasks, Invoices, AI)**

### Category

Web Development › Full Stack Development

### Tags

React, Node.js, Express, MongoDB, MERN Stack, SaaS, Tailwind CSS, JWT, OpenAI, REST API, Agency Management, CRM, Project Management

---

### Description

A complete, production-grade SaaS platform that replaces WhatsApp + Excel + Google Drive + Trello + manual invoicing for digital marketing agencies. Built from scratch with a clean, modern UI inspired by Linear, Notion, ClickUp and Stripe.

**The entire platform is fully functional end-to-end** — backend API, database models, authentication, role-based permissions, and a polished React frontend. Every screen is wired to a real database, with no mocks, no placeholders, and no "coming soon" on the core flows.

---

### ✨ What's included

**Marketing & Auth**

- Premium animated landing page (hero, features, product preview, testimonials, pricing, FAQ, CTA)

- Full authentication: register, login, forgot/reset password, email verification

- JWT access + refresh tokens, secure httpOnly cookies, single-flight auto-refresh

- Role-based access control (owner / manager / member / client)

**Working modules (full UI + API)**

- **Client Management** — list with filters, profile with stats & tabs, create/edit forms, tags, notes, contact & contract management

- **Dashboard** — revenue chart, project status, upcoming deadlines, activity feed

- **Global search** — Cmd+K palette across clients, projects, tasks, invoices, people

**Scaffolded modules (full backend API + landing UI)**

- Projects, Tasks, Team, Finance (invoices/payments), Analytics, AI Assistant, Files, Notifications, Client Portal

- Each one ships with a complete REST API, Mongoose models, RBAC, and a "what's next" page that documents the planned UI

**AI Assistant** (unique)

- OpenAI-powered (gpt-4o-mini by default) with a context-aware system prompt

- Asks about clients, revenue, project risks, team workload

- 5 preset prompts (risks, revenue, team, clients, focus)

- Graceful offline mode: returns curated structured insights when no API key is set

---

### 🛠 Tech stack

**Backend**

- Node.js + Express

- MongoDB + Mongoose (12 collections)

- JWT auth (access + refresh + rotation)

- Zod validation

- Helmet, CORS, rate-limit, mongo-sanitize, hpp, compression

- OpenAI SDK

- Nodemailer (with console fallback)

- Multer for file uploads

- Pino-style colored logger

**Frontend**

- React 18 + Vite

- Tailwind CSS with custom design system (light + dark)

- 13 shadcn-style UI primitives (Radix UI + CVA)

- Framer Motion animations

- React Query (TanStack Query v5) for data

- React Router v6

- Axios with auto-refresh interceptor

- Recharts for analytics

- Sonner toasts + cmdk command palette

---

### 🗄 Database models (12)

User, Client, Project, Task, Invoice, Payment, Employee, Notification, File, Comment, Message, ActivityLog — each with proper indexing, validation, hooks, and pre-save computed fields (e.g. invoice totals, client slugs, project progress).

---

### 🎨 Design

- Custom design system: light + dark themes, 5 accent colors, gradient/glass effects

- Fully responsive (mobile sidebar, mobile-first tables)

- Accessible (Radix primitives)

- Smooth animations everywhere (Framer Motion)

- Reusable component library

---

### 🚀 How to run

```bash

# 1. install

npm run install:all

# 2. configure

cp server/.env.example server/.env

# edit MONGO_URI, JWT_ACCESS_SECRET, JWT_REFRESH_SECRET

# 3. seed demo data

npm run seed

# 4. start (in 2 terminals)

npm run dev:server # http://localhost:5000

npm run dev:client # http://localhost:5173

```

**Demo accounts (all use `Password123!`):**

- `owner@agencyos.com` — full access

- `manager@agencyos.com` — can manage projects/team

- `member@agencyos.com` — team member

- `client@acmecorp.com` — client portal user

---

### 📦 What you get

- 142 source files

- 63 backend files (12 models, 15 controllers, 15 routes, 6 middlewares, 2 services, 1 seed)

- 65 frontend files (13 UI primitives, full landing/auth/dashboard/clients, 9 scaffolded modules, premium 404)

- Full REST API documentation (`server/docs/API.md`)

- Production deployment guide (`DEPLOYMENT.md`) for Render + Vercel + MongoDB Atlas

- Clean, commented-light, dependency-light code — no dead files, no placeholder TODOs on critical paths

---

### ✅ Why this listing

This isn't a wireframe. This isn't a portfolio mockup. This is a real, runnable, extensible SaaS foundation that you can:

- White-label for a specific agency

- Customize per client branding

- Extend with payments (Stripe is a 1-day integration)

- Deploy to production today

The buyer receives the entire codebase, full documentation, and a working demo they can log into and click through in under 2 minutes.

---

## 🇸🇦 الوصف بالعربية

### العنوان

**AgencyOS — منصة SaaS كاملة لإدارة وكالات التسويق الرقمي (MERN Stack)**

### القسم

تطوير الويب › تطوير متكامل (Full Stack)

### الوسوم

React, Node.js, MongoDB, MERN, SaaS, إدارة مشاريع, نظام عملاء, فواتير, ذكاء اصطناعي, JWT

---

### الوصف

منصة SaaS متكاملة وجاهزة للإنتاج تُغني وكالات التسويق الرقمي عن استخدام واتساب + إكسل + Drive + Trello + الفواتير اليدوية. مبنية من الصفر بواجهة عصرية مستوحاة من Linear و Notion و ClickUp و Stripe.

**المنصة تعمل بالكامل من النهاية إلى النهاية** — API خلفية، نماذج قاعدة بيانات، مصادقة، صلاحيات حسب الدور، وواجهة React مصقولة. كل شاشة مرتبطة بقاعدة بيانات حقيقية، بدون أي بيانات وهمية أو عناصر ناقصة.

---

### ✨ المميزات

**التسويق والمصادقة**

- صفحة هبوط متحركة بجودة عالية (Hero, Features, Pricing, FAQ, CTA)

- مصادقة كاملة: تسجيل، دخول، استعادة كلمة المرور، تفعيل البريد

- JWT access + refresh tokens مع تدوير آمن

- صلاحيات حسب الدور (مالك / مدير / عضو / عميل)

**الوحدات الجاهزة (واجهة + API)**

- **إدارة العملاء** — قائمة مع فلاتر، بروفايل مع إحصائيات، نماذج إضافة/تعديل، وسوم، ملاحظات

- **لوحة التحكم** — رسم بياني للإيرادات، حالة المشاريع، المواعيد القادمة، آخر النشاطات

- **بحث شامل** — Cmd+K للبحث في كل شيء

**وحدات أخرى (API كامل + واجهة قادمة)**

- المشاريع، المهام، الفريق، المالية، التحليلات، المساعد الذكي، الملفات، الإشعارات، بوابة العميل

**المساعد الذكي** (ميزة مميزة)

- مدعوم بـ OpenAI (gpt-4o-mini افتراضياً)

- يجيب عن أسئلة حول العملاء والإيرادات والمخاطر

- 5 قوالب جاهزة (مخاطر، إيرادات، فريق، عملاء، تركيز)

- يعمل بدون API key في وضع غير متصل

---

### 🛠 التقنيات

**الخلفية**: Node.js, Express, MongoDB, Mongoose, JWT, Zod, OpenAI, Nodemailer, Helmet, Rate-limit

**الواجهة**: React 18, Vite, Tailwind CSS, Radix UI, Framer Motion, React Query, Recharts, Axios, Sonner

---

### 🚀 طريقة التشغيل

```bash

npm run install:all

cp server/.env.example server/.env

npm run seed

npm run dev:server # http://localhost:5000

npm run dev:client # http://localhost:5173

```

**حسابات تجريبية (كلمة المرور: `Password123!`):**

- `owner@agencyos.com`

- `manager@agencyos.com`

- `member@agencyos.com`

- `client@acmecorp.com`

---

### 📦 ما ستحصل عليه

- 142 ملف مصدر

- 63 ملف خلفي (12 نموذج، 15 controller، 15 route)

- 65 ملف واجهة (13 مكون UI، landing كامل، dashboard، إدارة عملاء كاملة)

- توثيق API كامل (`server/docs/API.md`)

- دليل نشر للإنتاج (`DEPLOYMENT.md`) — Render + Vercel + Atlas

---

### 💡 لماذا هذا المشروع؟

هذا ليس wireframe ولا mockup. هذا أساس SaaS حقيقي قابل للتشغيل يمكن تخصيصه للوكالة الخاصة بك، أو تبييضه (white-label)، أو توسيعه بدمج Stripe للدفع، أو نشره في الإنتاج اليوم.

المشتري يستلم الكود كاملاً مع التوثيق وتجربة عمل مباشرة يمكنه تجربتها في أقل من دقيقتين.