# mapnests/synkroniq-android-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/mapnests/synkroniq-android-sdk
- Repository: https://github.com/mapnests/synkroniq-android-sdk

## Overview

1. **Repository purpose and boundary**
   - This is an Android **sample app** for demonstrating the Synkroniq SDK, not the SDK implementation itself.
   - The app is a thin client over a **prebuilt AAR** (`app/libs/synkroniq1.0.0.aar`) that exposes ticketing and service-category APIs.
   - The actual network stack and native TLS/JNI details live inside the AAR boundary, not in this repo’s Kotlin source.

2. **Build and packaging model**
   - The project is a standard **single-module Android app** (`app`) built with **Gradle Kotlin DSL**.
   - Dependency resolution includes local binary artifacts from `app/libs`, which is how the SDK is consumed.
   - Minimum runtime target is **Android API 23**, with **Java 11** as stated in the README.

3. **External service integration**
   - All business functionality comes from the external **Synkroniq backend API**.
   - The app constructs request bodies as `JSONObject`s and sends them through `SynkroniqSDK.getInstance(...)`.
   - Responses are returned as raw JSON strings; failures surface as `ApiError`.

4. **Top-level app flow**
   - `MainActivity` is the entry point and hosts the Compose UI.
   - `SdkConfig.kt` centralizes the SDK bootstrap parameters such as API key, platform, and timeout.
   - After initialization, the app routes into a navigation shell that switches between feature screens.

5. **Navigation and screen partitioning**
   - `navigation/AppNavigation.kt` provides the app-level navigation structure, including bottom navigation and the `NavHost`.
   - `navigation/Screen.kt` defines the screen routes.
   - The UI is intentionally split into three feature areas:
     - **Categories**
     - **Tickets**
     - **Articles**

6. **Shared UI layer**
   - `ui/components/ApiSectionCard.kt` is the reusable interaction unit: it presents an API action, a call button, and a response/status area.
   - `ui/components/ApiState.kt` holds the interaction state model used by those cards.
   - This creates a consistent request/response pattern across all API demonstrations.

7. **Categories feature flow**
   - `ui/screens/CategoriesScreen.kt` demonstrates the service-category APIs:
     - list categories
     - fetch category by ID
     - search categories
   - Each action builds the common user-context payload plus any endpoint-specific fields, then invokes the SDK.
   - Results are rendered back into the screen through the shared API state/card pattern.

8. **Tickets feature flow**
   - `ui/screens/TicketsScreen.kt` covers:
     - list tickets
     - create ticket
     - list ticket states
   - This screen is the main example of both read and write operations against the SDK.
   - Ticket creation shows the app’s pattern for sending richer payloads, including attachments as JSON arrays.

9. **Articles feature flow**
   - `ui/screens/ArticlesScreen.kt` demonstrates ticket article operations:
     - list ticket articles
     - add a ticket article
   - It follows the same request lifecycle as the other screens, but with ticket-centric pagination and comment/attachment fields.

10. **Data flow and threading model**
   - User taps a UI action in a screen.
   - The screen assembles a `JSONObject` containing required user identity fields plus endpoint-specific fields.
   - The app calls the SDK from a **background thread**, as required by the SDK contract.
   - The SDK returns either:
     - `onSuccess(String)` with a raw JSON response, or
     - `onError(ApiError)` with structured failure details.
   - Because callbacks are not guaranteed to be on the main thread, the UI layer must marshal updates back to the UI thread before rendering state changes.

11. **Presentation and theming**
   - `ui/theme/Color.kt`, `Theme.kt`, and `Type.kt` define the Compose visual system.
   - These files are purely presentation concerns; they do not affect API or navigation architecture.
   - The app is therefore cleanly split into theme, navigation, reusable components, and feature screens.

12. **Tests and support files**
   - `src/test` and `src/androidTest` contain the default sample test scaffolding.
   - `res/` contains standard Android resources such as app icons, theme XML, strings, and backup/data-extraction rules.
   - These are peripheral to the architecture; the core behavior is concentrated in the Compose screens and SDK wrapper usage.

