Chapter 1 - Technology, Architecture, Setup and Maintenance

1. Technology Stack

Backend

• Language: PHP 8.2+.
• Framework: Laravel 12 (laravel/framework).
• ORM: Eloquent.
• Auth: session (Laravel).
• Authorisation: Spatie Permission (spatie/laravel-permission) and custom middleware.
• Media: Spatie MediaLibrary.
• IMAP: webklex/laravel-imap.
• OpenAI client: openai-php/client.
• HTTP client: Laravel Http facade + Guzzle (ZoomService directly).
• PDF export: dompdf/dompdf.
• Excel/spreadsheets: phpoffice/phpspreadsheet, phpoffice/phpword.
• PDF text: smalot/pdfparser.
• Arabic handling: khaled.alshamaa/ar-php.
• Payment & gateway libraries: Stripe, Razorpay, MercadoPago, Cashfree, PayTabs, Mollie, Coingate, Fedapay, Iyzipay, YooKassa (composer manifest list).
• Installer: rachidlaasri/laravel-installer.
• Impersonation: lab404/laravel-impersonate.
• Monitoring: larabug/larabug.

Frontend

• React 19, TypeScript 5.7, Tailwind CSS 4, Vite 6, Inertia.js 2 (react adapter), Ziggy 2 (routing), i18next 25, date-fns, FullCalendar 6, Tiptap 2, Radix UI, Headless UI, Recharts 3, react-markdown, react-barcode, qrcode, Stripe + React Stripe JS, react-hook-form not used (uses Inertia useForm), Sonner toasts.
• Eslint 9 flat + Prettier 3.

Database + storage

• MySQL/SQLite supported, Redis optional.
• File storage via S3 or local FILESYSTEM_DISK.

Build tools

• Vite 6 with SSR build.
• Prettier + Tailwind organize-import plugin.
• TypeScript (no emit, strict).
• ESLint 9.
• Pint for PHP (vendor).
• Pest/PHPUnit (no tests).

External systems

• Google Gemini + OpenAI; IMAP; WhatsApp (UltraMsg/Twilio); Slack; Telegram; Zoom; payments (33); S3.

2. Prerequisites (minimum)

• PHP 8.2+ with extensions: pdo_mysql/sqlite, mbstring, xml, curl, zip, gd, bcmath, intl, soap, imap, exif, pcntl, sodium. (See Dockerfile.)
• Composer.
• Node 18+ (Node/npm from Laravel vite).
• Database (MySQL or SQLite).
• Optional: Redis/SQS/AWS/S3, Nginx/Apache, SSL certificate, cron, outbound SMTP and IMAP access.
• No test runners installed project-side required.

3. Repository Structure (important paths)

app/                           # Backend PHP classes (Controllers, Models, Services, Middleware, Queue, Observers, Policies, Listeners, Events, Notifications, Jobs, Helpers, Repositories)
bootstrap/app.php              # Routing, middleware, exceptions
config/                        # 24 config files
database/                      # migrations(93), seeders(42), factories(3)
docs/                          # source files compiled into this volume
public/                        # web root index.php + hardcoded assets
resources/                     # JS app + Blade + languages
routes/                        # web.php, settings.php, auth.php, console.php
storage/                       # runtime cache/sessions/views/logs
tests/                         # NOT present (no project tests)
vendor/                        # Composer deps (gitignored)
node_modules/                  # (gitignored)

• bootstrap/cache and storage/framework/{cache, sessions, testing, views} are expected but may be absent until CLI bootstrap.
• public/build is gitignored; Vite output.
• build-ui/ remote build helper maintains separate SaaS-style builder flow.
• resources/views mainly blade wrapper + mail + installer component.

4. Architecture and Design Patterns

• Request → middleware (locale/appearance/concurrency/demo/workspace suspension) → route → controller → service → repository → model → database.
• Inertia: HandleInertiaRequests returns page mapping with data; prop flash for errors/plan warnings.
• Events/Listeners: 16 events × ~33 listener classes; mostly notification dispatch.
• Observers: WorkspaceObserver, UserObserver, TaskObserver, PlanObserver.
• Service layer: ProjectService, TaskService, UserService, WorkspaceService, etc.
• Repositories: interfaces in app/Repositories/Interfaces; implementations in app/Repositories.
• Storage: DynamicStorageService::configureDynamicDisks().
• Authorization: middleware or service checks.

