EthioHeritage360 - Ethiopian Heritage Platform

A comprehensive digital platform for preserving, exploring, and sharing Ethiopia's rich cultural heritage through immersive virtual experiences, artifact management, and community engagement.

🚀 Live Demo • 📖 Documentation • 🔧 Setup Guide • 🗄️ Database Docs • 🐛 Report Bug • ✨ Request Feature

### *Preserving Ethiopia's Cultural Heritage Through Technology* [![Project Status](https://img.shields.io/badge/Status-Production%20Ready-green)](https://github.com/Summer-Camp-Project/Project-for-G25) [![Frontend](https://img.shields.io/badge/Frontend-React%2018-61DAFB?logo=react)](https://reactjs.org/) [![Backend](https://img.shields.io/badge/Backend-Node.js-339933?logo=node.js)](https://nodejs.org/) [![Database](https://img.shields.io/badge/Database-MongoDB-47A248?logo=mongodb)](https://mongodb.com/) [![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE) *A comprehensive digital platform for preserving, exploring, and sharing Ethiopia's rich cultural heritage through immersive virtual experiences, artifact management, and community engagement.* [🚀 **Live Demo**](https://ethioheritage360.com) • [📖 **Documentation**](./docs) • [🐛 **Report Bug**](https://github.com/Summer-Camp-Project/Project-for-G25/issues) • [✨ **Request Feature**](https://github.com/Summer-Camp-Project/Project-for-G25/issues) ---

📸 Platform Preview

### 🏠 Home Page ![Home Page](./docs/images/home-preview.png) *Modern, responsive home page showcasing Ethiopian heritage* ### 🏛️ Virtual Museum ![Virtual Museum](./docs/images/museum-preview.png) *Immersive artifact exploration with 3D/AR capabilities* ### 📊 Admin Dashboard ![Admin Dashboard](./docs/images/dashboard-preview.png) *Comprehensive management interface for all user roles*

🌟 Project Status: Production Ready

✅ Complete Implementation

EthioHeritage360 is a fully functional, production-ready platform with:

🎨 Complete Frontend: Modern React application with professional UI/UX
⚡ Full Backend: Robust Node.js/Express API with comprehensive features
🗄️ Database Integration: MongoDB with optimized schemas and indexes
🔐 Advanced Security: JWT authentication, role-based access, input validation
📱 Mobile Responsive: Optimized for all devices and screen sizes
🌍 Multilingual Support: English, Amharic, Oromo, Tigrinya
♿ Accessibility: WCAG 2.1 AA compliant

🏆 Enterprise-Grade Features

Multi-Role Architecture: Super Admin, Museum Admin, Staff, Visitors
Virtual Museum System: 3D artifact viewing, AR/VR integration
Rental Management: Complete artifact rental workflow
Event Management: Museum events, exhibitions, workshops
Analytics Dashboard: Comprehensive insights and reporting
Real-time Notifications: Smart alerts and task management
Advanced Search: AI-powered search across all content

🚀 Core Features

🏛️ Virtual Museum Experience

Immersive Artifact Gallery: 3D/AR/VR artifact viewing with high-resolution imagery
Advanced Filtering: Search by region, historical era, category, and keywords
Multilingual Content: Available in English, Amharic, Oromo, and Tigrinya
Interactive Learning: Detailed artifact descriptions, historical context, and multimedia content
Social Features: Like, share, and bookmark favorite artifacts

🗺️ Interactive Cultural Map

Heritage Site Discovery: Interactive map with detailed site information
GPS Integration: Location-based heritage site recommendations
Rich Media: Photos, videos, and virtual tours for each location
Cultural Routes: Curated heritage trails and cultural journeys

🎯 Tour Management System

Physical & Virtual Tours: Complete booking and management system
Live Streaming: Real-time virtual tour capabilities
Tour Organizer Tools: Schedule management, participant tracking, revenue analytics
Multi-language Tours: Support for local and international visitors

👥 Multi-Role User System

🛡️ Super Admin Dashboard

