# opencti-platform/client-python architecture

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

- Interactive diagram: https://gitdiagram.com/opencti-platform/client-python
- Repository: https://github.com/opencti-platform/client-python

## Overview

##### Project type and purpose
- This is an open-source Python client library (“pycti”) for the OpenCTI platform.
- It provides a high-level, easy-to-use wrapper around the OpenCTI GraphQL API, with modules for API calls, STIX-based entities, connector helpers, and utilities.

##### File structure
- Top level
- Configuration and CI: .circleci/, .github/, .drone.yml, Makefile, setup files
- docs/: Sphinx documentation source
- examples/: Python scripts showing how to call pycti to interact with OpenCTI
- pycti/: the client library itself, subdivided into api/, connector/, entities/, utils/
- tests/: unit and integration test suites
- Key modules
- pycti/api: GraphQL client, methods grouped by API domain (client, job, notification, workspace, etc.)
- pycti/connector: helper classes to build connectors that sync data to/from OpenCTI
- pycti/entities: classes modeling OpenCTI’s STIX objects (attack patterns, malware, campaigns…)
- pycti/utils: logging, STIX2 helpers, constants, ID management
- Deployment/config
- pyproject.toml, setup.cfg, requirements.txt define packaging and dependencies
- CI workflows (.circleci/config.yml, .github/workflows/*.yml) enforce tests, linting, security scans
- pre-commit, flake8, isort, yamllint for code quality

##### README for additional insights
- Describes install, local development, testing against a live OpenCTI instance
- Points to usage docs, API reference, and example scripts
- Emphasizes that the library is used by other OpenCTI components

##### Detailed component breakdown (to include
- User Application / Scripts (examples/)
- pycti Client
- API Client (pycti/api/opencti_api_client.py & domain-specific clients)
- Connector Helper (pycti/connector/opencti_connector_helpers.py)
- Metric Handler (pycti/connector/opencti_metric_handler.py)
- Entities (pycti/entities/*.py mapping STIX domain objects)
- Utils (logging, STIX2 converters, ID management)
- External OpenCTI Platform (GraphQL endpoint)
- CI/CD Pipelines
- GitHub Actions, CircleCI, Drone
- Packaging & Distribution (PyPI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        UA["User Application / Examples"]:::user
    end

    %% Core Library
    subgraph "Core Library"
        subgraph "API Module" 
            APIClient["opencti_api_client.py"]:::core
            APIConnector["opencti_api_connector.py"]:::core
            APIDraft["opencti_api_draft.py"]:::core
            APIFile["opencti_api_internal_file.py"]:::core
            APINotif["opencti_api_notification.py"]:::core
            APIPir["opencti_api_pir.py"]:::core
            APIPlaybook["opencti_api_playbook.py"]:::core
            APIDashboard["opencti_api_public_dashboard.py"]:::core
            APITrash["opencti_api_trash.py"]:::core
            APIWork["opencti_api_work.py"]:::core
            APIWorkspace["opencti_api_workspace.py"]:::core
        end
        subgraph "Connector Module"
            ConnectorBase["opencti_connector.py"]:::connector
            ConnectorHelper["opencti_connector_helper.py"]:::connector
            MetricHandler["opencti_metric_handler.py"]:::connector
        end
        subgraph "Entities Module"
            Entities["STIX Domain Entities"]:::entities
        end
        subgraph "Utils Module"
            Constants["constants.py"]:::utils
            Logger["opencti_logger.py"]:::utils
            STIX2["opencti_stix2.py"]:::utils
            STIX2Utils["opencti_stix2_utils.py"]:::utils
            Identifier["opencti_stix2_identifier.py"]:::utils
            Splitter["opencti_stix2_splitter.py"]:::utils
            Updater["opencti_stix2_update.py"]:::utils
        end
    end

    %% External System
    subgraph "External OpenCTI Platform"
        OpenCTI["GraphQL API Endpoint"]:::external
    end

    %% CI/CD & Packaging & Docs
    subgraph "CI/CD & Packaging"
        CircleCI[".circleci/config.yml"]:::ci
        GHActions[".github/workflows/*.yml"]:::ci
        DroneCI[".drone.yml"]:::ci
        PyPI["PyPI Packaging"]:::ci
        Docs["docs/"]:::ci
    end

    %% Relationships
    UA -->|"imports/uses"| APIClient
    UA -->|"imports/uses"| ConnectorBase
    APIClient -->|"GraphQL query/response"| OpenCTI
    ConnectorBase -->|"uses API Module"| APIClient
    ConnectorBase -->|"streams data to/from"| OpenCTI
    APIClient -->|"uses Entities"| Entities
    ConnectorBase -->|"uses Entities"| Entities
    APIClient -->|"uses Utils"| Logger
    ConnectorBase -->|"uses Utils"| Logger
    Entities -->|"assisted by"| STIX2
    STIX2Utils -->|"helper for"| Entities
    Logger -->|"logs for"| APIClient
    Logger -->|"logs for"| ConnectorBase

    CircleCI -->|"runs tests"| APIClient
    GHActions -->|"runs tests"| APIClient
    DroneCI -->|"runs tests"| APIClient
    CircleCI -->|"deploys to"| PyPI
    GHActions -->|"deploys to"| PyPI

    UA -.->|"refer docs in"| Docs
    APIClient -.->|"generated docs"| Docs
    Entities -.->|"generated docs"| Docs
    STIX2 -.->|"generated docs"| Docs

    %% Click Events
    click UA "https://github.com/opencti-platform/client-python/tree/master/examples/"
    click APIClient "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_client.py"
    click APIConnector "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_connector.py"
    click APIDraft "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_draft.py"
    click APIFile "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_internal_file.py"
    click APINotif "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_notification.py"
    click APIPir "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_pir.py"
    click APIPlaybook "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_playbook.py"
    click APIDashboard "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_public_dashboard.py"
    click APITrash "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_trash.py"
    click APIWork "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_work.py"
    click APIWorkspace "https://github.com/opencti-platform/client-python/blob/master/pycti/api/opencti_api_workspace.py"
    click ConnectorBase "https://github.com/opencti-platform/client-python/blob/master/pycti/connector/opencti_connector.py"
    click ConnectorHelper "https://github.com/opencti-platform/client-python/blob/master/pycti/connector/opencti_connector_helper.py"
    click MetricHandler "https://github.com/opencti-platform/client-python/blob/master/pycti/connector/opencti_metric_handler.py"
    click Constants "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/constants.py"
    click Logger "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/opencti_logger.py"
    click STIX2 "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/opencti_stix2.py"
    click STIX2Utils "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/opencti_stix2_utils.py"
    click Identifier "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/opencti_stix2_identifier.py"
    click Splitter "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/opencti_stix2_splitter.py"
    click Updater "https://github.com/opencti-platform/client-python/blob/master/pycti/utils/opencti_stix2_update.py"
    click CircleCI "https://github.com/opencti-platform/client-python/blob/master/.circleci/config.yml"
    click GHActions "https://github.com/opencti-platform/client-python/blob/master/.github/workflows/auto-set-labels.yml"
    click GHActions "https://github.com/opencti-platform/client-python/blob/master/.github/workflows/codeql-analysis.yml"
    click DroneCI "https://github.com/opencti-platform/client-python/blob/master/.drone.yml"
    click PyPI "https://github.com/opencti-platform/client-python/blob/master/pyproject.toml"
    click Docs "https://github.com/opencti-platform/client-python/tree/master/docs/"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef connector fill:#bfb,stroke:#333,stroke-width:1px
    classDef entities fill:#fbf,stroke:#333,stroke-width:1px
    classDef utils fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#fbb,stroke:#333,stroke-width:1px
    classDef ci fill:#ccc,stroke:#333,stroke-width:1px
```