5. Local Installation and Setup

Follow Laravel's standard + these concrete steps (never run on production without permission):

1. git clone repository into your web root.
2. composer install.
3. Ensure .env exists (the files are not committed; composer create-project step requires it via post-root-package-install). Given gap ".env.example is not tracked", copy your own baseline (see config reference). Set APP_KEY via php artisan key:generate.
4. Database create SQLite or MySQL; configure DB_... keys in .env.
5. php artisan migrate — applies 93 migrations. (php artisan db:seed for demo content.)
6. npm install and npm run build for asset generation.
7. Ensure storage/framework/cache/data, sessions, views, testing exist and writable.
8. php artisan storage:link for public/storage.
9. Configure queue driver and run php artisan queue:work --tries=3 --timeout=600.
10. Add cron entry for php artisan schedule:run.
11. Set IMAP variables when email feature needed.
12. Ingest TRY AI assistant via commands.
13. Start app: php artisan serve --host=0.0.0.0 --port=3150.

Docker option:

docker compose up --build

EXPOSES 3150 and 5173. Startup migrates and queue:1 process.

6. Environment Variables

Required for most builds

• APP_NAME, APP_ENV, APP_KEY, APP_URL, DB_CONNECTION (and corresponding DB creds), APP_DEBUG.
• Laravel config/app.php uses IS_DEMO, IS_SAAS to gate menus/build behaviour.
• PHP config defaults missing .env.example means an SRE must construct it manually (gap).
• VITE_APP_NAME optional for dev.
• SESSION_DRIVER, CACHE_STORE, QUEUE_CONNECTION with backing services as configured.

Payment gateways

• 33 environment keys lines (see config/payment settings.controller) based on naming convention (e.g. STRIPE_KEY, STRIPE_SECRET, PAYPAL_CLIENT_ID, etc.) — naming not listed in config file; derives from config patterns? Actually PaymentSettingController enumerates constants only in .env from reading getenv? Values entered via UI into database (table payment_settings), not environment necessarily. Better: all credentials are editable in Settings > Payment, stored in DB per user/workspace.
• Stripe JS VITE_KEY? Frontend uses stripe-js plus gateway forms under components/payment/invoices.

7. Database Technical Reference (high level)

Engine support

