# admoai/admoai-ios architecture

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

- Interactive diagram: https://gitdiagram.com/admoai/admoai-ios
- Repository: https://github.com/admoai/admoai-ios

## Overview

##### Project Type and Purpose
- This is an iOS SDK for native advertising integration. Its purpose is to enable other iOS applications to request and display various ad formats (including carousel, companion, and standard ads), while also handling targeting, event tracking (impressions, clicks, and custom events), and user consent management (GDPR).
- The README and file structure indicate that this project is distributed as a Swift Package (via Package.swift) and includes a demo application (under the Examples/Demo directory) to illustrate its usage.

##### Key Architectural Components
- SDK Core (Sources/AdMoai):
- AdMoai.swift: Contains the main SDK interface and initialization logic.
- SDKConfig & Configs.swift: Handles configuration such as the base URL and global settings.
- API Client (APIClient.swift): Manages network calls to external ad servers.
- Builder Pattern (DecisionRequestBuilder.swift in Models/): Used to create ad requests with placements, targeting data (geo, location, custom), and user overrides.
- Models (located in Sources/AdMoai/Models): Structure the data for requests (DecisionRequest) and responses (DecisionResponse).
- Utilities (Sources/AdMoai/Utils): Includes helper functions and shared utilities such as AnyCodable and device/app details management.
- Demo App Components (Examples/Demo):
- App Logic (DemoApp.swift, ContentView.swift, and ContentViewModel.swift): Demonstrates integration of the SDK.
- UI Components and Views: Organized under Views and Components (e.g., different ad layout views, request views, and response views) showcasing different parts of the user interface.
- Extensions & Preview Content: To facilitate design and testing of the UI.
- Documentation (docs folder):
- Includes detailed generated documentation of components along with styling and javascript to support the web documentation site.
- Testing (Tests/AdMoaiTests):
- Unit tests to verify core functionalities such as request building and response validation.

##### Defining Relationships and Interactions
- The Application (or Demo App) initializes the SDK core by providing configuration information.
- Once the ad response is received, the creative/contents are parsed from the DecisionResponse model. The demo application then uses these data to render the UI components, such as ad views.
- Event tracking is handled via utility functions: when an impression, click, or custom event occurs, the SDK makes network calls (using URL sessions) to track these events. Show these paths as outgoing calls from the creative’s tracking component.

##### Highlighting Architectural Patterns and Design Principles
- Modularity: The SDK is divided into separate modules for API interactions, business logic (models and configurations), and helper utilities.
- Builder Pattern: The ad request creation uses a builder pattern, allowing flexible construction of ad requests with various targeting options.
- Testability: With dedicated test directories, the design supports unit testing practices that validate core functionality independent of UI components.

##### Relevant Technologies, Frameworks, and Libraries
- Swift (version 5.9+)
- Swift Package Manager integration (via Package.swift)
- iOS frameworks (UIKit for UI components in the demo, URLSession for HTTP requests)
- Xcode project structure for building and testing (see the Demo project’s .xcodeproj files)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% SDK Core Section
    subgraph "SDK Core"
        SDK["AdMoai SDK Core"]:::sdk
        CONFIG["SDK Configuration"]:::sdk
        API["API Client"]:::sdk
        BUILDER["Ad Request Builder"]:::sdk
        subgraph "Models"
            REQ["DecisionRequest"]:::sdk
            RESP["DecisionResponse"]:::sdk
        end
        UTIL["Utilities & Event Tracker"]:::utility
    end

    %% Demo App Section
    subgraph "Demo App"
        APP_LOGIC["Demo App Logic"]:::app
        subgraph "UI Layer"
            UI_COMP["UI Components"]:::app
            UI_EXT["UI Extensions"]:::app
            PREVIEW["Preview Content"]:::app
        end
    end

    %% Documentation & Testing Section
    subgraph "Documentation & Testing"
        DOC["Documentation"]:::doc
        TEST["Testing"]:::doc
    end

    %% External Component
    EXT["Remote Ad Server"]:::external

    %% Relationships and Data Flow
    APP_LOGIC -->|"init"| SDK
    SDK -->|"configures"| CONFIG
    SDK -->|"triggersBuilder"| BUILDER
    BUILDER -->|"buildsRequest"| REQ
    BUILDER -->|"buildsResponse"| RESP
    BUILDER -->|"sendsRequest"| API
    API -->|"HTTPReqRes"| EXT
    EXT -->|"HTTPRes"| API
    RESP -->|"sendsData"| APP_LOGIC
    SDK -->|"handlesEvents"| UTIL
    UTIL -->|"tracksEvents"| EXT
    UI_COMP -->|"rendersAds"| APP_LOGIC

    %% Click Events
    click SDK "https://github.com/admoai/admoai-ios/tree/main/Sources/AdMoai"
    click CONFIG "https://github.com/admoai/admoai-ios/blob/main/Sources/AdMoai/Configs.swift"
    click API "https://github.com/admoai/admoai-ios/blob/main/Sources/AdMoai/APIClient.swift"
    click BUILDER "https://github.com/admoai/admoai-ios/blob/main/Sources/AdMoai/Models/DecisionRequestBuilder.swift"
    click REQ "https://github.com/admoai/admoai-ios/blob/main/Sources/AdMoai/Models/DecisionRequest.swift"
    click RESP "https://github.com/admoai/admoai-ios/blob/main/Sources/AdMoai/Models/DecisionResponse.swift"
    click UTIL "https://github.com/admoai/admoai-ios/tree/main/Sources/AdMoai/Utils"
    click APP_LOGIC "https://github.com/admoai/admoai-ios/tree/main/Examples/Demo/Demo/App"
    click UI_COMP "https://github.com/admoai/admoai-ios/tree/main/Examples/Demo/Demo/Components"
    click UI_EXT "https://github.com/admoai/admoai-ios/tree/main/Examples/Demo/Demo/Extensions"
    click PREVIEW "https://github.com/admoai/admoai-ios/tree/main/Examples/Demo/Demo/Preview Content"
    click DOC "https://github.com/admoai/admoai-ios/tree/main/docs folder"
    click TEST "https://github.com/admoai/admoai-ios/tree/main/Tests/AdMoaiTests"

    %% Styles
    classDef sdk fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef app fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef doc fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;
```
