improve doc

Author: emnbdx

.env.example

@@ -1,8 +1,10 @@
 DBURL=localhost
+DBPORT=3306
 DBNAME=twitch
 DBUSER=root
 DBPASSWORD=
 DBPREFIX=sandbox_
+LOGLEVEL=DEBUG
 
 BLOB_URL=
 BLOB_CONNECTION_STRING=

README.md

@@ -8,8 +8,10 @@ This application manages Twitch widgets for streamers. It specifically supports
 
 ## Prerequisites
 To run this application, you will need:
-- PHP
+- PHP 8.3+
 - MySQL
+- Node.js (for frontend dependencies)
+- Composer (for PHP dependencies)
 
 ## Installation
 
@@ -20,7 +22,18 @@ git clone [repository-url]
 cd twitch-widget
 ```
 
-### Step 2: Configure Your Environment
+### Step 2: Install Dependencies
+Install PHP dependencies using Composer:
+```bash
+composer install
+```
+
+Install frontend dependencies using npm:
+```bash
+npm install
+```
+
+### Step 3: Configure Your Environment
 Copy the example environment file and then edit it with your specific configurations:
 ```bash
 cp .env.example .env
@@ -33,7 +46,7 @@ Database connection details
 API keys if applicable
 Any other environment-specific variables
 
-### Step 3: Run SQL Migrations
+### Step 4: Run SQL Migrations
 To set up your database, execute the SQL migrations provided:
 ```bash
 php migrations/run.php
@@ -60,3 +73,104 @@ ngrok http 8000
 
 This command will create a secure tunnel to your localhost server running on port 8000, allowing you to safely test your application's HTTPS functionality. Ensure that your application is running on port 8000 or adjust the port number in the command accordingly.
 Also update WEBSITE_DOMAIN from you env file
+
+## Architecture & Code Organization
+
+### Framework & Technologies
+- **Backend:** PHP 8.3 with Slim Framework 4
+- **Frontend:** Bootstrap 5.3, CountUp.js, Moment.js
+- **Database:** MySQL
+- **Template Engine:** Twig
+- **Dependency Injection:** PHP-DI
+- **Cloud Storage:** Azure Blob Storage
+- **Email Service:** Mailchimp Transactional (Mandrill)
+
+### Project Structure
+
+```
+twitch-widget/
+├── public/                 # Web root directory
+│   ├── css/               # Compiled CSS files
+│   ├── js/                # Compiled JavaScript files
+│   └── index.php          # Application entry point
+├── src/                   # Application source code
+│   ├── Controllers/       # Request handlers
+│   ├── Models/           # Data models
+│   ├── Repositories/     # Data access layer
+│   ├── Services/         # Business logic services
+│   ├── Middlewares/      # Request/response middleware
+│   └── views/            # Twig templates
+├── migrations/           # Database migration files
+└── vendor/              # Composer dependencies
+```
+
+### Key Components
+
+#### Controllers (`src/Controllers/`)
+- **HomeController:** Handles public pages (home, password reset)
+- **LoginController:** Manages authentication and OAuth flow
+- **AdminController:** Admin panel functionality
+- **ApiController:** API endpoints for external integrations
+- **WidgetController:** Widget rendering and data endpoints
+
+#### Models (`src/Models/`)
+- **User:** User account management
+- **Stream:** Stream configuration and data
+- **Event:** Event management
+- **WidgetAlert/WidgetDonation:** Widget-specific data models
+- **AccessToken/AuthorizationCode:** OAuth token management
+
+#### Repositories (`src/Repositories/`)
+- **UserRepository:** User data operations
+- **StreamRepository:** Stream data operations
+- **EventRepository:** Event data operations
+- **WidgetRepository:** Widget data operations
+- **FileManager:** File upload/management via Azure Blob Storage
+
+#### Services (`src/Services/`)
+- **ApiWrapper:** External API integrations and OAuth handling
+
+#### Middlewares (`src/Middlewares/`)
+- **AuthMiddleware:** Session-based authentication
+- **AuthAdminMiddleware:** Admin role verification
+- **AuthApiMiddleware:** API authentication
+
+### Widget System
+The application provides two main widget types:
+
+1. **Alert Widget** (`/widget-stream-alert/{id}`)
+   - Displays real-time donation alerts
+   - Updates via AJAX polling
+   - Customizable styling and animations
+
+2. **Donation Bar Widget** (`/widget-stream-donation/{id}`)
+   - Shows fundraising progress
+   - Real-time goal tracking
+   - Animated progress bars
+
+### Database Migrations
+Database schema is managed through SQL migration files in the `migrations/` directory:
+- `00-init-db.sql`: Initial database setup
+- `01-add-goal-widget-text.sql`: Widget text configuration
+- `02-add-user-table.sql`: User management
+- `03-update-widget-alert-box.sql`: Alert widget improvements
+- `04-new-bar.sql`: Donation bar widget
+- `05-manage-user-reset-pwd.sql`: Password reset functionality
+- `06-manage-event.sql`: Event management
+- `07-improve-user-rights.sql`: User permissions
+
+### Frontend Assets
+JavaScript and CSS files are organized in `public/js/` and `public/css/`:
+- **admin.js:** Admin panel functionality
+- **alert.js:** Alert widget logic
+- **event.js:** Event widget logic
+- **stream.js:** Stream management
+- **main.css:** Global styles
+
+### Environment Configuration
+Key environment variables include:
+- Database connection (DBURL, DBPORT, DBNAME, DBUSER, DBPASSWORD)
+- OAuth configuration (CLIENT_ID, CLIENT_SECRET, API_URL)
+- Azure Blob Storage (BLOB_CONNECTION_STRING, BLOB_URL)
+- Email service (MANDRILL_API)
+- Application domain (WEBSITE_DOMAIN)