# ink-developer/pymax architecture

> Architecture diagram of the GitHub repository ink-developer/pymax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ink-developer/pymax
- Repository: https://github.com/ink-developer/pymax

## Overview

##### Project Type and Purpose
- PyMax is an asynchronous Python SDK (open-source library) that wraps the internal WebSocket API of the “Max” messenger.
- It provides an event-driven interface (MaxClient) for user code to authenticate, send/edit/delete messages, manage chats/channels, and handle incoming events.

##### File Structure Analysis
- Top level:
- src/pymax – SDK package
- examples/ – user-facing usage scripts
- docs/ – Markdown API documentation
- assets/, mkdocs.yml – static site for docs
- Inside src/pymax:
- core.py – MaxClient implementation (initialization, lifecycle)
- interfaces.py – abstract definitions of client methods
- mixins/ – composable feature modules (auth, message, channel, socket, telemetry, etc.)
- payloads.py, models.py, types.py – domain models, request/response types
- static/ – constants and enums
- files.py, crud.py, filters.py, formatter.py/formatting.py – helper modules
- exceptions.py – error handling classes
- Configuration files (pyproject.toml, ruff.toml, .github/workflows) reflect CI, packaging, linting.

##### Architectural Insights from README
- Event-driven, asynchronous design using asyncio and WebSocket.
- Core entrypoint: MaxClient; users register @client.on_message(), @client.on_start handlers.
- Communication over a persistent WebSocket connection to Max’s API.
- Maintains local state: chats, channels, dialogs.

