# z-hub/z-push architecture

> Architecture diagram of the GitHub repository z-hub/z-push, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z-hub/z-push
- Repository: https://github.com/z-hub/z-push

## Overview

##### Main Components Identification
The system should be represented with these key components:

a) Core Components:
- ActiveSync Protocol Handler (src/lib/core)
- Request Processor (src/lib/request)
- WBXML Parser/Encoder (src/lib/wbxml)
- State Management System (src/lib/core/statemanager.php)
- Device Management (src/lib/core/devicemanager.php)

b) Backend Systems:
Multiple backend implementations including:
- Kopano
- IMAP
- CalDAV
- CardDAV
- LDAP
- Combined
- SQL State Machine

c) Interface Layer:
- IBackend
- IChanges
- IExportChanges
- IImportChanges
- IStateManager

**┌─────────────────────────────────────────────┐**
- Client Devices                 │
- (Mobile Phones, Tablets, Outlook)        │
- ┘
- ↕ ActiveSync
**┌─────────────────────────────────────────────┐**
- Web Server Layer               │
- (Apache/Nginx/Lighttpd)             │
- ┘
- ↕ PHP
**┌─────────────────────────────────────────────┐**
- Z-Push Core Layer               │
- ┤
- Request Processor                         │
- WBXML Handler                            │
- State Management                         │
- Device Management                        │
- ┘
- ↕ Backend Interfaces
**┌─────────────────────────────────────────────┐**
- Backend Connectors               │
- ┬───────────┬──────────┬─────────┤
- Kopano   │   IMAP    │  CalDAV  │ CardDAV │
- ┴───────────┴──────────┴─────────┘
- ↕
**┌─────────────────────────────────────────────┐**
- Storage Systems                  │
- (Email Servers, Calendar, Contacts, etc.)  │
- ┘

##### Important Details

a) Protocol Handling:
- ActiveSync protocol handling at the top level
- WBXML encoding/decoding process
- Request/response flow

b) Backend Integration:
- Demonstrate the plugin architecture for backends
- How different backends can be used simultaneously
- State management flow

c) IPC and State Management:
- Different state storage options (File/SQL/Memory)
- Inter-process communication mechanisms
- Caching systems

##### Implementation Details

- The modular backend system
- The request processing pipeline
- State management across different storage options
- Device provisioning and management
- Synchronization mechanisms

##### Optimization Notes

- Use consistent naming with the codebase
- Version information
- Notes about deployment configurations

This system design should be created using a professional diagramming tool that supports:
- Layered architecture representation
- Export to common formats (PNG, SVG, PDF)
- Easy updates and modifications

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph CL[Client Layer]
        CD[Client Devices]:::client
    end

    %% Web Server Layer
    subgraph WS[Web Server Layer]
        WEB[Web Server - Apache/Nginx/Lighttpd]:::webserver
    end

    %% Z-Push Core Layer
    subgraph ZP[Z-Push Core]
        RP["Request Processor"]:::core
        click RP "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/request/requestprocessor.php"
        
        WBXML["WBXML Parser/Encoder"]:::core
        click WBXML "https://github.com/Z-Hub/Z-Push/tree/develop/src/lib/wbxml"
        
        SM["State Management"]:::core
        click SM "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/core/statemanager.php"
        
        DM["Device Management"]:::core
        click DM "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/core/devicemanager.php"
        
        LOG["Logging System"]:::core
        click LOG "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/core/zlog.php"
        
        DEFS["Core Definitions"]:::core
        click DEFS "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/core/zpushdefs.php"
    end

    %% Request Handlers
    subgraph RH[Request Handlers]
        SYNC["Sync"]:::handler
        click SYNC "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/request/sync.php"
        
        FSYNC["FolderSync"]:::handler
        click FSYNC "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/request/foldersync.php"
        
        PING["Ping"]:::handler
        click PING "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/request/ping.php"
        
        SEARCH["Search"]:::handler
        click SEARCH "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/request/search.php"
        
        MAIL["SendMail"]:::handler
        click MAIL "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/request/sendmail.php"
    end

    %% Interface Layer
    subgraph IL[Interface Layer]
        IB["IBackend"]:::interface
        click IB "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/interface/ibackend.php"
        
        IC["IChanges"]:::interface
        click IC "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/interface/ichanges.php"
        
        IEC["IExportChanges"]:::interface
        click IEC "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/interface/iexportchanges.php"
        
        IIC["IImportChanges"]:::interface
        click IIC "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/interface/iimportchanges.php"
        
        ISM["IStateManager"]:::interface
        click ISM "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/interface/istatemachine.php"
    end

    %% Backend Systems
    subgraph BE[Backend Systems]
        KOP["Kopano"]:::backend
        click KOP "https://github.com/Z-Hub/Z-Push/blob/develop/src/backend/kopano/kopano.php"
        
        IMAP["IMAP"]:::backend
        click IMAP "https://github.com/Z-Hub/Z-Push/blob/develop/src/backend/imap/imap.php"
        
        CALDAV["CalDAV"]:::backend
        click CALDAV "https://github.com/Z-Hub/Z-Push/blob/develop/src/backend/caldav/caldav.php"
        
        CARDDAV["CardDAV"]:::backend
        click CARDDAV "https://github.com/Z-Hub/Z-Push/blob/develop/src/backend/carddav/carddav.php"
        
        LDAP["LDAP"]:::backend
        click LDAP "https://github.com/Z-Hub/Z-Push/blob/develop/src/backend/ldap/ldap.php"
        
        COMB["Combined"]:::backend
        click COMB "https://github.com/Z-Hub/Z-Push/blob/develop/src/backend/combined/combined.php"
    end

    %% Storage Layer
    subgraph ST[Storage Systems]
        STO[Email/Calendar/Contacts Servers]:::storage
        FSM["File State Machine"]:::storage
        click FSM "https://github.com/Z-Hub/Z-Push/blob/develop/src/lib/default/filestatemachine.php"
    end

    %% Connections
    CD --> WEB
    WEB --> RP
    RP --> WBXML
    RP --> RH
    RH --> SM
    RH --> DM
    SM --> FSM
    DM --> FSM
    RH --> IL
    IL --> BE
    BE --> STO

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef webserver fill:#ddf,stroke:#333,stroke-width:2px
    classDef core fill:#bbf,stroke:#333,stroke-width:2px
    classDef handler fill:#dbf,stroke:#333,stroke-width:2px
    classDef interface fill:#ff9,stroke:#333,stroke-width:2px
    classDef backend fill:#9f9,stroke:#333,stroke-width:2px
    classDef storage fill:#ddd,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1[Client]:::client
        L2[Web Server]:::webserver
        L3[Core Components]:::core
        L4[Request Handlers]:::handler
        L5[Interfaces]:::interface
        L6[Backends]:::backend
        L7[Storage]:::storage
    end
```
