BizFlow | بيز فلو

AI-powered business planning platform — analyze markets, score opportunities, manage projects, and chat with an AI consultant in English or Arabic.

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

GitHub Repository

Table of contents | فهرس المحتويات

English	العربية
Overview	نظرة عامة
Features	المميزات
Tech stack	التقنيات المستخدمة
AI in BizFlow	الذكاء الاصطناعي
Project structure	هيكل المشروع
Getting started	التشغيل المحلي
Environment variables	متغيرات البيئة
API overview	واجهة الـ API
Diagrams	المخططات
Security	الأمان

Overview (English)

BizFlow helps entrepreneurs and small teams decide whether to open a business in a given location. The app combines:

Market data — nearby competitors via Google Places (or deterministic mock data for demos)
Scoring engine — weighted business score from demand, competition, rent affordability, and review sentiment
Google Gemini — narrative analysis, recommendations, and an interactive AI chat
Project workspace — projects, tasks, financial records, resources, notifications, and saved AI insights

The UI supports RTL (Arabic) and LTR (English), light/dark themes, charts (Recharts), and an optional Google Maps view for competitor locations.

Features (English)

Area	Description
Landing & auth	Register, login, JWT sessions; demo user `demo@bizflow.app` / `demo123`
AI Market Wizard	Step-by-step: category, location, budget → analysis → charts, map, save to project
Business analysis	Competitor count, ratings, rent estimate, sub-scores, Gemini JSON insights
AI chat	BIZFLOW consultant; auto-detects “open a cafe in …” and injects live market snapshot
Dashboard	Project count, insight count, average score, last analysis
Projects	CRUD projects; link insights; tasks, finances, resources per project
i18n	Full Arabic/English via `i18next` (frontend) and server-side `lang` middleware
Diagrams	Architecture, ERD, use cases, sequences (see `/Diagrams`)

Tech stack (English)

Frontend (`FrontEnd/`)

Tool	Role
React 19	UI framework
TypeScript	Type-safe components
Vite 5	Dev server & production build
React Router 7	Client-side routing
Tailwind CSS 3	Styling & responsive layout
Radix UI	Accessible primitives (dialog, tabs, avatar, etc.)
Framer Motion	Page transitions & marketing animations
Recharts	Business score radar, bar charts, radial gauges
i18next / react-i18next	Arabic & English translations
@react-google-maps/api	Competitor map on analysis results
Lucide React	Icons
ESLint + TypeScript ESLint	Linting

Backend (`BackEnd/`)

Tool	Role
Node.js (ES modules)	Runtime
Express 4	REST API
better-sqlite3	Embedded SQLite database
bcryptjs	Password hashing
jsonwebtoken	JWT authentication
Zod	Request validation
dotenv	Environment configuration
CORS	Allows Vite dev origin (`localhost:5173`)

External services

Service	Usage
Google Gemini API	Business review analysis, chat replies (`GEMINI_API_KEY`, model `GEMINI_MODEL`)
Google Places API	Nearby competitors & geocoding (`GOOGLE_PLACES_API_KEY`)
Google Maps JavaScript API	Frontend map (`VITE_GOOGLE_MAPS_API_KEY`)

AI in BizFlow (English)

BizFlow uses Google Gemini (generativelanguage.googleapis.com) in two main flows:

1. Business analysis wizard (`POST /api/business/analyze`)

Places layer — Fetches nearby competitors (Google Places or mock when USE_MOCK_PLACES=true / no API key).
Heuristic layer — Computes rent estimate, sub-scores (demand, competition, rent affordability, sentiment), and weighted business score (0–100).
Gemini layer — Sends category, location, competitor count, and aggregated review text; expects JSON with:
- overallSentimentScore, strengths, weaknesses
- marketOpportunity, riskLevel, finalRecommendation (Open / Avoid / Careful)
- advice, profitOutlookSummary, estimatedMonthlyProfit
Fallback — If Gemini fails, heuristic defaults are returned so the wizard still works offline.

Results are stored in ai_insights and shown with charts + optional map.

2. AI consultant chat (`POST /api/ai/chat`)

Maintains conversation history per sessionId.
Intent detection — Parses phrases like “Should I open a restaurant in Cairo?” to trigger a live runBusinessAnalysis.
System prompt — Injects market snapshot (competitors, score, rent, profit outlook, recommendation) into Gemini context.
Replies in Arabic or English based on user language.
Messages persisted in chat_messages.

Default model

gemini-2.5-flash (override with GEMINI_MODEL in BackEnd/.env).

Disclaimer: Rent, profit, and scores are illustrative estimates, not financial or legal advice.

Project structure