Platform Overview: Comprehensive analytics and statistics
User Management: Create, edit, delete users across all roles
Museum Oversight: Approve/reject museum registrations
Heritage Site Management: Add and manage cultural sites
Content Moderation: Approve artifacts, posts, and rental requests
System Settings: Global platform configuration and branding
Analytics & Reporting: Platform-wide performance insights

🏛️ Museum Admin Dashboard

Museum Profile Management: Update information, hours, contact details
Artifact Management: Upload, edit, categorize museum collections
Staff Management: Add/remove staff, assign roles and permissions
Rental System: Manage artifact rental requests and approvals
Event Management: Create and manage museum events and exhibitions
Visitor Analytics: Track museum visits, popular artifacts, revenue
Smart Notifications: Real-time alerts for pending tasks

🎨 Staff & Contributor Tools

Content Creation: Submit artifacts, write descriptions, upload media
Collaborative Editing: Multi-user content management
Task Management: Assigned responsibilities and deadlines
Quality Control: Review and approval workflows

🎫 Visitor Experience

Personalized Dashboard: Customized content feed and recommendations
Booking System: Reserve tours, events, and experiences
Social Features: Connect with other heritage enthusiasts
Learning Paths: Curated educational journeys through Ethiopian history
AI Assistant: Intelligent chatbot for questions and recommendations

💰 Comprehensive Rental System

Artifact Rentals: Complete workflow for borrowing museum pieces
Two-Tier Approval: Museum Admin → Super Admin approval process
Insurance Management: Policy tracking and documentation
Payment Processing: Secure transaction handling
Timeline Tracking: Rental duration, extensions, return monitoring
Communication Tools: Built-in messaging between parties

📊 Advanced Analytics Platform

Real-Time Dashboards: Live statistics and performance metrics
User Behavior Analytics: Visitor patterns, popular content, engagement metrics
Revenue Tracking: Tourism income, rental revenues, event attendance
Geographic Insights: Visitor origins, heritage site popularity
Custom Reports: Exportable data for research and planning

🔔 Smart Notification System

Real-Time Alerts: Instant notifications for important events
Priority Management: High/medium/low priority categorization
Multi-Channel Delivery: In-app, email, and push notifications
Action-Oriented: Direct links to relevant management pages
Customizable Preferences: User-controlled notification settings

💻 Technology Stack

Frontend

⚛️ React 18 - Modern component-based UI framework
🎨 Tailwind CSS - Utility-first CSS framework for responsive design
📋 React Router - Client-side routing and navigation
📱 Progressive Web App - PWA capabilities for mobile experience
♿ Accessibility - WCAG 2.1 AA compliant components

Backend

🟢 Node.js - JavaScript runtime environment
⚡ Express.js - Fast web application framework
🔐 JWT Authentication - Secure token-based authentication
🛡️ Helmet.js - Security middleware for HTTP headers
💫 Socket.io - Real-time bidirectional communication

Database & Storage

🍃 MongoDB - NoSQL document database with advanced aggregation
📋 Mongoose - Object modeling for MongoDB
🗄️ Optimized Schemas - Indexed collections for performance
📊 Analytics Collections - Dedicated analytics data storage

Security & Performance

🔒 bcryptjs - Password hashing and security
🛳 Rate Limiting - API protection against abuse
📚 Input Validation - Comprehensive data validation
💫 Compression - Gzip compression for optimal performance

Development & Deployment

🐳 Docker - Containerization for consistent deployment
🚀 CI/CD Ready - GitHub Actions workflow templates
🗺️ Environment Management - Secure configuration handling
🔍 Logging - Comprehensive application monitoring

📁 Project Structure

