Appendix A - Diagrams

System Architecture

graph TB
  subgraph Frontend["Frontend (resources/js)"]
    RX["app.tsx entry"] --> Pages["Inertia pages (128 files)"]
    Pages --> Components["60 components + 42 ui primitives"]
    Pages --> Layouts["layouts/app-sidebar-layout"]
    Pages --> Hooks["hooks/ 14"]
    Pages --> Utils["utils/ 17"]
  end
  subgraph Backend["Backend (app/)"]
    Routes["routes/web,settings,auth,console"]
    Ctrls["Http/Controllers 125"]
    Midws["Http/Middleware 17"]
    Srvs["Services 32 + 3 WhatsApp drivers"]
    Repo["Repositories 12 + interfaces"]
    Models["Models 85"]
    Obs["Observers 4"]
    Mail["Mail 2 + Listeners 33 + Events 16"]
  end
  subgraph Data["Database"]
    DB2[("MySQL/SQLite ~94 tables")]
    Mig["93 migrations"]
  end
  Frontend -- "Inertia JSON props" --> Routes
  Routes --> Midws --> Ctrls
  Ctrls --> Srvs --> Repo --> Models --> DB2
  Srvs --> Mail
  Obs --> Models
  Mig --> DB2

Database ER Diagram

erDiagram
  users ||--o{ workspace_members : "member-of"
  users ||--o{ workspaces : "owns"
  workspaces ||--o{ projects : "contains"
  workspaces ||--o{ task_stages : "defines"
  workspaces ||--o{ bug_statuses : "defines"
  workspaces ||--o{ timesheets : "scopes"
  projects ||--o{ tasks : "contains"
  projects ||--o{ project_members : "has"
  projects ||--o{ project_clients : "has-client"
  projects ||--o{ project_milestones : "has"
  projects ||--o{ invoices : "billed-on"
  projects ||--o{ project_expenses : "spent-in"
  projects ||--o{ project_budgets : "budget"
  projects ||--o{ bug : "tracks"
  projects ||--o{ zoom_meetings : "links"
  tasks ||--o{ task_comments : "has"
  tasks ||--o{ task_checklists : "has"
  tasks ||--o{ task_attachments : "has"
  tasks ||--o{ task_members : "assigned-to"
  tasks ||--o{ task_events : "governance"
  tasks }o--|| task_stages : "stage"
  tasks }o--|| projects : "project"
  invoices ||--o{ invoice_items : "items"
  invoices ||--o{ payments : "received"
  users ||--o{ plan_orders : "purchased"
  users ||--o{ plan_requests : "requests"
  plans ||--o{ plan_orders : "ordered"
  users ||--o{ email_accounts : "owns"
  email_accounts ||--o{ email_messages : "syncs"
  email_messages }o--|| projects : "links"
  email_messages }o--|| tasks : "links"
  email_messages }o--|| bug : "links"
  users ||--o{ ai_chat_conversations : "starts"
  ai_chat_conversations ||--o{ ai_chat_messages : "contains"
  workspaces ||--o{ ai_knowledge_entries : "knowledge"
  workspaces ||--o{ workspace_ai_agents : "agent"
  workspaces ||--o{ ai_token_usage : "usage"
  workspaces ||--o{ ai_batch_logs : "batch"
  ai_batch_logs ||--o{ ai_batch_log_entries : "entries"

Major Workflows

flowchart TD
  Start(["Inbound email"]) --> Listener["EmailListenerService / IMAP sync"]
  Listener --> Filter{"Filter pass? whitelist/blocklist/allowed_email_senders"}
  Filter -->|No| Skip["Skip email"]
  Filter -->|Yes| Process["ProcessMessage"]
  Process --> MatchProject{"Find project?"}
  MatchProject -->|"case_ref match"| Link["Link email to project"]
  MatchProject -->|"allowed_domains match"| Link
  MatchProject -->|no match| Create{"Auto-create enabled?"}
  Create -->|Yes| NewProject["Create Project + assign manager/lawyer"]
  Create -->|No| LogOnly["Log only"]
  Link --> EmailRec["Create EmailMessage record"]
  NewProject --> EmailRec
  EmailRec --> AICheck{"ai_enabled = 1?"}
  AICheck -->|Yes| AI["EmailAIAssignmentService.analyzeAndAssign (Gemini)"]
  AICheck -->|No| Rules["EmailAutomationService rules fallback"]
  AI -->|success| TaskBug["Create Task/Bug + assignment + notifications"]
  AI -->|"fail / no API key"| Rules
  Rules --> Task["Create Task optionally"]
  TaskBug --> Events["Emit TaskAssigned / ProjectMemberAssigned"]
  Events --> Notify["Email + Slack + Telegram + WhatsApp + Webhooks"]
  Skip --> Seen["Mark Seen on IMAP"]
  Notify --> Seen
  Task --> Seen

System Context

graph TD
  User["Browser / SPA user (React 19 + Inertia.js)"]
  App["Laravel 12 backend (MVC + Service Layer)"]
  DB[(MySQL / SQLite database)]
  Email["IMAP server (Gmail)"]
  Gemini["Google Gemini API"]
  OpenAI["OpenAI API (ChatGptController)"]
  Wa["WhatsApp (UltraMsg/Twilio)"]
  Tg["Telegram Bot API"]
  Slack["Slack Incoming Webhook"]
  Zoom["Zoom REST API"]
  PG["33 payment gateways"]
  Storage["Local / S3 storage"]

  User -- "Inertia SPA" --> App
  App --> DB
  App -- "EmailAutomation / AI triage" --> Email
  App -- "AiAgentService / EmailAIAssignmentService" --> Gemini
  App -- "ChatGptController" --> OpenAI
  App --> Wa
  App --> Tg
  App --> Slack
  App --> Zoom
  App --> PG
  App --> Storage