Biz-Flow/
├── BackEnd/                 # Express API + SQLite
│   ├── src/
│   │   ├── index.js         # App entry, routes mount
│   │   ├── db/migrate.js    # Schema & demo seed
│   │   ├── routes/          # auth, business, ai, projects, tasks, …
│   │   ├── services/        # gemini, analysis, places, googlePlaces
│   │   ├── middleware/      # JWT auth, language
│   │   └── i18n/            # Server error strings (ar/en)
│   ├── data/                # bizflow.sqlite (gitignored)
│   └── .env.example
├── FrontEnd/                # React + Vite SPA
│   ├── src/
│   │   ├── pages/           # Landing, Login, Wizard, Chat, Dashboard, …
│   │   ├── components/      # UI, maps, wizard charts, marketing
│   │   ├── lib/             # API client, auth helpers
│   │   ├── providers/       # Theme, language, loading
│   │   └── i18n/            # ar/en JSON
│   └── .env.example
├── Diagrams/                # Architecture & UML images
├── .gitignore
└── README.md

Getting started (English)

Prerequisites

Node.js 18+ (20+ recommended)
npm
API keys (optional for full features): Gemini, Google Cloud (Places + Maps)

1. Clone

git clone https://github.com/mohamedmoamen8/Biz-Flow.git
cd Biz-Flow

2. Backend

cd BackEnd
copy .env.example .env    # Windows: copy | Linux/Mac: cp
npm install
npm run migrate
npm run dev

API: http://localhost:4000 — health check: GET /api/health

3. Frontend

cd FrontEnd
copy .env.example .env
npm install
npm run dev

App: http://localhost:5173

4. Demo login

Field	Value
Email	`demo@bizflow.app`
Password	`demo123`

Environment variables

Never commit .env files. Use .env.example as a template.

BackEnd (`BackEnd/.env`)

Variable	Description
`PORT`	API port (default `4000`)
`JWT_SECRET`	Secret for signing tokens (required in production)
`JWT_EXPIRES_IN`	Token lifetime (e.g. `7d`)
`GEMINI_API_KEY`	Google Gemini API key
`GEMINI_MODEL`	Model id (default `gemini-2.5-flash`)
`GOOGLE_PLACES_API_KEY`	Places Text Search / Nearby
`USE_MOCK_PLACES`	`true` to skip Places API and use mock competitors

FrontEnd (`FrontEnd/.env`)

Variable	Description
`VITE_API_URL`	Backend URL (default `http://localhost:4000`)
`VITE_GOOGLE_MAPS_API_KEY`	Maps JavaScript API for wizard map

API overview

Base URL: http://localhost:4000

Method	Path	Auth	Description
GET	`/api/health`	No	Service health
POST	`/api/auth/register`	No	Create account
POST	`/api/auth/login`	No	JWT login
POST	`/api/business/analyze`	Yes	Run full AI market analysis
GET	`/api/business/insights`	Yes	List saved insights
GET	`/api/business/competitors`	Yes	Map competitor points
POST	`/api/ai/chat`	Yes	Gemini consultant chat
GET	`/api/dashboard/stats`	Yes	Dashboard aggregates
CRUD	`/api/projects`, `/api/tasks`, …	Yes	Project workspace

Send Authorization: Bearer <token> and optional Accept-Language: ar for Arabic responses.

Diagrams

The Diagrams/ folder includes:

Context & container architecture
ERD & database diagram
Class diagram, use cases
Sequence: login, business analysis
Activity: wizard analysis flow

Security

.env, SQLite DB files, and node_modules/ are gitignored
Passwords hashed with bcrypt
Protected routes use JWT middleware
Do not expose API keys in source code or commits
Rotate JWT_SECRET and all API keys before production deployment

نظرة عامة (العربية)

بيز فلو (BizFlow) منصة ويب تساعد رواد الأعمال على تقييم فكرة مشروع جديد في موقع معيّن. تجمع المنصة بين:

بيانات السوق — منافسون قريبون عبر Google Places (أو بيانات تجريبية ثابتة للعرض بدون مفتاح API)
محرك التقييم — درجة مركّبة من الطلب، المنافسة، ملاءمة الإيجار، وتحليل المراجعات
Gemini من Google — تحليل نصي، توصيات، ومحادثة مع مستشار ذكي
مساحة عمل — مشاريع، مهام، سجلات مالية، موارد، إشعارات، وتحليلات محفوظة

واجهة المستخدم تدعم العربية (RTL) والإنجليزية (LTR)، الوضع الفاتح/الداكن، رسوم بيانية، وخريطة اختيارية للمنافسين.

المميزات (العربية)

