# Parakeet API: High-Level Codebase Overview

**1. Project Purpose**

The Parakeet API is the backend system for the Parakeet application, a platform designed to streamline email outreach and management. It's built using **PHP** and the **Laravel framework (version 10.x)**, serving a **React-based front-end**.

The core functionalities include:

- **Email Campaign Management:** Enabling users to create, schedule, send, and track outreach email campaigns using multiple integrated email accounts.
- **Workspaces:** Providing a collaborative environment where users can organize their projects, team members, and associated email accounts.
- **Mailhub:** A centralized inbox feature that allows users to read, manage, and organize emails from all their connected accounts in one place.

**2. Main Components and Interactions**

The application follows a standard Laravel structure, leveraging its Model-View-Controller (MVC) pattern, though for an API, the "View" is primarily the JSON response. Key components include:

- **Core Framework & Language:**
    
    
    - **PHP ^8.1**
    - **Laravel Framework 10.x**: Provides the foundational structure, routing, ORM (Eloquent), authentication, and other essential web development features. ([`composer.json`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/composer.json), [`config/app.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/config/app.php))
- **API Routing ([`routes<span class="hljs-regexp">/routes/</span>api.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/routes/routes/api.php)):**
    
    
    - Defines all the accessible API endpoints. Requests from the React front-end are directed here.
    - Routes are grouped by functionality (e.g., `<span class="hljs-attribute">auth</span>`, `<span class="hljs-attribute">workspace</span>`, `<span class="hljs-attribute">campaign</span>`, `<span class="hljs-attribute">mailhub</span>`).
- **Controllers (`app<span class="hljs-regexp">/Http/</span>Controllers<span class="hljs-regexp">/Api/</span>`):**
    
    
    - Handle incoming API requests, validate data, and orchestrate responses.
    - Examples: [`Api<span class="hljs-regexp">/Campaign/</span>CampaignController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Campaign/CampaignController.php), [`Api<span class="hljs-regexp">/Workspace/</span>WorkspaceController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Workspace/WorkspaceController.php), [`Api<span class="hljs-regexp">/Mailhub/</span>MailHubController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Mailhub/MailHubController.php).
- **Services (`app<span class="hljs-regexp">/Services/</span>`):**
    
    
    - Contain the core business logic of the application. Controllers delegate tasks to these services.
    - Organized by domain (e.g., [`app<span class="hljs-regexp">/Services/</span>Campaign/CampaignService.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Services/Campaign/CampaignService.php), [`app<span class="hljs-regexp">/Services/</span>Workspace/WorkspaceService.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Services/Workspace/WorkspaceService.php), [`app<span class="hljs-regexp">/Services/</span>MailHub/MailboxService.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Services/MailHub/MailboxService.php)).
    - Services for ESP (Email Service Provider) integrations like Gmail, Outlook, and SMTP are found in `app<span class="hljs-regexp">/Services/</span>ESP/`.
- **Models (`app<span class="hljs-regexp">/Models/</span>`):**
    
    
    - Eloquent models representing database tables and their relationships.
    - Examples: [`Campaign.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/Campaign.php), [`Workspace.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/Workspace.php), [`<span class="hljs-keyword">User</span>.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/User.php), [`Emails.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/Emails.php).
- **Database:**
    
    
    - The primary data store (likely MySQL or PostgreSQL, typical for Laravel). Migrations in `database<span class="hljs-regexp">/migrations/</span>` define the schema.
