📄 Viewing: architecture.md
# System Architecture
## Architectural Pattern
The application follows the **Model-View-Controller (MVC)** architectural pattern, leveraging the Laravel framework's capabilities to separate concerns effectively.
- **Model**: Represents the logical structure of data (e.g., `Campaign`, `Contact`, `User`). Managed via Eloquent ORM.
- **View**: The presentation layer using Blade templates and Vue.js components (`resources/views`, `resources/js`).
- **Controller**: Handles user input and interactions (`app/Http/Controllers`).
## High-Level Components
### 1. Application Layer
- **Middleware**: authenticates users and handles Cross-Origin Resource Sharing (CORS).
- **Controllers**: Orchestrates flow between Models and Views. Key controllers include `CampaignController` and `SmsController`.
### 2. Service Layer
- **Mail/SMS Services**: Abstract implementation for dispatching messages via external providers.
- **Jobs & Queues**: Asynchronous processing for high-volume email/SMS sending to prevent request timeouts.
### 3. Data Layer
- **MySQL Database**: Stores relational data.
- **Redis (Optional)**: Can be used for queue management and caching.
## Data Flow
The typical control flow for a campaign dispatch is as follows:
1. **User Request**: Admin initiates a campaign via the Dashboard.
2. **Validation**: Request data is validated against rules (e.g., valid template, sufficient credits).
3. **Job Dispatch**: The controller pushes a `SendBatchEmail` job to the queue.
4. **Worker Processing**:
- The Queue Worker picks up the job.
- It iterates through selected contacts.
- It calls the configured Provider API (e.g., Mailgun/Twilio).
- It logs the result in `SmsLog` or `MailLog` tables.
## Artificial Intelligence & Physics Engine
**Status**: Not Present
Based on a strict analysis of the codebase, this project **does not currently incorporate** any Generative AI models (such as Gemini) or Physics Engines.
- **Generative AI**: No references to LLM APIs, embeddings, or inference logic were found in the `app/` directory or `composer.json`.
- **Physics Engine**: No physics libraries (e.g., Box2D, Ammo.js) or spatial rendering logic (WebGPU) were detected.
The system operates as a purely **deterministic** application where outputs are strictly derived from inputs and predefined logic rules.
### Mathematical Logic
While no complex physical simulations are present, the system employs deterministic arithmetic for billing and rate limiting.
**Cost Calculation Model:**
The cost $C$ for a campaign is calculated as:
$$ C = \sum_{i=1}^{N} (R_{provider} + M_{markup}) $$
Where:
- $N$ is the number of recipients.
- $R_{provider}$ is the base rate charged by the gateway (e.g., Twilio).
- $M_{markup}$ is the platform fee added by the Admin.
**Rate Limiting:**
To comply with API limits, the dispatch rate $R_d$ is constrained by:
$$ R_d \le \min(L_{provider}, L_{plan}) $$
Where:
- $L_{provider}$ is the external provider's throughput limit.
- $L_{plan}$ is the user's subscription plan limit per hour.
## Infrastructure Constraints
- **GPU Requirements**: None. Use of GPU-based rendering is not supported or required.
- **Scaling**: Horizontal scaling is achieved by adding more Queue Workers, not by GPU acceleration.
NovaShell
🛸 NovaShell — Cyber Yellow Mode