القسم	الوصف
الصفحة الرئيسية والمصادقة	تسجيل، دخول، جلسات JWT؛ حساب تجريبي `demo@bizflow.app` / `demo123`
معالج السوق الذكي	خطوات: النشاط، الموقع، الميزانية → تحليل → رسوم بيانية وخريطة وحفظ في مشروع
تحليل الأعمال	عدد المنافسين، التقييمات، تقدير الإيجار، درجات فرعية، رؤى Gemini
محادثة الذكاء الاصطناعي	مستشار BIZFLOW؛ يكتشف نية مثل «أفتح مقهى في …» ويضيف لقطة السوق
لوحة التحكم	إحصائيات المشاريع والتحليلات ومتوسط الدرجة
المشاريع	إنشاء وربط التحليلات؛ مهام، مالية، موارد
تعدد اللغات	عربي/إنجليزي في الواجهة والخادم
المخططات	معمارية، ERD، حالات استخدام، تسلسل (مجلد `Diagrams`)

التقنيات المستخدمة (العربية)

الواجهة الأمامية

الأداة	الاستخدام
React 19 + TypeScript	بناء الواجهة
Vite 5	التطوير والبناء
React Router 7	التنقل بين الصفحات
Tailwind CSS	التصميم المتجاوب
Radix UI	مكوّنات وصول سهلة
Framer Motion	حركات وانتقالات
Recharts	مخططات الدرجة والسوق
i18next	ترجمة عربي/إنجليزي
Google Maps API	خريطة المنافسين

الخادم الخلفي

الأداة	الاستخدام
Node.js + Express	واجهة REST
SQLite (better-sqlite3)	قاعدة بيانات مدمجة
bcryptjs + JWT	أمان الحسابات
Zod	التحقق من المدخلات
dotenv	إعدادات البيئة

خدمات خارجية

الخدمة	الاستخدام
Google Gemini	تحليل المراجعات والمحادثة
Google Places	المنافسون والموقع
Google Maps	عرض الخريطة في المعالج

الذكاء الاصطناعي في بيز فلو (العربية)

1. معالج تحليل السوق

جلب المنافسين القريبين (Places أو وضع تجريبي).
حساب تقدير الإيجار والدرجات الفرعية والدرجة الإجمالية (0–100).
إرسال نصوص المراجعات إلى Gemini لاستخراج JSON: نقاط القوة والضعف، مستوى المخاطر، التوصية (افتح / تجنّب / بحذر)، نصيحة، وتوقعات الربح.
عند فشل Gemini يُستخدم تقدير احتياطي حتى يعمل التطبيق بدون اتصال بالذكاء الاصطناعي.

2. محادثة المستشار

حفظ الرسائل لكل جلسة.
اكتشاف نية فتح مشروع في موقع معيّن وحقن نتائج التحليل في سياق Gemini.
الرد بالعربية أو الإنجليزية حسب لغة المستخدم.

النموذج الافتراضي

gemini-2.5-flash — يمكن تغييره عبر GEMINI_MODEL.

تنبيه: الأرقام والتوصيات تقديرية تعليمية وليست استشارة مالية أو قانونية.

التشغيل المحلي (العربية)

المتطلبات

Node.js 18 أو أحدث
npm
مفاتيح API (اختياري): Gemini، Google Places، Google Maps

الخطوات

git clone https://github.com/mohamedmoamen8/Biz-Flow.git
cd Biz-Flow

الخادم:

cd BackEnd
copy .env.example .env
npm install
npm run migrate
npm run dev

الواجهة:

cd FrontEnd
copy .env.example .env
npm install
npm run dev

الخادم: http://localhost:4000
التطبيق: http://localhost:5173

حساب تجريبي: demo@bizflow.app / demo123

Scripts | أوامر التشغيل

Location	Command	Purpose
`BackEnd`	`npm run dev`	API with file watch
`BackEnd`	`npm start`	API production mode
`BackEnd`	`npm run migrate`	Create/update SQLite schema
`FrontEnd`	`npm run dev`	Vite dev server
`FrontEnd`	`npm run build`	Production build
`FrontEnd`	`npm run lint`	ESLint

Contributing | المساهمة

Fork the repository
Create a feature branch
Keep secrets in .env only — never commit API keys
Open a pull request with a clear description

License

This project is provided as-is for educational and portfolio use. Add a license file if you plan to open-source under a specific terms (MIT, Apache, etc.).

BizFlow — Plan smarter. Launch with clarity.
بيز فلو — خطّط بذكاء. انطلق بوضوح.

Name		Name	Last commit message	Last commit date
BackEnd		BackEnd
Diagrams		Diagrams
FrontEnd		FrontEnd
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation