Architecture
A deep dive into how Omega AI is structured, from request flow through the service layer to the Model Context Protocol integration.
Architecture Overview
Omega AI follows a layered Laravel architecture. Web requests flow through Laravel routing into controllers, which delegate business logic to dedicated service classes. The Filament admin panel provides the dashboard UI via Livewire components.
External chat traffic enters through API routes, passes through authentication and rate-limiting middleware, and is processed by the AiChatService which orchestrates conversation management, knowledge base retrieval via MCP resources, external AI API calls, and message persistence.
Subscription enforcement is handled by SubscriptionFeatureService with plan-based feature gating. The system uses MySQL for persistence, database-backed queues and caching, and Stripe for billing.
The architecture separates concerns between HTTP controllers (thin request handling), service classes (business logic), Filament resources (admin UI), and MCP resources (AI context delivery).
Modules
AI Assistants
Core module for creating and managing AI chat assistants with configurable system prompts, model settings, temperature, token limits, and activation controls.
- Name
app/Models/AiAssistant.php- Type
- Model
- Description
Eloquent model defining assistant attributes, relationships, and scopes.
- Name
app/Filament/Resources/AiAssistantResource.php- Type
- Filament Resource
- Description
Admin panel resource for CRUD operations on assistants.
Knowledge Base
Training data management for AI assistants. Supports text content, file uploads, and source URLs. Content is injected into the AI system prompt via MCP resources.
- Name
app/Models/KnowledgeBase.php- Type
- Model
- Description
Eloquent model for knowledge base entries with content, file paths, and source URLs.
- Name
app/Mcp/Resources/KnowledgeResource.php- Type
- MCP Resource
- Description
Delivers active knowledge base content to the AI during prompt construction.
Chat Engine
Orchestrates the AI conversation flow: session management, system prompt construction, external AI API integration, response parsing, and message persistence with token tracking.
- Name
app/Services/AiChatService.php- Type
- Service
- Description
Core service handling conversation orchestration, prompt building, and AI API communication.
- Name
app/Http/Controllers/ChatController.php- Type
- Controller
- Description
HTTP controller for API chat endpoints.
- Name
app/Http/Controllers/MockAiController.php- Type
- Controller
- Description
Fallback controller providing keyword-based responses when the AI service is unavailable.
API Layer
REST API with API key authentication, domain whitelisting, and message quota enforcement. Provides chat completions, assistant info, and conversation history endpoints.
- Name
routes/api.php- Type
- Routes
- Description
API route definitions for chat, assistant info, and history endpoints.
- Name
app/Models/ApiKey.php- Type
- Model
- Description
API key model with domain restrictions, expiration, and usage tracking.
- Name
app/Http/Middleware/CheckMessageLimit.php- Type
- Middleware
- Description
Enforces monthly message quotas based on subscription plan.
Billing & Subscriptions
Stripe-powered billing with three subscription tiers, one-time purchases, feature gating, monthly message quotas, and a self-service billing portal.
- Name
app/Services/SubscriptionFeatureService.php- Type
- Service
- Description
Subscription feature enforcement with cached quota counts.
- Name
app/Http/Controllers/SubscriptionController.php- Type
- Controller
- Description
Handles subscription purchase flows and billing portal access.
- Name
app/Enums/PlanFeature.php- Type
- Enum
- Description
Defines all gated features (assistant limits, API access, branding, etc.).
- Name
app/Enums/PlanFeatureLimits.php- Type
- Enum
- Description
Defines per-tier limits for each feature.
Admin Dashboard
Filament 4 admin panel with resource management, billing info, widget instructions, health checks, log viewing, and role-based access control.
- Name
app/Providers/Filament/AppPanelProvider.php- Type
- Provider
- Description
Filament panel configuration, navigation, and middleware registration.
- Name
app/Filament/Pages/- Type
- Pages
- Description
Dashboard, BillingInformation, HealthCheckResults, ViewLog, WidgetInstructions.
- Name
app/Filament/Resources/- Type
- Resources
- Description
AiAssistants, ApiKeys, KnowledgeBases, Products, Users, Roles, Activities, Emails.
Monitoring & Observability
Health checks, activity logging, email/SMS delivery logs, application log viewer, and Sentry integration for error tracking.
- Name
config/health.php- Type
- Config
- Description
Spatie Health check configuration.
- Name
app/Filament/Pages/HealthCheckResults.php- Type
- Page
- Description
Dashboard page displaying health check results and history.
- Name
app/Filament/Pages/ViewLog.php- Type
- Page
- Description
Application log viewer in the admin panel.
MCP Server
The Model Context Protocol (MCP) server is a key architectural component that provides structured context to the AI during prompt construction. It is implemented as a local Laravel MCP server with dedicated resource classes.
How it works
When a chat message is processed, the AiChatService queries the MCP server to gather all relevant context for the AI prompt. The server responds with structured data from two resource types:
- RulesResource -- Supplies the assistant's configuration including system prompt, behavior rules, and instructions
- KnowledgeResource -- Delivers all active knowledge base content associated with the assistant
This context is compiled into the system prompt sent to the external AI API, ensuring responses are grounded in the assistant's training data.
Key Files
- Name
app/Mcp/Servers/LocalServer.php- Type
- MCP Server
- Description
The main MCP server class that registers resources and handles context requests.
- Name
app/Mcp/Resources/RulesResource.php- Type
- MCP Resource
- Description
Provides assistant configuration, system prompt, and behavior rules.
- Name
app/Mcp/Resources/KnowledgeResource.php- Type
- MCP Resource
- Description
Provides active knowledge base entries for the requested assistant.
- Name
routes/ai.php- Type
- Routes
- Description
MCP server route registration.
The MCP server runs locally within the Laravel application. It does not expose external endpoints -- it is consumed internally by the AiChatService during prompt construction.