# vkcom/vk-android-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/vkcom/vk-android-sdk
- Repository: https://github.com/vkcom/vk-android-sdk

## Overview

##### Project Type and Purpose
- This is an Android SDK library (multi‑module Gradle project) providing:
- Core network + auth framework (“core” module)
- Generated VK API service stubs + DTOs (“api” module)
- Host support for in‑app/browser OAuth flows (“host” module)
- User‑ID helper functionality (“id” module)
- Sample Android application demonstrating integration (“samples/app”).
- Its purpose is to let Android apps authenticate with VK, call VK’s REST API, handle token refresh, parse JSON responses, and upload files.

##### Main Components
- Sample Application (Android APK)
- Core SDK module
- HTTP client (OkHttp)
- API call scheduler, retry/chain logic
- JSON parsing, token management, preferences storage
- API SDK module
- Auto‑generated service classes (e.g., FriendsService, PhotosService)
- DTOs for request/response payloads
- Host SDK module
- OAuth launcher activities/components
- WebView or deep‑link handler for VK app
- ID SDK module
- UserId utilities, Gson serializers
- External VK Backend (REST API endpoints)
- External OAuth providers (VK App, Browser)

##### Relationships and Data Flows
- The Sample App depends on Core, API, Host, and ID modules.
- Authentication Flow:
Sample App → Host SDK → Android OS (WebView or VK App) → OAuth login UI → callback → Host SDK → Core SDK (token stored) → Sample App.
- API Call Flow:
Sample App → API SDK (service.method(...)) → Core SDK (VKApiManager) → HTTP client → VK Backend → JSON response → Core SDK JSON parser → API DTO parser → Sample App callback.
- Token Expiry: Core SDK issues callbacks to registered VKTokenExpiredHandler in the Sample App.

##### Architectural Patterns and Principles
- Modular layered architecture:
- Core layer abstracts networking & auth.
- API layer contains only service stubs and models.
- Host and ID layers extend core for specific features.
- Dependency Injection (via Gradle & Interface abstractions)
- Chain of Responsibility for error handling and retries
- Separation of concerns: UI auth handled in Host, business logic in Core, API model definitions in API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sample Application
    SampleApp["Sample App"]:::app

    %% VK SDK Suite
    subgraph "VK SDK Suite"
        CoreSDK["Core SDK"]:::sdk
        APISDK["API SDK"]:::sdk
        HostSDK["Host SDK"]:::sdk
        IDSDK["ID SDK"]:::sdk
    end

    %% External Systems
    VKBackend((VK REST Backend)):::external
    VKAppBrowser[("VK App / Browser")]:::external

    %% Dependencies from Sample App to SDK modules
    SampleApp -->|"depends on"| CoreSDK
    SampleApp -->|"depends on"| APISDK
    SampleApp -->|"depends on"| HostSDK
    SampleApp -->|"depends on"| IDSDK

    %% SDK inter-dependencies
    APISDK -->|"uses"| CoreSDK
    HostSDK -->|"extends"| CoreSDK
    IDSDK -->|"extends"| CoreSDK

    %% Authentication Flow
    SampleApp -->|"auth request"| HostSDK
    HostSDK -->|"open OAuth UI"| VKAppBrowser
    VKAppBrowser -->|"redirect callback"| HostSDK
    HostSDK -->|"store token"| CoreSDK
    CoreSDK -->|"token callback"| SampleApp

    %% API Call Flow
    SampleApp -->|"service.method()"| APISDK
    APISDK -->|"VKApiManager.call()"| CoreSDK
    CoreSDK -->|"HTTP request"| VKBackend
    VKBackend -->|"JSON response"| CoreSDK
    CoreSDK -->|"parse JSON"| APISDK
    APISDK -->|"callback"| SampleApp

    %% Token Expiry Handler
    CoreSDK -.->|"token expired event"| SampleApp

    %% Click events
    click SampleApp "https://github.com/vkcom/vk-android-sdk/tree/master/samples/app"
    click CoreSDK "https://github.com/vkcom/vk-android-sdk/tree/master/core"
    click APISDK "https://github.com/vkcom/vk-android-sdk/tree/master/api"
    click HostSDK "https://github.com/vkcom/vk-android-sdk/tree/master/host"
    click IDSDK "https://github.com/vkcom/vk-android-sdk/tree/master/id"

    %% Styles
    classDef app fill:#D0E4FD,stroke:#3B82F6,stroke-width:2px;
    classDef sdk fill:#D1FAE5,stroke:#10B981,stroke-width:2px;
    classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:2px,stroke-dasharray: 5 5;
```
