Application Architecture¶
Document Version: 1.1 Last Updated: 2026-01-09 Purpose: Technical overview of Vellocity platform application architecture
Overview¶
Vellocity is an AI-powered SaaS platform built for AWS ISV (Independent Software Vendor) Partners to execute Go-To-Market (GTM) campaigns. The platform focuses on demand generation, co-sell campaigns, and partner collaboration using AI-driven workflow automation.
Technology Stack¶
| Layer | Technology | Purpose |
|---|---|---|
| Backend | PHP 8.2 / Laravel 10 | MVC framework, API, business logic |
| Frontend | Alpine.js 3.15 + Livewire 3 | Reactive UI components |
| Styling | Tailwind CSS 3.4 | Utility-first CSS framework |
| Build | Vite 5.4 | Frontend asset bundling |
| Database | Aurora MySQL Serverless v2 | Primary relational storage |
| Cache | Redis (ElastiCache) | Sessions, cache, queues |
| Real-time | Pusher + Laravel Echo | WebSocket communication |
| AI Engine | AWS Bedrock (Claude, Nova, SD) | Text/image generation |
Directory Structure¶
vell-main/
├── app/ # Core application code
│ ├── Extensions/ # Feature modules (33+ extensions)
│ ├── Domains/ # Business logic domains
│ ├── Http/ # Controllers, middleware, requests
│ ├── Models/ # Eloquent ORM models (100+)
│ ├── Services/ # Business logic services
│ ├── Jobs/ # Async background jobs
│ ├── Events/ # Event dispatchers
│ ├── Policies/ # Authorization policies
│ └── Concerns/ # Shared model traits
├── routes/ # Route definitions
│ ├── web.php # Web routes
│ ├── api.php # API routes (v1)
│ ├── panel.php # Dashboard routes
│ └── webhooks.php # Webhook routes
├── resources/ # Frontend assets
│ ├── views/ # Blade templates
│ ├── css/ # SCSS stylesheets
│ └── js/ # JavaScript modules
├── database/ # Migrations, seeders, factories
├── config/ # Laravel configuration (40+ files)
├── cloudformation/ # AWS Infrastructure as Code
└── public/ # Web server root
Core Architecture Pattern¶
Vellocity uses a modular monolith architecture with a plugin-based extension system:
┌─────────────────────────────────────────────────────────────────────┐
│ VELLOCITY PLATFORM │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ EXTENSION LAYER │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Content │ │ Social │ │ AWS │ │ HubSpot │ │ │
│ │ │ Manager │ │ Media │ │Marketplace │ │Integration │ │ │
│ │ │ (AgentCore)│ │ Publisher │ │ Connector │ │ (CRM) │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Canvas │ │ AI │ │ AI │ │ Xero │ │ │
│ │ │ Editor │ │ Chat │ │Presentation│ │ Accounting │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │
│ │ + 25 more extensions │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ DOMAIN LAYER │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ │
│ │ │ Engine │ │ Marketplace │ │ Workflow │ │ │
│ │ │ (AI Drivers) │ │ (Listings) │ │ (Execution) │ │ │
│ │ └─────────────────┘ └─────────────────┘ └────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ LARAVEL CORE │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ HTTP │ │ Eloquent │ │ Queue │ │ Events │ │ │
│ │ │ Layer │ │ ORM │ │ System │ │ System │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ DATA LAYER │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Aurora MySQL │ │ Redis │ │ S3 │ │ │
│ │ │ (Primary) │ │ (Cache) │ │ (Storage) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Extension System¶
Each extension is a self-contained feature module with its own:
- Controllers - HTTP request handlers
- Models - Database entities
- Services - Business logic
- Migrations - Database schema
- Views - UI templates
- Routes - URL endpoints
Extension Structure¶
app/Extensions/{ExtensionName}/
├── System/
│ ├── Http/
│ │ ├── Controllers/ # Route handlers
│ │ └── Requests/ # Form validation
│ ├── Models/ # Eloquent models
│ ├── Services/ # Business logic
│ ├── Jobs/ # Background jobs
│ ├── Mail/ # Email templates
│ └── Database/
│ ├── Migrations/ # Schema changes
│ └── Seeders/ # Initial data
├── resources/
│ ├── views/ # Blade templates
│ └── lang/ # Translations
└── extension.json # Metadata
Key Extensions¶
| Extension | Purpose | Key Features |
|---|---|---|
| ContentManager | GTM workflow orchestration | AgentCore, capability registry, workflow planning |
| SocialMedia | Social publishing | LinkedIn, Twitter, scheduling |
| AWSMarketplace | Marketplace integration | Listings, agreements, SEO |
| AIChatPro | Conversational AI | Chat interface, history |
| Canvas | Content creation | Rich text editor, templates |
| AiPresentation | Slide generation | AI-powered presentations |
| Hubspot | CRM sync | Contact, deal sync |
AgentCore: AI Workflow Engine¶
The ContentManager extension contains AgentCore, the central AI workflow orchestration system:
┌─────────────────────────────────────────────────────────────────────┐
│ AGENTCORE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ USER REQUEST │ │
│ │ "Create a blog post about our product launch" │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ WORKFLOW PLANNER │ │
│ │ Uses Claude to break request into execution steps │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ Plan: │ │ │
│ │ │ 1. Gather brand context │ │ │
│ │ │ 2. Generate blog content │ │ │
│ │ │ 3. Create featured image │ │ │
│ │ │ 4. Optimize for SEO │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ BRAND VOICE CONTEXT BUILDER │ │
│ │ Injects company tone, audience, and brand guidelines │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ CAPABILITY REGISTRY │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Generate │ │ Generate │ │ Analyze │ │ │
│ │ │ Text │ │ Image │ │ Content │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Co-Sell │ │ Joint GTM │ │ AWS │ │ │
│ │ │ Matching │ │ Planner │ │ CleanRooms │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ + 15 more capabilities │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ AGENT ORCHESTRATOR │ │
│ │ Executes steps sequentially, tracks progress │ │
│ │ ┌──────────────────────────────────────────────────────────┐ │ │
│ │ │ Step 1: [✓] Brand context loaded │ │ │
│ │ │ Step 2: [✓] Blog content generated (1,200 words) │ │ │
│ │ │ Step 3: [→] Generating featured image... │ │ │
│ │ │ Step 4: [ ] SEO optimization pending │ │ │
│ │ └──────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ RESULTS │ │
│ │ AgentExecution model stores: │ │
│ │ - Generated content │ │
│ │ - Media assets (S3) │ │
│ │ - Credits/tokens used │ │
│ │ - Execution duration │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Key AgentCore Services¶
| Service | Purpose | Location |
|---|---|---|
AgentOrchestrator |
Main workflow coordinator | Extensions/ContentManager/System/Services/AgentCore/ |
WorkflowPlanner |
Uses Claude for step planning | Extensions/ContentManager/System/Services/AgentCore/ |
BrandVoiceContextBuilder |
Injects company context | Extensions/ContentManager/System/Services/AgentCore/ |
CapabilityRegistry |
Manages available capabilities | Extensions/ContentManager/System/Services/AgentCore/ |
AgentMemoryService |
AWS Bedrock Agent memory | Extensions/ContentManager/System/Services/AgentCore/ |
Data Flow¶
Request Lifecycle¶
┌─────────────────────────────────────────────────────────────────────┐
│ REQUEST LIFECYCLE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ │
│ │ Client │ │
│ │ Browser │ │
│ └─────┬──────┘ │
│ │ HTTPS │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MIDDLEWARE STACK │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ TLS │→│ Auth │→│ CORS │→│ Rate │ │ │
│ │ │Terminate │ │(Passport)│ │(if API) │ │ Limit │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ROUTING │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ web.php │ │ api.php │ │panel.php │ │webhooks │ │ │
│ │ │ (Views) │ │ (JSON) │ │(Dashboard│ │ .php │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CONTROLLER │ │
│ │ 1. Validate request (FormRequest) │ │
│ │ 2. Call service layer │ │
│ │ 3. Return response (JSON/View) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ SERVICE LAYER │ │
│ │ - Business logic │ │
│ │ - External API calls (Bedrock, Marketplace) │ │
│ │ - Job dispatching │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MODEL LAYER │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Aurora MySQL │ │ Redis │ │ S3 │ │ │
│ │ │ (Eloquent) │ │ (Cache) │ │ (Storage) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
AI Workflow Execution¶
┌─────────────────────────────────────────────────────────────────────┐
│ AI WORKFLOW EXECUTION │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ │
│ │ User │ "Generate a co-sell proposal for Partner X" │
│ └─────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AGENTCONTROLLER.EXECUTE() │ │
│ │ - Validate agent configuration │ │
│ │ - Check user credits/permissions │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PROCESSAGENTWORKFLOWJOB (Async) │ │
│ │ - Queued on Redis │ │
│ │ - Handles long-running operations │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AGENTORCHESTRATOR.EXECUTE() │ │
│ │ │ │
│ │ 1. Build context (Brand Voice) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 2. Retrieve memory (Bedrock Agent Memory) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 3. Plan workflow (Claude) │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ Analyze request → Select capabilities → Order │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 4. Execute steps sequentially │ │
│ │ ┌───────────────────────────────────────────────────┐ │ │
│ │ │ For each step: │ │ │
│ │ │ - Load capability handler │ │ │
│ │ │ - Execute with context │ │ │
│ │ │ - Store intermediate results │ │ │
│ │ │ - Update progress (WebSocket) │ │ │
│ │ └───────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 5. Track usage (Marketplace metering) │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ 6. Persist results to AgentExecution │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ RESULTS STORED │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │AgentExecution│ │ UserOpenai │ │ S3 │ │ │
│ │ │ (status, │ │ (content │ │ (media │ │ │
│ │ │plan, results)│ │ records) │ │ assets) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Authentication & Authorization¶
Authentication Guards¶
┌─────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION SYSTEM │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ AUTH GUARDS │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │
│ │ │ WEB GUARD │ │ API GUARD │ │ COGNITO │ │ │
│ │ │ (Session) │ │ (Passport) │ │ (SSO) │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Traditional │ │ OAuth 2.0 │ │ Enterprise │ │ │
│ │ │ web pages │ │ API tokens │ │ deployments │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ SOCIAL LOGIN │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Google │ │ Apple │ │ GitHub │ │ Facebook │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Authorization (Role-Based Access)¶
| Role | Permissions |
|---|---|
SUPER_ADMIN |
Full system access, manage all users |
ADMIN |
Manage admins, view all data |
USER |
Standard user access |
TEAM_MEMBER |
Access within team context |
Authorization is enforced through: - Laravel Gates - Global authorization checks - Policies - Model-specific authorization (AgentPolicy, etc.) - Spatie Permission - Granular role/permission management
Team-Centric Architecture¶
Vellocity uses a team-centric multi-tenancy model where Team is the primary tenant, not User. This enables collaboration where multiple users can work together on shared resources.
Architecture Diagram¶
┌─────────────────────────────────────────────────────────────────────┐
│ TEAM-CENTRIC DATA MODEL │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ TEAM (Tenant) │ │
│ │ - Primary organizational unit │ │
│ │ - Owns: Companies, Partners, Subscriptions, Credits │ │
│ │ - Has: entity_credits, training_data_opt_out, analytics_opt_in │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────┴──────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ TEAM_MEMBER │ │ COMPANY │ │
│ │ (Pivot) │ │ (Brand) │ │
│ │ │ │ │ │
│ │ - role: owner │ │ - team_id (FK) │ │
│ │ admin │ │ - user_id (FK) │ │
│ │ member │ │ - brand_voice │ │
│ │ viewer │ │ │ │
│ │ - status │ └────────┬────────┘ │
│ │ - joined_at │ │ │
│ └────────┬────────┘ │ │
│ │ ▼ │
│ ▼ ┌─────────────────┐ │
│ ┌─────────────────┐ │ PRODUCT │ │
│ │ USER │ │ (Listing) │ │
│ │ │ │ │ │
│ │ - active_team_id│ │ - team_id (FK) │ │
│ │ - teams() (M:M) │ │ - company_id │ │
│ │ - myCreatedTeam │ │ - user_id (FK) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Key Relationships¶
| Relationship | Type | Description |
|---|---|---|
| User → Teams | Many-to-Many | Via team_members pivot table |
| User → myCreatedTeam | One-to-One | Team where teams.user_id = users.id |
| User → activeTeam | Belongs-To | Current team context via active_team_id |
| Team → Companies | One-to-Many | Companies owned by the team |
| Team → Partners | One-to-Many | Co-sell partner profiles |
| Team → Members | One-to-Many | TeamMember records |
| Company → Products | One-to-Many | Products inherit team_id |
Multi-Team Membership¶
Users can belong to multiple teams via the TeamMember pivot:
// User model relationships
public function teams(): BelongsToMany
{
return $this->belongsToMany(Team::class, 'team_members')
->withPivot('role', 'status', 'joined_at')
->wherePivot('status', 'joined');
}
public function activeTeam(): ?Team
{
// Returns team based on active_team_id or fallback
}
public function setActiveTeam(Team $team): void
{
// Switch user's active team context
}
Team Member Roles¶
| Role | Permissions |
|---|---|
owner |
Full team management, billing, delete team |
admin |
Manage members, manage all resources |
member |
Create/edit own resources, view team resources |
viewer |
Read-only access to team resources |
BelongsToTeam Trait¶
Resources use the BelongsToTeam trait for consistent team scoping:
// Available on Company, Product, Partner models
use App\Models\Concerns\Team\BelongsToTeam;
class Company extends Model
{
use BelongsToTeam;
}
// Query scopes provided by trait:
Company::forTeam($teamId)->get(); // Filter by team
Company::accessibleByUser($user)->get(); // User's accessible companies
Company::accessibleByAnyTeam($user)->get(); // All teams user belongs to
Credit & Subscription Allocation¶
Credits and subscriptions are managed at the Team level:
┌─────────────────────────────────────────────────────────────────────┐
│ CREDIT FLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ SUBSCRIPTION │ ← Purchased by team owner │
│ │ (Plan-based) │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ TEAM │ ← Credits allocated to team │
│ │ entity_credits │ word_credit, image_credits, seo_credits │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ TEAM_MEMBER │ ← Optional per-member limits │
│ │ remaining_words │ allow_unlimited_credits flag │
│ │ remaining_images│ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Data Isolation Hierarchy¶
Data privacy settings cascade from User → Team → Company → Product:
| Level | Settings | Inheritance |
|---|---|---|
| User | training_data_opt_out, analytics_opt_in |
Base defaults |
| Team | Same fields (nullable) | Inherits from owner if null |
| Company | data_isolation_enabled, kb_cross_brand_sharing |
Inherits from team |
| Product | Same fields (nullable) | Inherits from company if null |
Database Schema¶
Core Tables¶
| Table | Purpose | Key Fields |
|---|---|---|
users |
User accounts | email, type, active_team_id, aws_credentials |
teams |
Team/organization | user_id (owner), entity_credits, allow_seats |
team_members |
User-Team pivot | team_id, user_id, role, status, joined_at |
companies |
Company/brand data | team_id, user_id, name, brand_voice |
products |
Product catalog | team_id, company_id, marketplace_sku |
plans |
Subscription plans | name, price, features, is_team_plan |
subscriptions |
Team subscriptions | user_id, plan_id, status |
user_usage_credits |
Credit tracking | user_id, credits, period |
Team Tables¶
| Table | Purpose | Key Fields |
|---|---|---|
teams |
Team organization | user_id, name, entity_credits, word_credit, training_data_opt_out |
team_members |
Team membership | team_id, user_id, role, status, remaining_words, remaining_images |
AgentCore Tables¶
| Table | Purpose |
|---|---|
ext_content_manager_agents |
Agent configurations |
ext_content_manager_agent_executions |
Workflow execution history |
ext_content_manager_agent_capabilities |
Available capabilities |
ext_content_manager_cosell_relationships |
Partner relationships |
ext_content_manager_cosell_plans |
Joint GTM plans |
Content Tables¶
| Table | Purpose |
|---|---|
user_openai_chats |
Chat conversations |
user_openai_chat_messages |
Individual messages |
user_openai |
Generated content records |
AI Engine Architecture¶
Engine Driver System¶
┌─────────────────────────────────────────────────────────────────────┐
│ AI ENGINE DRIVERS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ENGINE INTERFACE │ │
│ │ - generateText(prompt, options) │ │
│ │ - generateImage(prompt, options) │ │
│ │ - textToSpeech(text, options) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ BEDROCK │ │ OPENAI │ │ GEMINI │ │
│ │ DRIVER │ │ DRIVER │ │ DRIVER │ │
│ │ (Primary) │ │ (Optional) │ │ (Optional) │ │
│ │ │ │ │ │ │ │
│ │ Claude 3 │ │ GPT-4o │ │ Gemini 2.5 │ │
│ │ Nova │ │ DALL-E │ │ │ │
│ │ Stable Diff │ │ │ │ │ │
│ │ Polly │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Location: app/Domains/Engine/Drivers/ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Bedrock Integration¶
The primary AI engine uses AWS Bedrock:
| Model | Service | Use Case |
|---|---|---|
| Claude 3 (Haiku/Sonnet/Opus) | Bedrock | Text generation, planning |
| Claude Sonnet 4.5 | Bedrock | Advanced reasoning |
| Nova (Micro/Lite/Pro) | Bedrock | Cost-effective text |
| Stable Diffusion XL | Bedrock | Image generation |
| Amazon Polly | Polly | Text-to-speech |
Queue & Job System¶
Background jobs are processed through Redis queues:
┌─────────────────────────────────────────────────────────────────────┐
│ JOB PROCESSING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ JOB DISPATCH │ │
│ │ ProcessAgentWorkflowJob::dispatch($agent, $request) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ REDIS QUEUE │ │
│ │ ┌───────────────────────────────────────────────────────┐ │ │
│ │ │ default: [job1, job2, job3, ...] │ │ │
│ │ │ high: [priority_job, ...] │ │ │
│ │ │ low: [background_task, ...] │ │ │
│ │ └───────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ QUEUE WORKERS │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Worker 1 │ │ Worker 2 │ │ Worker n │ │ │
│ │ │ (EC2) │ │ (EC2) │ │ (EC2) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Common Jobs¶
| Job | Purpose |
|---|---|
ProcessAgentWorkflowJob |
Execute AI workflows |
SyncMarketplaceListingJob |
Sync AWS Marketplace data |
PublishToSocialJob |
Post to social media |
SendEmailNotificationJob |
Transactional emails |
Real-Time Features¶
WebSocket communication via Pusher + Laravel Echo:
┌─────────────────────────────────────────────────────────────────────┐
│ REAL-TIME UPDATES │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ LARAVEL (Server) │ │
│ │ event(new WorkflowProgressUpdated($execution, $progress)) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PUSHER │ │
│ │ Channel: private-workflow.{execution_id} │ │
│ │ Event: WorkflowProgressUpdated │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ BROWSER (Laravel Echo) │ │
│ │ Echo.private('workflow.' + id) │ │
│ │ .listen('WorkflowProgressUpdated', (e) => { │ │
│ │ updateProgressBar(e.progress); │ │
│ │ }); │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Security Patterns¶
Data Encryption¶
| Layer | Method |
|---|---|
| At-rest (DB) | Aurora encryption (KMS) |
| At-rest (Files) | S3 AES-256 |
| In-transit | TLS 1.2+ everywhere |
| Sensitive fields | Laravel Crypt facade |
Input Validation¶
- Form Requests - Validate all user input
- Eloquent - SQL injection prevention
- Blade - XSS protection (auto-escaping)
- CSRF - Token validation on forms
AWS Credentials¶
User AWS credentials are stored encrypted:
- aws_access_key_id (encrypted)
- aws_secret_access_key (encrypted)
- Cross-account access via IAM roles with External ID
Testing¶
| Framework | Location | Purpose |
|---|---|---|
| Pest | tests/ |
Unit & feature tests |
| PHPUnit | tests/ |
Alternative test runner |
| Laravel Dusk | tests/Browser/ |
Browser automation |
Run tests:
Key Configuration Files¶
| File | Purpose |
|---|---|
config/auth.php |
Authentication guards |
config/database.php |
Aurora MySQL connection |
config/cache.php |
Redis configuration |
config/queue.php |
Queue driver settings |
config/filesystems.php |
S3 storage config |
config/services.php |
External service keys |
Development Workflow¶
- Local Development: Laravel Sail or Valet
- Build:
npm run build(Vite) - Test:
php artisan test - Deploy: Push to GitHub → CodePipeline → CodeDeploy
References¶
- Extension System:
app/Extensions/ - AgentCore Services:
app/Extensions/ContentManager/System/Services/AgentCore/ - AI Drivers:
app/Domains/Engine/Drivers/ - Models:
app/Models/ - API Routes:
routes/api.php,routes/api_v1.php
Document generated: 2025-12-28