# stoffl6781/perfex-api architecture

> Architecture diagram of the GitHub repository stoffl6781/perfex-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stoffl6781/perfex-api
- Repository: https://github.com/stoffl6781/perfex-api

## Overview

##### Project Type and Purpose
- This is a PHP-based module for Perfex CRM that exposes a REST-style HTTP API endpoint for creating and updating Leads via POST.
- It hooks into the Perfex CRM core as an installable module—no core code changes are required.

##### File Structure
- api.php: the module’s entry point for external HTTP calls.
- install.php: handles module installation (registering hooks/routes in Perfex CRM).
- controllers/
- Api.php – processes incoming API requests, delegates to CRM models.
- Settings.php – renders and saves module-level configuration in the CRM admin UI.
- views/settings.php: the HTML/PHP form for configuration in Perfex CRM’s backend.
- language/: locale files (english, german) for internationalizing UI and API responses.
- README.md & LICENSE: project overview and license.

##### README for Additional Insights
- Describes required POST fields, update vs. create logic, and special “block” and “return” query flags.
- Mentions token authentication.
- Explains how custom fields, statuses, sources and assignments are fetched or modified.

##### Main Components
a. External Client(s)
- Any web application or service sending HTTP POSTs (with token and lead data).
b. Perfex CRM Module Loader
- install.php registers hooks; routes requests under /modules/perfex-api/api.php -> controllers/Api.
c. API Controller Layer
- Api.php: Authentication check (token), “blockcreatelead” / “blockupdatelead” rules, CRUD logic.
d. Settings Controller & UI
- Settings.php + views/settings.php: Admin user configures API token, defaults, languages.
e. Perfex CRM Core & Models
- Uses existing CRM models (Leads, Staff, Sources, Status, Custom Fields).
f. Database
- MySQL (Perfex CRM schema): leads, staff, sources, statuses, custom_fields, etc.
g. Language Service
- Loads fapi_lang.php and api_lang.php based on CRM locale to localize messages/responses.

##### Relationships and Data Flows
- External Client → HTTP POST → api.php
- api.php invokes Api controller.
- Api controller authenticates (token), validates payload, decides “create” or “update.”
- Interacts with CRM core models to read/write the leads table and related lookup tables (status, source, staff).
- Returns JSON with success/error codes, optionally data from returnactivefields or returncustomfields calls.
- CRM Admin UI → Settings Controller
- Admin submits API token & module settings via views/settings.php.
- Settings controller persists settings (CRM’s options table).
- Controllers → Language Service
- On each request, loads appropriate fapi_lang.php or api_lang.php for messages.

##### Architectural Patterns and Principles
- MVC: controllers (Api, Settings), views (settings.php), models (CRM core).
- Single module boundary: api.php & controllers are encapsulated in module folder.
- Hook/Plugin pattern: install.php registers the module with Perfex CRM.
- Separation of concerns: API logic isolated from CRM UI logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External System
    subgraph "External System"
        EC["External Client"]:::external
        CRMAdmin["CRM Admin UI"]:::external
    end

    %% Perfex-API Module
    subgraph "Perfex-API Module"
        APIEntry["api.php"]:::module
        Installer["install.php"]:::module
        subgraph "Controllers"
            ApiC["Api Controller"]:::module
            SettingsC["Settings Controller"]:::module
        end
        SettingsV["views/settings.php"]:::view
        subgraph "Language Files"
            LangEn["fapi_lang.php"]:::lang
            LangDe["api_lang.php"]:::lang
        end
        README["README.md"]:::module
        LICENSE["LICENSE"]:::module
    end

    %% Perfex CRM Core
    subgraph "Perfex CRM Core"
        Leads["Leads Model"]:::core
        Staff["Staff Model"]:::core
        Sources["Sources Model"]:::core
        Status["Status Model"]:::core
        Custom["Custom Fields Model"]:::core
    end

    %% Database
    Database["MySQL Database"]:::db

    %% Decision Nodes
    TokenCheck{"Token Valid?"}
    BlockCheck{"Block Lead Flags?"}

    %% Data Flows
    EC -->|POST lead data + token| APIEntry
    APIEntry -->|Route request| ApiC
    ApiC -->|Load language strings| LangEn
    ApiC -->|Load language strings| LangDe
    ApiC --> TokenCheck
    TokenCheck -->|valid| BlockCheck
    TokenCheck -->|invalid| ApiCError["Error Response"]:::module
    BlockCheck -->|allow| ApiCCreateUpdate["Create/Update Lead"]:::module
    BlockCheck -->|blocked| ApiCError
    ApiCCreateUpdate -->|CRUD operations| Leads
    ApiCCreateUpdate -->|CRUD operations| Staff
    ApiCCreateUpdate -->|CRUD operations| Sources
    ApiCCreateUpdate -->|CRUD operations| Status
    ApiCCreateUpdate -->|CRUD operations| Custom
    Leads -->|SQL read/write| Database
    Staff -->|SQL read/write| Database
    Sources -->|SQL read/write| Database
    Status -->|SQL read/write| Database
    Custom -->|SQL read/write| Database

    CRMAdmin -->|Configure Module| SettingsC
    SettingsC -->|Render form| SettingsV
    SettingsC -->|Load language strings| LangEn
    SettingsC -->|Load language strings| LangDe
    SettingsC -->|Save settings| Database

    %% Click Events
    click APIEntry "https://github.com/stoffl6781/perfex-api/blob/main/api.php"
    click Installer "https://github.com/stoffl6781/perfex-api/blob/main/install.php"
    click ApiC "https://github.com/stoffl6781/perfex-api/blob/main/controllers/Api.php"
    click SettingsC "https://github.com/stoffl6781/perfex-api/blob/main/controllers/Settings.php"
    click SettingsV "https://github.com/stoffl6781/perfex-api/blob/main/views/settings.php"
    click LangEn "https://github.com/stoffl6781/perfex-api/blob/main/language/english/fapi_lang.php"
    click LangDe "https://github.com/stoffl6781/perfex-api/blob/main/language/german/api_lang.php"
    click README "https://github.com/stoffl6781/perfex-api/blob/main/README.md"
    click LICENSE "https://github.com/stoffl6781/perfex-api/tree/main/LICENSE"

    %% Styles
    classDef external fill:#AEDFF7,stroke:#006DAA,color:#000;
    classDef module fill:#C8E6C9,stroke:#2E7D32,color:#000;
    classDef core fill:#E0E0E0,stroke:#424242,color:#000;
    classDef db fill:#FFE0B2,stroke:#EF6C00,color:#000;
    classDef view fill:#FFF9C4,stroke:#FBC02D,color:#000;
    classDef lang fill:#E1BEE7,stroke:#8E24AA,color:#000;
```