EthioHeritage360/
├── 📁 client/                    # React Frontend Application
│   ├── 📁 src/
│   │   ├── 📁 components/        # Reusable UI components
│   │   ├── 📁 pages/             # Application pages/routes
│   │   ├── 📁 hooks/             # Custom React hooks
│   │   ├── 📁 utils/             # Utility functions
│   │   └── 📁 assets/            # Images, fonts, static files
│   ├── 📄 package.json
│   └── 📄 tailwind.config.js
├── 📁 server/                    # Node.js Backend API
│   ├── 📁 controllers/          # Request handlers
│   ├── 📁 models/               # Database schemas
│   │   ├── 📄 User.js           # User management
│   │   ├── 📄 Museum.js         # Museum data
│   │   ├── 📄 Artifact.js       # Artifact collections
│   │   ├── 📄 Rental.js         # Rental system
│   │   ├── 📄 Event.js          # Event management
│   │   ├── 📄 Analytics.js      # Analytics tracking
│   │   └── 📄 SystemSettings.js # Global settings
│   ├── 📁 routes/               # API endpoints
│   │   ├── 📄 superAdmin.js     # Super admin routes
│   │   ├── 📄 museumAdmin.js    # Museum admin routes
│   │   └── 📄 auth.js           # Authentication
│   ├── 📁 middleware/           # Custom middleware
│   ├── 📁 config/               # Configuration files
│   ├── 📁 scripts/              # Database seeders
│   └── 📄 server.js             # Main application file
├── 📁 docs/                     # 📚 Organized Documentation
│   ├── 📄 README.md             # Documentation index
│   ├── 📁 setup/                # 🚀 Setup & Installation guides
│   ├── 📁 database/             # 🗄️ Database schemas & integration
│   ├── 📁 admin/                # 👥 Admin management & credentials
│   ├── 📁 features/             # 🎯 Feature specifications
│   ├── 📁 development/          # 🛠️ API docs & development guides
│   ├── 📁 troubleshooting/      # 🔧 Fixes & troubleshooting
│   └── 📁 scripts/              # 📜 Automation scripts
├── 📁 scripts/                  # Build and deployment
├── 📄 docker-compose.yml       # Docker configuration
├── 📄 package.json             # Root dependencies
└── 📄 README.md                 # This file

📋 Prerequisites

🟢 Node.js (v18.x or later) - Download
🍃 MongoDB (v6.x or later) - Download
🐳 Docker (optional, for containerized setup) - Download
🔧 Git - Download

🚀 Quick Start

1️⃣ Clone the Repository

git clone https://github.com/Summer-Camp-Project/Project-for-G25.git
cd Project-for-G25

2️⃣ Environment Setup

Create environment files for both client and server:

Server Environment (server/.env):

NODE_ENV=development
PORT=5000
MONGODB_URI=mongodb://localhost:27017/ethioheritage360
JWT_SECRET=your-super-secret-jwt-key-here
AI_API_KEY=your-ai-api-key-here

Client Environment (client/.env):

REACT_APP_API_URL=http://localhost:5000/api
REACT_APP_SOCKET_URL=http://localhost:5000

3️⃣ Installation Methods

🚀 Option A: Automatic Setup (Recommended)

# Install all dependencies and setup environment
npm run setup

⚡ Option B: Manual Installation

# Install root dependencies
npm install

# Install all workspace dependencies
npm run install:all

# Or install individually
npm run install:server
npm run install:client

4️⃣ Database Setup

🐳 Option A: Docker (Recommended for Development)

# Start MongoDB with Docker Compose
npm run db:start

# Initialize database with default data
npm run db:setup

# Access MongoDB Express UI at http://localhost:8081

📊 Option B: Local MongoDB

# Start MongoDB service
sudo service mongod start  # Linux
brew services start mongodb-community  # macOS

# Initialize database with secure seeding
cd server
npm run seed

☁️ Option C: MongoDB Atlas (Production)

Create a free MongoDB Atlas cluster
Get your connection string
Update MONGODB_URI in server/.env
Run: npm run db:seed

5️⃣ Start the Application

🔧 Development Mode:

# Start both frontend and backend concurrently
npm run dev

# Or start individually:
npm run dev:server    # Backend only
npm run dev:client    # Frontend only

🐳 Docker Development:

# Start with Docker Compose (includes hot reload)
npm run docker:dev