• MySQL then SQLite; custom types via Schema::.
• 93 migration files, comprehensive entities (85 models).
• Models: app/Models/*.php with relationships.

Eloquent relationships

• Uses hasMany, belongsToMany with pivot tables, belongsToOne.
• Uses SoftDeletes at least projects migration.
• Many uses pivot columns manually.

Security

• Migration users.id default UUID/int depends on framework 12 users.
• Slug unique.
• workspace_id scope int.

Integration

• Foreign keys declared; ON DELETE cascade not always.
• task_stage_id, bug_status_id default 1 if custom creation occurs (manual apps).
• workspace observer seeds default stages within code on creation.
• plan_id on user often nullable outside SaaS (isSaasMode()).
• Methods: PlanLimitService requires all counters/manual queries not based on SQL count? Not sure (scope).
• Where query scoped.

8. API Technical Reference (Application Routes)

The app does not have api.php (Inertia-bound). Data endpoints:

• /api/notifications, /api/media, /api/chatgpt/generate, /api/bugs/project-data, /api/ai-agent/*, /api/payment-settings/enabled, /api/invoices/{invoice}/payment-methods, /api/expense-dashboard/*, /api/budget-dashboard/*, /api/zoom-meetings/calendar, /api/projects/{id}/members, /api/projects/{project}/tasks, /api/reports/lawyers/{id}, /api/evaluate(user); etc. all in web route manifests web.php and settings.php.
• Most end up controllers returning JSON or performing batch.
• permissions middleware uses pms permission:<scope> string. plan.access/plan.limits gate.
• webhook inbound 20+ endpoints define callback route.
• Gateway callback flows mix GET and POST entries per controller (each gateway differs; consult routes/web.php before modifying).

9. Authentication/Authorization Implementation

• Stack: sessions, guarded, verified middleware.
• Impersonation optional.
• Permissions management via app setting superuser only for roles.
• Middleware/CheckPermission can generic permission.
• AutoApplyPermissionCheck trait is mixed on certain controllers.

10. Frontend Architecture

• Entry: app.tsx.
• Router: Inertia + Ziggy.
• Pages resolution: ./pages/${name}.tsx. All React compiled by Vite.
• Layouts: app-layout/app sidebar/header, auth variants.
• State management: hook + context, Inertia props; Form via useForm.
• API: axios-config.ts + manual fetch.
• Styles: Tailwind CSS 4 linking with app.css, dark-mode.css, rtl.css.
• Assets: processed with base ./.
• i18n: i18next (http backend).
• Forms validation server-side.

11. External Services & Integration

IMAP

• Library: Webklex IMAP via facade; config config/imap.php.
• Email accounts credentials stored in DB, mutators encrypt password.
• Frontend config: EmailInbox\Index, Config.tsx.
• Minimal error tracking via Log + cmd.

Gemini

• Direct URL request via Http facade (https://generativelanguage.googleapis.com/v1beta/models).
• Key/model derived via Setting key rows.
• Pricing built-in to project constants.
• Outputs are expected bubble text schema (not enforced JSON schema beyond service parse for model).

Payments

• 33 gateways with controllers and advanced management. Different gateway UI components within components/invoices and payments.
• InvoiceController and InvoicePaymentController axes.

WhatsApp

• Multi-driver Zoom? WhatsApp driver supports twilio/ultramsg.
• WhatsAppService facade via dedicated interface.

Slack/Telegram

• Slack SlackService::sendSlackNotification; Telegram TelegramService::send.
• Listener vector count pairs every second event.

Zoom

• ZoomService implements requests and Google calendar sync option.
• Meeting model monthly. meeting workflows.
• Project related (api/projects/{id}/members) frontend modal fetches.

Storage

• Dynamic or disk configured via settings.
• Test storage connection via service.

12. Testing Guide

See Part III - Technical Documentation, Chapter 6 (Testing Guide).

• Test infra: No tests/ set; phpunit.xml configured fully but xsuites missing. Parts missing.
• Pest is listed in require-dev; composer test not wired.
• Frontend: no jest/vitest references.
• Commands not run due to absent.

13. Build, Deployment, and Release

See Part III - Technical Documentation, Chapter 4 (Installation and Deployment).

• php artisan serve, npm run dev, Vite build.
• Docker compose + Dockerfile.
• queue:work --tries=3 --timeout=600.
• Laravel scheduler every minute.

14. Logging, Debugging, and Troubleshooting

• Log channel, larabug (optional).
• debugbar not installed; use php artisan pail via composer.
• Troubleshoot IMAP via command attach CLI.
• Debug Vite via dev mode.
• Config caches? artisan config:cache.
• Baseline fill check: Database seed default Super Admin exists per SEEDER_CREDENTIALS.md.

15. Maintenance and Extension Guide

• Adding feature route:

1. Add route in one of web.php, settings.php or auth.php.
2. Verify middlewares (permission:*, plan.access, etc) properly.
3. Add controller method or constructor service.
4. Update FE page modal.
5. Add translation key; debug.

• Adding notification:

1. Define event class.
2. Add listener queue side.
3. Emit in controller/service.
4. Tests/community verify.

• Integrations:
• WebhookService::triggerWebhooks(module, data) must enumerate action explicitly in webhook listener.
• DB tables updates new migration need to respect all.
• migrations: new file; update Model fillable/casts.
• new roles and permissions: add to PermissionSeeder and RoleSeeder matrix.
• UI: add Nav link to app-sidebar and breadcrumbs.

16. Security and Operational Recommendations

See Part III - Technical Documentation, Chapter 7 (Security Review).

17. Developer Handover Checklist

See Part III - Technical Documentation, Chapter 8 (Developer Handover Checklist).>