Technical Flowcharts
Everything about campaigns and their functioning. 

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 ,  config/app.php ) 

 

 

 

 API Routing ( 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.,  auth ,  workspace ,  campaign ,  mailhub ). 

 

 

 

 Controllers ( app /Http/ Controllers /Api/ ): 

 

 Handle incoming API requests, validate data, and orchestrate responses. 

 Examples:  Api /Campaign/ CampaignController.php ,  Api /Workspace/ WorkspaceController.php ,  Api /Mailhub/ MailHubController.php . 

 

 

 

 Services ( app /Services/ ): 

 

 Contain the core business logic of the application. Controllers delegate tasks to these services. 

 Organized by domain (e.g.,  app /Services/ Campaign/CampaignService.php ,  app /Services/ Workspace/WorkspaceService.php ,  app /Services/ MailHub/MailboxService.php ). 

 Services for ESP (Email Service Provider) integrations like Gmail, Outlook, and SMTP are found in  app /Services/ ESP/ . 

 

 

 

 Models ( app /Models/ ): 

 

 Eloquent models representing database tables and their relationships. 

 Examples:  Campaign.php ,  Workspace.php ,  User .php ,  Emails.php . 

 

 

 

 Database: 

 

 The primary data store (likely MySQL or PostgreSQL, typical for Laravel). Migrations in  database /migrations/  define the schema. 

 

 

 

 Authentication & Authorization: 

 

 Laravel Passport  ( laravel /pass port ) is used for API token-based authentication. 

 Spatie Laravel Permission  ( spatie/laravel-permission ) manages roles and permissions. 

 Relevant controllers:  Api /Auth/ AuthController.php ,  Api /Role/ RoleController.php . 

 

 

 

 Email Campaign Management: 

 

 This is a major module with extensive logic for creating campaigns, managing leads ( CampaignLeads.php ), sequences ( CampaignSequences.php ), scheduling ( CampaignSchedule.php ), and tracking ( CampaignTrackEmail.php ). 

 Services like  ProcessCampaignService.php  handle the execution of campaigns. 

 

 

 

 Mailhub & ESP Integration: 

 

 Connects to external email services like Gmail ( google/apiclient ), Outlook ( dcblogdev/laravel-microsoft-graph ), and generic SMTP ( php- imap /php- imap ). 

 Services in  app /Services/ ESP/  and  app /Services/ MailHub/  manage fetching, sending, and organizing emails. 

 Webhooks (e.g.,  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 ). 

 

 

 

 Background Processing: 

 

 Laravel Horizon  ( laravel/horizon ) 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 ) is used as the Redis client. 

 

 

 

 Payment & Subscriptions: 

 

 Laravel Cashier  ( laravel/cashier ) is integrated for handling subscriptions and payments, likely with Stripe. 

 Models:  Plans.php ,  Payments.php ,  UserCredits.php . 

 Controllers:  Api /Payment/ PaymentController.php . 

 

 

 

 Onboarding & User Experience: 

 

 Features to guide new users, potentially using AI for campaign generation ( openai-php/ client ). 

 Controllers:  Api /Boarding/ OnboardingController.php . 

 

 

 

 Logging, Debugging & API Documentation: 

 

 Sentry  ( sentry/sentry-laravel ) for error tracking. 

 Laravel Telescope  ( laravel/telescope ) for local debugging (though potentially disabled in  extra .laravel .dont-discover  in  composer.json ). 

 Dedoc Scramble  ( dedoc/scramble ) for API documentation generation. 

 OwenIt Laravel Auditing  ( owen- it /laravel-auditing ) for tracking model changes. 

 

 

 

 3. Interaction Flow (Simplified) 

 

 

 

 The  React front-end  interacts with the Parakeet API by making HTTP requests to defined endpoints. 

 API Routes  map these requests to specific  Controller  methods. 

 Controllers  validate input and delegate business logic to  Services . 

 Services  perform operations, interacting with  Models  (which represent database tables) for data persistence and retrieval. 

 For long-running tasks (e.g., sending email campaigns), Services dispatch jobs to the  Background Queue  (managed by Horizon and Redis). 

 Services also handle communication with  External Integrations  like Gmail, Outlook, Stripe, etc. 

 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.

Flow Diagrams

Campaign Sending flowchart