# View logs
npm run docker:logs

🚀 Production Mode:

# Build everything
npm run build

# Start production server
npm start

# Or with Docker
npm run docker:prod

6️⃣ Access the Platform

🌐 Frontend: http://localhost:3000
🔧 Backend API: http://localhost:5000/api
📊 Health Check: http://localhost:5000/api/health

🔑 Default Admin Access

After running the setup script, use these credentials:

Email: [email protected]
Password: SuperAdmin123!
⚠️ Important: Change the default password after first login!

🛠️ Development Guidelines

Frontend Development

📁 Components: Add reusable components in client/src/components/
📄 Pages: Create new pages in client/src/pages/
🎨 Styling: Use Tailwind CSS classes for consistent design
🔧 Hooks: Custom hooks go in client/src/hooks/

Backend Development

🛣️ Routes: Add API endpoints in server/routes/
🎮 Controllers: Business logic in server/controllers/
📊 Models: Database schemas in server/models/
🔒 Middleware: Security and validation in server/middleware/

Testing

# Run frontend tests
cd client
npm test

# Run backend tests
cd server
npm test

# Run all tests
npm run test:all

🤝 Contributing

We welcome contributions! Please follow these steps:

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing-feature)
💾 Commit your changes (git commit -m 'Add amazing feature')
📤 Push to the branch (git push origin feature/amazing-feature)
🔄 Open a Pull Request

Code Standards

✅ Follow ESLint configuration
📝 Add comments for complex logic
🧪 Write tests for new features
📚 Update documentation

📖 API Documentation

📚 Comprehensive Documentation

🏠 Documentation Home: Browse All Docs
📊 API Reference: Development Docs
🔧 Setup Guides: Installation & Setup
🗄️ Database: Database Documentation
👥 Admin Guides: Admin Management
🎯 Features: Feature Specifications
🔧 Troubleshooting: Common Issues & Fixes

🛠️ Development Resources

🏛️ Museum Admin API: Available in /server/routes/museumAdmin.js
🔐 Authentication API: Available in /server/routes/auth.js
📜 Scripts: Automation Scripts

🐛 Troubleshooting

Common Issues

MongoDB Connection Error:

# Check if MongoDB is running
sudo service mongod status

# Start MongoDB
sudo service mongod start

Port Already in Use:

# Kill process on port 3000 or 5000
sudo lsof -ti:3000 | xargs kill -9
sudo lsof -ti:5000 | xargs kill -9

Node Modules Issues:

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

🎯 Deployment

Production Deployment

Environment Variables: Set production values
Database: Use MongoDB Atlas for production
Frontend: Build optimized version
Security: Enable HTTPS and security headers

# Build frontend for production
cd client
npm run build

# Start production server
cd ../server
NODE_ENV=production npm start

Docker Deployment

docker-compose -f docker-compose.prod.yml up -d

## 👥 **Team & Support** **Project Lead**: [Your Name] **Get Help**: - 💬 [GitHub Discussions](https://github.com/Summer-Camp-Project/Project-for-G25/discussions) - 🐛 [Report Issues](https://github.com/Summer-Camp-Project/Project-for-G25/issues) - 📧 **Email**: [email protected] **Connect With Us**: [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?logo=linkedin)](https://linkedin.com/in/yourprofile) [![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?logo=twitter)](https://twitter.com/yourhandle) [![Website](https://img.shields.io/badge/Website-000000?logo=About.me)](https://yourwebsite.com) --- ### 📄 **License** This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ### 🙏 **Acknowledgments** - 🇪🇹 **Ethiopian Heritage**: For the rich cultural legacy we're preserving - 🏛️ **Museums**: For their collaboration and artifact contributions - 👥 **Open Source Community**: For the amazing tools and libraries - 🎓 **Educational Institutions**: For supporting heritage preservation --- **⭐ Star this repository if you find it helpful!** *"Preserving the past, inspiring the future"* 🏛️✨

Built With

batchfile
css
dockerfile
html
javascript
powershell
shell
typescript