- **Authentication &amp; Authorization:**
    
    
    - **Laravel Passport** ([`<span class="hljs-title">laravel</span>/pass<span class="hljs-keyword">port</span>`](https://internal-docs.parakeet.io/composer.json:19)) is used for API token-based authentication.
    - **Spatie Laravel Permission** ([`spatie/laravel-permission`](https://internal-docs.parakeet.io/composer.json:32)) manages roles and permissions.
    - Relevant controllers: [`Api<span class="hljs-regexp">/Auth/</span>AuthController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Auth/AuthController.php), [`Api<span class="hljs-regexp">/Role/</span>RoleController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Role/RoleController.php).
- **Email Campaign Management:**
    
    
    - This is a major module with extensive logic for creating campaigns, managing leads ([`CampaignLeads.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/CampaignLeads.php)), sequences ([`CampaignSequences.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/CampaignSequences.php)), scheduling ([`CampaignSchedule.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/CampaignSchedule.php)), and tracking ([`CampaignTrackEmail.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/CampaignTrackEmail.php)).
    - Services like [`ProcessCampaignService.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Services/ProcessCampaign/ProcessCampaignService.php) handle the execution of campaigns.
- **Mailhub &amp; ESP Integration:**
    
    
    - Connects to external email services like Gmail ([`google/apiclient`](https://internal-docs.parakeet.io/composer.json:12)), Outlook ([`dcblogdev/laravel-microsoft-graph`](https://internal-docs.parakeet.io/composer.json:9)), and generic SMTP ([`php-<span class="hljs-keyword">imap</span>/php-<span class="hljs-keyword">imap</span>`](https://internal-docs.parakeet.io/composer.json:28)).
    - Services in `app<span class="hljs-regexp">/Services/</span>ESP/` and `app<span class="hljs-regexp">/Services/</span>MailHub/` manage fetching, sending, and organizing emails.
    - Webhooks (e.g., [`<span class="hljs-attribute">routes</span>/routes/api.php:<span class="hljs-number">73</span>`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/routes/routes/api.php:73) for Gmail) are used for real-time email updates.
- **Workspaces:**
    
    
    - Allows users to manage distinct environments with their own accounts, campaigns, and team members ([`WorkspaceUsers.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/WorkspaceUsers.php)).
- **Background Processing:**
    
    
    - **Laravel Horizon** ([`laravel/horizon`](https://internal-docs.parakeet.io/composer.json:18)) is used for managing Redis queues. This is crucial for handling time-consuming tasks like sending email blasts, email warming, and processing incoming emails without blocking user requests. **Predis** ([`predis/predis`](https://internal-docs.parakeet.io/composer.json:29)) is used as the Redis client.
- **Payment &amp; Subscriptions:**
    
    
    - **Laravel Cashier** ([`laravel/cashier`](https://internal-docs.parakeet.io/composer.json:16)) is integrated for handling subscriptions and payments, likely with Stripe.
    - Models: [`Plans.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/Plans.php), [`Payments.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/Payments.php), [`UserCredits.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Models/UserCredits.php).
    - Controllers: [`Api<span class="hljs-regexp">/Payment/</span>PaymentController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Payment/PaymentController.php).
- **Onboarding &amp; User Experience:**
    
    
    - Features to guide new users, potentially using AI for campaign generation ([`openai-php/<span class="hljs-keyword">client</span>`](https://internal-docs.parakeet.io/composer.json:26)).
    - Controllers: [`Api<span class="hljs-regexp">/Boarding/</span>OnboardingController.php`](https://file+.vscode-resource.vscode-cdn.net/Users/vivek/www/parakeet/api/app/Http/Controllers/Api/Boarding/OnboardingController.php).
- **Logging, Debugging &amp; API Documentation:**
    
    
    - **Sentry** ([`sentry/sentry-laravel`](https://internal-docs.parakeet.io/composer.json:30)) for error tracking.
    - **Laravel Telescope** ([`laravel/telescope`](https://internal-docs.parakeet.io/composer.json:21)) for local debugging (though potentially disabled in `extra<span class="hljs-selector-class">.laravel</span>.dont-discover` in [`composer.json`](https://internal-docs.parakeet.io/composer.json:78)).
    - **Dedoc Scramble** ([`dedoc/scramble`](https://internal-docs.parakeet.io/composer.json:37)) for API documentation generation.
    - **OwenIt Laravel Auditing** ([`owen-<span class="hljs-keyword">it</span>/laravel-auditing`](https://internal-docs.parakeet.io/composer.json:27)) for tracking model changes.

**3. Interaction Flow (Simplified)**

<div drawio-diagram="14"><img src="https://internal-docs.parakeet.io/uploads/images/drawio/2025-06/C3cxARSShUyeTRbo-drawing-1-1749562889.png" alt=""/></div>

<div class="snippet-clipboard-content notranslate position-relative overflow-auto" id="bkmrk--2"></div>1. The **React front-end** interacts with the Parakeet API by making HTTP requests to defined endpoints.
2. **API Routes** map these requests to specific **Controller** methods.
3. **Controllers** validate input and delegate business logic to **Services**.
4. **Services** perform operations, interacting with **Models** (which represent database tables) for data persistence and retrieval.
5. For long-running tasks (e.g., sending email campaigns), Services dispatch jobs to the **Background Queue** (managed by Horizon and Redis).
6. Services also handle communication with **External Integrations** like Gmail, Outlook, Stripe, etc.
7. Finally, Controllers return JSON responses to the front-end.

This overview should provide a solid understanding of the Parakeet API's architecture, its main components, and how they interact. The use of Laravel provides a robust and scalable foundation for the application's features.