38960-vm/SETUP.md

Project Setup Guide

This guide provides step-by-step instructions to set up, configure, and run the Hospital Management System.

Prerequisites

• PHP: Version 8.0 or higher.
• Database: MariaDB 10.x or MySQL 5.7+.
• Web Server: Apache 2.4+ (with mod_rewrite enabled).
• Composer: (Optional) For dependency management if using third-party packages in the future.

Installation Steps

1. Clone the Repository

   git clone <repository_url>
   cd <project_directory>
   

2. Configure Web Server

   • Point your Apache VirtualHost DocumentRoot to the project directory.
   • Ensure the directory has appropriate permissions (e.g., www-data user).
   • Enable .htaccess overrides if applicable.

3. Database Setup

   • Create a new MySQL/MariaDB database (e.g., hospital_db).
   • Import the database schema and seed data. You can do this by running the initialization script or importing SQL files:
     • Option A (Script): Run php install.php from the command line (ensure db/config.php is configured first).
     • Option B (Manual): Import files from db/migrations/ in chronological order using a tool like phpMyAdmin or CLI.

4. Configuration Files

   • Database: Edit db/config.php to match your database credentials:

     define('DB_HOST', '127.0.0.1');
     define('DB_NAME', 'your_db_name');
     define('DB_USER', 'your_db_user');
     define('DB_PASS', 'your_db_password');
     

Configuration & Environment Variables

The application uses a mix of PHP constants and environment variables for configuration.

Email Configuration (mail/config.php)

The application uses PHPMailer. Configure the following environment variables (in your server config or .env file):

• MAIL_TRANSPORT: smtp (default)
• SMTP_HOST: e.g., smtp.gmail.com
• SMTP_PORT: e.g., 587
• SMTP_SECURE: tls or ssl
• SMTP_USER: Your email address
• SMTP_PASS: Your email password or App Password
• MAIL_FROM: Sender email address
• MAIL_FROM_NAME: Sender name (e.g., "Hospital Admin")

AI Integration (ai/config.php)

The system uses an AI proxy for features like "AI Suggestion" in visit forms and the Telegram bot.

• Config File: ai/config.php
• Key Settings: base_url, project_uuid.
• Usage: See ai/LocalAIApi.php.

Telegram Integration

The system includes a Telegram bot for answering FAQs (api/telegram_webhook.php).

1. Create a Bot: Talk to @BotFather on Telegram to create a bot and get a Token.
2. Save Token: Insert the token into the settings table in your database:

   INSERT INTO settings (setting_key, setting_value) VALUES ('telegram_token', 'YOUR_TELEGRAM_BOT_TOKEN');
   

3. Set Webhook: Configure the webhook URL for your bot:

   https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://<YOUR_DOMAIN>/api/telegram_webhook.php
   

Integrations & Libraries

Frontend (CDN)

The project relies on the following CDN-hosted libraries. Ensure you have an active internet connection.

• Framework: Bootstrap 5.3.0
• Icons: Bootstrap Icons 1.10.5
• Fonts: Google Fonts (Inter, Tajawal)
• Forms:
  • Select2 4.1.0 (with Bootstrap 5 theme)
  • Summernote Lite 0.8.18 (Rich Text Editor)
  • Flatpickr (Date/Time picker)
  • Inputmask 5.0.7 (Input formatting)
• Utilities:
  • jQuery 3.6.0
  • Ui-Avatars (User avatars)
  • JsBarcode 3.11.5 (Patient labels)

Backend Services

• Email: mail/MailService.php (Wraps PHPMailer).
• AI: ai/LocalAIApi.php (Handles OpenAI requests via proxy).
• Reporting: includes/SimpleXLSX.php (Excel export support).

Default Credentials

If you used the provided migration scripts (20260321_create_auth_system.sql), the default administrator account is:

• Email: admin@hospital.com
• Password: admin123
• Role: Administrator

Note: Change this password immediately after logging in.

Troubleshooting

• Database Connection Error: Check db/config.php credentials. Ensure the database server is running.
• Email Not Sending: Verify SMTP settings in mail/config.php or environment variables. Check server logs for connection timeouts.
• AI Features Not Working: Ensure the server can reach the AI proxy endpoint defined in ai/config.php.
• Telegram Bot Not Responding: Verify the telegram_token in the settings table and ensure the webhook URL is accessible from the public internet (HTTPS required).