Main entry points: [`app/src/main/java/com/synkroniqsdk/sampleapp/navigation/AppNavigation.kt`](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/navigation/AppNavigation.kt) (App navigation), [`app/libs/synkroniq1.0.0.aar`](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/libs/synkroniq1.0.0.aar) (Synkroniq AAR), [`app/src/main/java/com/synkroniqsdk/sampleapp/ui/theme/Theme.kt`](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/theme/Theme.kt) (Theme), [`app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/CategoriesScreen.kt`](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/CategoriesScreen.kt) (Categories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_root["Project"]
  node_node_build["Gradle build<br/>build system<br/>[build.gradle.kts]"]
  node_node_settings["Settings"]
end

subgraph group_group_app["App module"]
  node_node_module_build["App build<br/>android gradle<br/>[build.gradle.kts]"]
  node_node_manifest["Manifest"]
  node_node_main["MainActivity<br/>entry activity<br/>[MainActivity.kt]"]
  node_node_config["SDK config<br/>bootstrap config<br/>[SdkConfig.kt]"]
end

subgraph group_group_ui["Compose UI"]
  node_node_nav["App navigation<br/>compose navigation<br/>[AppNavigation.kt]"]
  node_node_routes["Screen routes<br/>route map<br/>[Screen.kt]"]
  node_node_api_card["API card<br/>shared component<br/>[ApiSectionCard.kt]"]
  node_node_api_state["API state<br/>ui state<br/>[ApiState.kt]"]
  node_node_categories["Categories<br/>feature screen"]
  node_node_tickets["Tickets<br/>feature screen<br/>[TicketsScreen.kt]"]
  node_node_articles["Articles<br/>feature screen<br/>[ArticlesScreen.kt]"]
  node_node_theme["Theme<br/>[Theme.kt]"]
end

subgraph group_group_sdk["SDK boundary"]
  node_node_aar[("Synkroniq AAR<br/>prebuilt sdk<br/>[synkroniq1.0.0.aar]")]
  node_node_backend[("Backend API<br/>external service")]
end

node_node_build -->|"project setup"| node_node_settings
node_node_settings -->|"includes module"| node_node_module_build
node_node_module_build -->|"depends on"| node_node_aar
node_node_module_build -->|"packages app"| node_node_manifest
node_node_manifest -->|"launches"| node_node_main
node_node_main -->|"initializes"| node_node_config
node_node_main -->|"hosts"| node_node_nav
node_node_nav -->|"uses"| node_node_routes
node_node_nav -->|"shows"| node_node_categories
node_node_nav -->|"shows"| node_node_tickets
node_node_nav -->|"shows"| node_node_articles
node_node_categories -->|"renders"| node_node_api_card
node_node_tickets -->|"renders"| node_node_api_card
node_node_articles -->|"renders"| node_node_api_card
node_node_api_card -->|"binds"| node_node_api_state
node_node_categories -->|"calls SDK"| node_node_aar
node_node_tickets -->|"calls SDK"| node_node_aar
node_node_articles -->|"calls SDK"| node_node_aar
node_node_aar -->|"proxies requests"| node_node_backend
node_node_theme -.->|"styles shell"| node_node_nav
node_node_theme -.->|"styles screen"| node_node_categories
node_node_theme -.->|"styles screen"| node_node_tickets
node_node_theme -.->|"styles screen"| node_node_articles

click node_node_build "https://github.com/mapnests/synkroniq-android-sdk/blob/master/build.gradle.kts"
click node_node_settings "https://github.com/mapnests/synkroniq-android-sdk/blob/master/settings.gradle.kts"
click node_node_module_build "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/build.gradle.kts"
click node_node_manifest "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/AndroidManifest.xml"
click node_node_main "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/MainActivity.kt"
click node_node_config "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/SdkConfig.kt"
click node_node_nav "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/navigation/AppNavigation.kt"
click node_node_routes "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/navigation/Screen.kt"
click node_node_api_card "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiSectionCard.kt"
click node_node_api_state "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiState.kt"
click node_node_categories "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/CategoriesScreen.kt"
click node_node_tickets "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/TicketsScreen.kt"
click node_node_articles "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/ArticlesScreen.kt"
click node_node_theme "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/theme/Theme.kt"
click node_node_aar "https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/libs/synkroniq1.0.0.aar"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_build,node_node_settings toneBlue
class node_node_module_build,node_node_manifest,node_node_main,node_node_config toneAmber
class node_node_nav,node_node_routes,node_node_api_card,node_node_api_state,node_node_categories,node_node_tickets,node_node_articles,node_node_theme toneMint
class node_node_aar,node_node_backend toneRose
```

## Components

### Project

Android sample app and build boundary

- [Gradle build](https://github.com/mapnests/synkroniq-android-sdk/blob/master/build.gradle.kts): build system · Root Gradle setup for the Android project · `build.gradle.kts`
- [Settings](https://github.com/mapnests/synkroniq-android-sdk/blob/master/settings.gradle.kts): gradle settings · Project/module wiring and repository configuration · `settings.gradle.kts`

### App module

Single Android application module

- [App build](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/build.gradle.kts): android gradle · Single-module Android app configuration and dependencies · `app/build.gradle.kts`
- [Manifest](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/AndroidManifest.xml): android manifest · Application entry and Android component declarations · `app/src/main/AndroidManifest.xml`
- [MainActivity](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/MainActivity.kt): entry activity · App entry point hosting the Compose UI · `app/src/main/java/com/synkroniqsdk/sampleapp/MainActivity.kt`
- [SDK config](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/SdkConfig.kt): bootstrap config · Centralized SDK initialization parameters · `app/src/main/java/com/synkroniqsdk/sampleapp/SdkConfig.kt`

### Compose UI

Navigation, screens, shared components, and theme

- [App navigation](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/navigation/AppNavigation.kt): compose navigation · Top-level navigation shell and bottom navigation · `app/src/main/java/com/synkroniqsdk/sampleapp/navigation/AppNavigation.kt`
- [Screen routes](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/navigation/Screen.kt): route map · Named destinations used by the navigation host · `app/src/main/java/com/synkroniqsdk/sampleapp/navigation/Screen.kt`
- [API card](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiSectionCard.kt): shared component · Reusable action card with trigger and response area · `app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiSectionCard.kt`
- [API state](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiState.kt): ui state · Interaction state model for API request/response flows · `app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiState.kt`
- [Categories](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/CategoriesScreen.kt): feature screen · Service-category API demonstrations · `app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/CategoriesScreen.kt`
- [Tickets](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/TicketsScreen.kt): feature screen · Ticket listing, creation, and state APIs · `app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/TicketsScreen.kt`
- [Articles](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/ArticlesScreen.kt): feature screen · Ticket article listing and creation APIs · `app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/ArticlesScreen.kt`
- [Theme](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/src/main/java/com/synkroniqsdk/sampleapp/ui/theme/Theme.kt): compose theme · App colors, typography, and Material styling · `app/src/main/java/com/synkroniqsdk/sampleapp/ui/theme/Theme.kt`

### SDK boundary

Local AAR dependency and external backend/API contract

- [Synkroniq AAR](https://github.com/mapnests/synkroniq-android-sdk/blob/master/app/libs/synkroniq1.0.0.aar): prebuilt sdk · Local binary SDK consumed by the app · `app/libs/synkroniq1.0.0.aar`
- **Backend API**: external service · Synkroniq backend accessed through the SDK

## Connections

- Gradle build → Settings: project setup · Root build participates in project configuration
- Settings → App build: includes module · Settings wires the app module into the build
- App build → Synkroniq AAR: depends on · App consumes the local prebuilt SDK artifact
- App build → Manifest: packages app · Android module defines the application package
- Manifest → MainActivity: launches · Manifest declares the entry activity
- MainActivity → SDK config: initializes · Activity bootstraps SDK configuration and app startup
- MainActivity → App navigation: hosts · Activity renders the Compose navigation shell
- App navigation → Screen routes: uses · Navigation shell is driven by route definitions
- App navigation → Categories: shows · Routes to categories feature screen
- App navigation → Tickets: shows · Routes to tickets feature screen
- App navigation → Articles: shows · Routes to articles feature screen
- Categories → API card: renders · Uses shared API interaction cards
- Tickets → API card: renders · Uses shared API interaction cards
- Articles → API card: renders · Uses shared API interaction cards
- API card → API state: binds · Card UI is driven by reusable state model
- Categories → Synkroniq AAR: calls SDK · Category actions invoke the Synkroniq SDK
- Tickets → Synkroniq AAR: calls SDK · Ticket actions invoke the Synkroniq SDK
- Articles → Synkroniq AAR: calls SDK · Article actions invoke the Synkroniq SDK
- Synkroniq AAR → Backend API: proxies requests · SDK forwards API calls to the external backend
- Theme → App navigation: styles shell · Compose theme supports navigation UI
- Theme → Categories: styles screen · Theme is shared across feature screens
- Theme → Tickets: styles screen · Theme is shared across feature screens
- Theme → Articles: styles screen · Theme is shared across feature screens