https://github.com/albahranimazin-commits/mazoon-platform
A comprehensive platform for every Omani
https://github.com/albahranimazin-commits/mazoon-platform
arabic flask oman python rest-api sqlite
Last synced: 3 months ago
JSON representation
A comprehensive platform for every Omani
- Host: GitHub
- URL: https://github.com/albahranimazin-commits/mazoon-platform
- Owner: albahranimazin-commits
- License: mit
- Created: 2025-11-12T16:24:19.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-11-12T18:49:39.000Z (9 months ago)
- Last Synced: 2025-11-12T19:12:08.887Z (9 months ago)
- Topics: arabic, flask, oman, python, rest-api, sqlite
- Language: HTML
- Homepage:
- Size: 118 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README .md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 🌟 Mazoon Platform | منصة مزون
**A Comprehensive Platform for Every Omani**
**منصة شاملة لكل عماني**
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://flask.palletsprojects.com/)
[](test_all_crud.py)
[](https://en.wikipedia.org/wiki/Oman)
[Features](#-features) • [Quick Start](#-quick-start) • [API Docs](#-api-documentation) • [Contributing](#-contributing) • [License](#-license)
---
## 📋 Table of Contents | المحتويات
- [About](#-about)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Project Structure](#-project-structure)
- [API Documentation](#-api-documentation)
- [Database Schema](#-database-schema)
- [Testing](#-testing)
- [Frontend Integration](#-frontend-integration)
- [Deployment](#-deployment)
- [Contributing](#-contributing)
- [License](#-license)
- [Contact](#-contact)
---
## 🎯 About | نبذة
Mazoon (مزون) is a comprehensive web platform designed to serve the Omani community by bringing together news, events, jobs, tourism information, and much more in one unified platform.
مزون هي منصة ويب شاملة مصممة لخدمة المجتمع العماني من خلال جمع الأخبار والفعاليات والوظائف ومعلومات السياحة والمزيد في منصة موحدة.
### Why Mazoon? | لماذا مزون؟
- 🇴🇲 **Built for Omanis** - Designed with Omani culture and needs in mind
- 🌐 **Bilingual** - Full support for Arabic and English
- 📱 **Modern** - RESTful API, responsive design, modern tech stack
- 🔓 **Open Source** - Free to use, modify, and contribute
- 📊 **Comprehensive** - 11 major systems in one platform
---
## ✨ Features | المميزات
### 📰 **News System** | نظام الأخبار
- 7 categories covering local, world, economy, sports, tech, health, and culture
- Full CRUD operations
- View tracking
- Arabic and English support
### 📅 **Events System** | نظام الفعاليات
- 6 categories: festivals, exhibitions, workshops, sports, culture, education
- Event registration
- Calendar integration
- Free and paid events
### 💼 **Jobs System** | نظام التوظيف
- 8 job categories
- Company profiles
- Application tracking
- Salary ranges in OMR
### 🏖️ **Tourism System** | نظام السياحة
- Tourist attractions database
- Reviews and ratings
- Interactive maps
- Opening hours and fees
### 👨🍳 **Recipes System** | نظام الوصفات
- Traditional Omani recipes
- Step-by-step instructions
- Ingredient lists
- Cooking times
### 🏢 **Business Directory** | دليل الأعمال
- Local business listings
- Reviews and ratings
- Contact information
- Categories and filters
### 💬 **Community Forums** | المنتديات
- Discussion topics
- User engagement
- Moderation system
### 🔍 **Global Search** | البحث الشامل
- Search across all content types
- Fast and efficient
- Relevant results
### 📊 **Statistics** | الإحصائيات
- Real-time platform stats
- Usage analytics
- Growth tracking
---
## 🚀 Quick Start | البدء السريع
### Prerequisites | المتطلبات
- Python 3.7 or higher
- pip (Python package manager)
- Modern web browser
### Installation | التثبيت
```bash
# Clone the repository
git clone https://github.com/mazoon-platform/mazoon.git
cd mazoon
# Install dependencies
pip install -r requirements.txt
# Initialize the database
python init_database.py
# Verify database
python verify_database.py
```
### Running the API | تشغيل الواجهة البرمجية
```bash
# Start the API server
python api.py
# API will be available at:
# http://localhost:5000
```
### Testing | الاختبار
```bash
# Option 1: Open interactive test interface
open test_api.html
# Option 2: Run automated tests
python test_all_crud.py
# Option 3: Manual testing with curl
curl http://localhost:5000/health
```
---
## 📁 Project Structure | هيكل المشروع
```
mazoon-platform/
├── 📄 README.md # This file
├── 📄 LICENSE # MIT License
├── 📄 CONTRIBUTING.md # Contribution guidelines
├── 📄 CHANGELOG.md # Version history
├── 📄 .gitignore # Git ignore rules
│
├── 📊 DATABASE/
│ ├── mazoon_database.sql # SQL schema (37 tables)
│ ├── mazoon.db # SQLite database
│ ├── init_database.py # Database initialization
│ └── verify_database.py # Database verification
│
├── 🔌 API/
│ ├── api.py # Main API server
│ └── api_example.py # API usage examples
│
├── ✅ TESTS/
│ ├── test_api.html # Interactive test UI
│ └── test_all_crud.py # Automated tests
│
├── 📚 DOCS/
│ ├── API_TESTING_GUIDE.md # API documentation
│ ├── DATABASE_README.md # Database guide
│ ├── PROJECT_SUMMARY.md # Project overview
│ └── FILES_OVERVIEW.txt # File descriptions
│
└── 📦 requirements.txt # Python dependencies
```
---
## 📖 API Documentation | توثيق الواجهة البرمجية
### Base URL
```
http://localhost:5000/api
```
### Endpoints Summary
#### News Endpoints
```http
GET /api/news # List all news
GET /api/news/ # Get single article
POST /api/news # Create article
PUT /api/news/ # Update article
DELETE /api/news/ # Delete article
GET /api/news/categories # Get categories
```
#### Events Endpoints
```http
GET /api/events # List all events
GET /api/events/ # Get single event
POST /api/events # Create event
PUT /api/events/ # Update event
DELETE /api/events/ # Delete event
GET /api/events/categories # Get categories
```
#### Jobs Endpoints
```http
GET /api/jobs # List all jobs
GET /api/jobs/ # Get single job
POST /api/jobs # Create job
PUT /api/jobs/ # Update job
DELETE /api/jobs/ # Delete job
GET /api/jobs/categories # Get categories
```
#### Other Endpoints
```http
GET /api/search?q=query # Global search
GET /api/stats # Platform statistics
GET /health # Health check
```
### Example Request
```bash
# Get all news
curl http://localhost:5000/api/news?limit=10
# Create news article
curl -X POST http://localhost:5000/api/news \
-H "Content-Type: application/json" \
-d '{
"category_id": 1,
"title_ar": "خبر جديد",
"slug": "new-article",
"content_ar": "محتوى الخبر"
}'
```
### Response Format
```json
{
"success": true,
"message": "Success",
"data": {
// Response data here
}
}
```
📚 **Full API documentation:** [API_TESTING_GUIDE.md](API_TESTING_GUIDE.md)
---
## 🗄️ Database Schema | مخطط قاعدة البيانات
### Overview | نظرة عامة
- **37 Tables** across 11 major systems
- **48+ Indexes** for optimized performance
- **Automatic Triggers** for data integrity
- **Full Arabic & English** support
### Main Tables
| System | Tables | Description |
|--------|--------|-------------|
| Users | 2 | User accounts and preferences |
| News | 4 | Articles, categories, tags |
| Events | 3 | Events, categories, registrations |
| Jobs | 4 | Jobs, companies, categories, applications |
| Marketplace | 3 | Listings, categories, images |
| Tourism | 4 | Places, categories, images, reviews |
| Recipes | 2 | Recipes, categories |
| Education | 2 | Institutions, programs |
| Business | 3 | Directory, categories, reviews |
| Forums | 3 | Topics, replies, categories |
| Weather | 2 | Locations, data |
📚 **Full database documentation:** [DATABASE_README.md](DATABASE_README.md)
---
## ✅ Testing | الاختبار
### Test Coverage
- **17 Tests** covering all major operations
- **100% Success Rate** on all CRUD operations
- **Automated** and **Interactive** testing options
### Test Results
```
✅ CREATE Operations - News, Events, Jobs
✅ READ Operations - All entities with pagination
✅ UPDATE Operations - All entities
✅ DELETE Operations - All entities
✅ CATEGORIES - All entity types
✅ SEARCH - Global search functionality
✅ STATISTICS - Platform-wide stats
🎉 17/17 Tests Passed
```
### Running Tests
```bash
# Interactive web interface
open test_api.html
# Automated test suite
python test_all_crud.py
# Database verification
python verify_database.py
```
---
## 💻 Frontend Integration | ربط الواجهة الأمامية
### React Example
```javascript
import axios from 'axios';
const API_BASE = 'http://localhost:5000/api';
// Fetch news
const fetchNews = async () => {
const response = await axios.get(`${API_BASE}/news`);
return response.data.data.articles;
};
// Create news
const createNews = async (newsData) => {
const response = await axios.post(`${API_BASE}/news`, newsData);
return response.data;
};
```
### Vue.js Example
```javascript
// In your Vue component
export default {
data() {
return {
news: [],
apiBase: 'http://localhost:5000/api'
}
},
async mounted() {
const response = await fetch(`${this.apiBase}/news`);
const data = await response.json();
this.news = data.data.articles;
}
}
```
### Vanilla JavaScript
```javascript
// Fetch news
fetch('http://localhost:5000/api/news')
.then(res => res.json())
.then(data => {
const articles = data.data.articles;
// Display articles
});
```
---
## 🚀 Deployment | النشر
### Development
```bash
python api.py
```
### Production
```bash
# Using Gunicorn
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 api:app
# Using uWSGI
pip install uwsgi
uwsgi --http :5000 --wsgi-file api.py --callable app
```
### Docker (Coming Soon)
```bash
docker build -t mazoon-api .
docker run -p 5000:5000 mazoon-api
```
### Environment Variables
```bash
export FLASK_ENV=production
export DATABASE_URL=sqlite:///mazoon.db
export SECRET_KEY=your-secret-key
```
---
## 🤝 Contributing | المساهمة
We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting pull requests.
نرحب بالمساهمات من المجتمع! يرجى قراءة [إرشادات المساهمة](CONTRIBUTING.md) قبل تقديم طلبات السحب.
### How to Contribute
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Areas for Contribution
- 🔐 Authentication & Authorization
- 📸 Image upload
- 🔔 Real-time notifications
- 📊 Analytics dashboard
- 🌐 Internationalization
- 📱 Mobile optimization
- 🐛 Bug fixes
- 📚 Documentation
- ✅ Tests
---
## 📄 License | الترخيص
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
هذا المشروع مرخص بموجب ترخيص MIT - راجع ملف [LICENSE](LICENSE) للحصول على التفاصيل.
---
## 📞 Contact | التواصل
- **Website:** https://mazoon.om
- **Email:** support@mazoon.om
- **GitHub:** https://github.com/mazoon-platform/mazoon
- **Issues:** https://github.com/mazoon-platform/mazoon/issues
---
## 🙏 Acknowledgments | شكر وتقدير
- Thanks to all contributors who help make Mazoon better
- Built with ♥ for the Omani community
- Inspired by the vision of a connected Oman
---
## 📊 Project Statistics | إحصائيات المشروع
- **37** Database Tables
- **17** API Endpoints
- **11** Major Systems
- **100%** Test Coverage
- **2** Languages (Arabic & English)
---
**Made with ♥ in Oman | صُنع بكل ♥ في عُمان**
⭐ Star us on GitHub if you find this project useful!
[⬆ Back to Top](#-mazoon-platform--منصة-مزون)