a. Main Components
1. User Application (example.py, reg.py, telegram_bridge.py, or any consumer code)
2. PyMax SDK
- MaxClient (core lifecycle + event dispatcher)
- Mixin Modules (auth, socket, message, channel, group, telemetry, user, etc.)
- Transport Layer (WebSocket client)
- Models & Payloads (domain objects)
- Utilities (filters, formatting, files, crud operations)
3. External Max Messenger API Service (WebSocket endpoint)
4. Optional Local Cache/File Storage (work_dir)
b. Relationships & Data Flow
- User App calls MaxClient.start() → Core initializes WebSocket transport.
- Core dispatches handshake/auth sequence (via auth mixin) → Max API responds.
- User registers event handlers → on incoming WebSocket messages:
- Transport Layer parses JSON → Payloads → Models → Core dispatches to handlers.
- User code invokes client.send_message() → Core → Transport Layer → WebSocket → Max API.
- SDK updates local state (chats, dialogs) and optionally writes to cache directory.
c. Architectural Patterns & Principles
- Event-driven, asynchronous I/O (asyncio + websockets)
- Mixin-based composition (separate concerns by feature)
- Layered design: transport, core orchestration, domain logic, user interface
- Domain modeling via typed payloads and models
d. Key Technologies & Libraries
- Python 3.10+, asyncio, websockets (or similar)
- Typed interfaces (from src/pymax/types.py, interfaces.py)
- CI/CD: GitHub Actions (publish workflow), ruff linter
- Documentation: MkDocs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        direction TB
        Example["example.py"]:::userapp
        Reg["reg.py"]:::userapp
        Telegram["telegram_bridge.py"]:::userapp
    end

    %% SDK Layers
    subgraph "PyMax SDK"
        direction TB

        subgraph "Transport Layer"
            direction TB
            SocketMixin["Socket Mixin"]:::sdk
            WebsocketLogic["WebSocket Logic"]:::sdk
        end

        subgraph "Core & Dispatcher"
            direction TB
            CoreClient["MaxClient & Dispatcher"]:::sdk
            Interfaces["Client Interfaces"]:::sdk
        end

        subgraph "Mixins"
            direction TB
            AuthMixin["Auth Mixin"]:::sdk
            MessageMixin["Message Mixin"]:::sdk
            ChannelMixin["Channel Mixin"]:::sdk
            GroupMixin["Group Mixin"]:::sdk
            UserMixin["User Mixin"]:::sdk
            HandlerMixin["Event Handler Mixin"]:::sdk
            TelemetryMixin["Telemetry Mixin"]:::sdk
            UtilsMixin["Utility Mixin"]:::sdk
        end

        subgraph "Domain & Utilities"
            direction TB
            Payloads["Domain Payloads"]:::sdk
            Models["Domain Models"]:::sdk
            Types["Typed Definitions"]:::sdk
            Constants["Static Constants"]:::sdk
            Enums["Static Enums"]:::sdk
            Crud["CRUD Helpers"]:::sdk
            Filters["Filters Utility"]:::sdk
            Files["File-handling Helpers"]:::sdk
            Formatter["Formatter"]:::sdk
            Formatting["Formatting Utilities"]:::sdk
            Exceptions["Exception Definitions"]:::sdk
            Navigation["Navigation/State Management"]:::sdk
        end
    end

    %% External Services
    MaxAPI[("Max Messenger WebSocket API")]:::external
    Cache[("Local Cache (work_dir)")]:::storage

    %% Connections
    Example -->|uses| CoreClient
    Reg -->|uses| CoreClient
    Telegram -->|uses| CoreClient

    CoreClient -->|calls| SocketMixin
    SocketMixin -->|wraps| WebsocketLogic
    WebsocketLogic -->|"connects over WS"| MaxAPI
    MaxAPI -->|"sends events"| WebsocketLogic
    WebsocketLogic -->|"forwards messages"| CoreClient
    CoreClient -->|"dispatches to handlers"| HandlerMixin
    HandlerMixin -->|"invokes user handlers"| Example

    CoreClient -->|reads/writes| Cache

    CoreClient -->|uses| Interfaces
    CoreClient -->|integrates| AuthMixin
    CoreClient -->|integrates| MessageMixin
    CoreClient -->|integrates| ChannelMixin
    CoreClient -->|integrates| GroupMixin
    CoreClient -->|integrates| UserMixin
    CoreClient -->|integrates| TelemetryMixin
    CoreClient -->|integrates| UtilsMixin

    CoreClient -->|converts| Payloads
    Payloads -->|models to| Models
    CoreClient -->|uses| Types
    CoreClient -->|uses| Constants
    CoreClient -->|uses| Enums
    CoreClient -->|calls| Crud
    CoreClient -->|applies| Filters
    CoreClient -->|delegates| Files
    CoreClient -->|formats via| Formatter
    CoreClient -->|formats via| Formatting
    CoreClient -->|raises| Exceptions
    CoreClient -->|manages state via| Navigation

    %% Click Events
    click Example "https://github.com/ink-developer/pymax/blob/main/examples/example.py"
    click Reg "https://github.com/ink-developer/pymax/blob/main/examples/reg.py"
    click Telegram "https://github.com/ink-developer/pymax/blob/main/examples/telegram_bridge.py"
    click CoreClient "https://github.com/ink-developer/pymax/blob/main/src/pymax/core.py"
    click Interfaces "https://github.com/ink-developer/pymax/blob/main/src/pymax/interfaces.py"
    click SocketMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/socket.py"
    click WebsocketLogic "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/websocket.py"
    click AuthMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/auth.py"
    click MessageMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/message.py"
    click ChannelMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/channel.py"
    click GroupMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/group.py"
    click UserMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/user.py"
    click HandlerMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/handler.py"
    click TelemetryMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/telemetry.py"
    click UtilsMixin "https://github.com/ink-developer/pymax/blob/main/src/pymax/mixins/utils.py"
    click Payloads "https://github.com/ink-developer/pymax/blob/main/src/pymax/payloads.py"
    click Models "https://github.com/ink-developer/pymax/blob/main/src/pymax/models.py"
    click Types "https://github.com/ink-developer/pymax/blob/main/src/pymax/types.py"
    click Constants "https://github.com/ink-developer/pymax/blob/main/src/pymax/static/constant.py"
    click Enums "https://github.com/ink-developer/pymax/blob/main/src/pymax/static/enum.py"
    click Crud "https://github.com/ink-developer/pymax/blob/main/src/pymax/crud.py"
    click Filters "https://github.com/ink-developer/pymax/blob/main/src/pymax/filters.py"
    click Files "https://github.com/ink-developer/pymax/blob/main/src/pymax/files.py"
    click Formatter "https://github.com/ink-developer/pymax/blob/main/src/pymax/formatter.py"
    click Formatting "https://github.com/ink-developer/pymax/blob/main/src/pymax/formatting.py"
    click Exceptions "https://github.com/ink-developer/pymax/blob/main/src/pymax/exceptions.py"
    click Navigation "https://github.com/ink-developer/pymax/blob/main/src/pymax/navigation.py"

    %% Styles
    classDef userapp fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef sdk fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef external fill:#ffdd99,stroke:#333,stroke-width:1px;
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:1px;
```
