# alibaba/coobjc architecture

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

- Interactive diagram: https://gitdiagram.com/alibaba/coobjc
- Repository: https://github.com/alibaba/coobjc

## Overview

##### Main modules
- Cocore Layer: This is the low-level core written in C/assembly (see the “cocore” directory) which provides the underlying coroutine functionality (context switching, error handling, etc.).
- coobjc Module: This provides the primary Objective-C implementation of coroutine features: the actor model, generators, promises, and tuple support. It sits atop cocore to expose coroutine APIs.
- coswift Module: A Swift wrapper (see “coswift” directory) built on top of the low-level coroutine support. It adapts the underlying system for Swift’s language features and syntax.
- cokit Module: A supplementary framework that extends the API by adding coroutine-based categories for standard Foundation and UIKit classes.
- Examples and Tests: Several example projects (such as coSwiftDemo, coobjcBaseExample, and coKitExamples) and unit test suites that demonstrate how to use these modules in practice.

##### Relationships and interactions
- The cocore module is the fundamental layer and is used by both coobjc and coswift – it handles low-level scheduling, context switching, and the core coroutine mechanisms.
- coobjc directly builds on cocore and exposes coroutine primitives (co_launch, await, error handling, etc.) and the additional concepts such as actor, generator, and tuple.
- coswift wraps or exposes these same functionalities in a way that is more natural to Swift programmers.
- cokit provides additional “glue” by wrapping native APIs (like NSFileManager, JSON parsing, etc.) so that they can be used in coroutine fashion possibly by utilizing coobjc/co routines under the hood.
- Example projects and tests show real-world usage scenarios and validate the functionality of each module.

##### Architectural patterns and design principles
- Layering: Clearly show a multi-layered stack where cocore is at the bottom, followed by coobjc (and its Swift wrapper, coswift) above it, and then cokit for high-level API integration.
- Separation of Concerns: Each module (cocore, coobjc, coswift, cokit) focuses on a different aspect of asynchronous programming – from low-level coroutine scheduling to high-level API wrapping.
- Modular and Extensible Design: The architecture supports both Objective-C and Swift, which implies a design that encapsulates lower-level concurrency details from the high-level application logic.
- Asynchronous Programming: Emphasize that the design avoids callback hell by using coroutines and asynchronous await constructs, which simplifies control flow and error handling.

##### Technologies, frameworks, and libraries
- Languages: Objective-C, Swift, C/Assembly (for cocore).
- iOS internal frameworks: Foundation and UIKit (wrapped via cokit).
- Integration with CocoaPods (podspec files for coobjc, coswift, and cokit).
- External libraries: fishhook (for symbol rebinding), and promise implementations (inspired by Google’s Promises framework).

##### Elements
- Clear labels: Make sure each module (cocore, coobjc, coswift, cokit) and their subcomponents (actor, generator, tuple support, promise implementation) are clearly identified.
- From coobjc and coswift to cocore (indicating that the low-level routines are called by the higher-level APIs).
- From cokit to actual system APIs (Foundation/ UIKit) indicating the wrapping.

##### Execution details
- Stack above it the coobjc module (with sub-modules like actor, generator, promise, tuple) and indicate that coobjc accesses cocore functions.
- To the side or on top, include the coswift module which wraps coobjc for Swift’s environment.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer
    subgraph "Core Layer"
        Cocore["Cocore (C/Assembly)"]:::core
    end

    %% API Layer: Objective-C and Swift
    subgraph "API Layers"
        coobjc["coobjc (Objective-C)"]:::objc
        coswift["coswift (Swift Wrapper)"]:::swift
    end

    %% Helper/Extension Layer
    subgraph "Helper/Extension Layer"
        cokit["cokit (iOS Wrappers)"]:::helper
    end

    %% System Libraries
    subgraph "System Libraries"
        iOS["iOS Frameworks (Foundation, UIKit)"]:::system
    end

    %% External Client Applications
    subgraph "Client Applications"
        Examples["Examples & Tests"]:::external
    end

    %% Relationships
    coobjc -->|"calls"| Cocore
    coswift -->|"wraps"| coobjc
    cokit -->|"extends"| coobjc
    cokit -->|"wraps"| iOS
    Examples -->|"uses"| coobjc
    Examples -->|"uses"| coswift
    Examples -->|"uses"| cokit

    %% Click Events
    click Cocore "https://github.com/alibaba/coobjc/tree/master/cocore"
    click coobjc "https://github.com/alibaba/coobjc/tree/master/coobjc"
    click coswift "https://github.com/alibaba/coobjc/tree/master/coswift"
    click cokit "https://github.com/alibaba/coobjc/tree/master/cokit"
    click Examples "https://github.com/alibaba/coobjc/tree/master/Examples"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef objc fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef swift fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef helper fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef system fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
