How mapnests/synkroniq-android-sdk works
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 JSONObjects 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: AppNavigation.kt App navigation · synkroniq1.0.0.aar Synkroniq AAR · Theme.kt Theme · CategoriesScreen.kt Categories
Components 16
Project
Android sample app and build boundary
- Gradle build · Root Gradle setup for the Android project
build.gradle.kts - Settings · Project/module wiring and repository configuration
settings.gradle.kts
App module
Single Android application module
- App build · Single-module Android app configuration and dependencies
app/build.gradle.kts - Manifest · Application entry and Android component declarations
app/src/main/AndroidManifest.xml - MainActivity · App entry point hosting the Compose UI
app/src/main/java/com/synkroniqsdk/sampleapp/MainActivity.kt - SDK config · Centralized SDK initialization parameters
app/src/main/java/com/synkroniqsdk/sampleapp/SdkConfig.kt
Compose UI
Navigation, screens, shared components, and theme
- App navigation · Top-level navigation shell and bottom navigation
app/src/main/java/com/synkroniqsdk/sampleapp/navigation/AppNavigation.kt - Screen routes · Named destinations used by the navigation host
app/src/main/java/com/synkroniqsdk/sampleapp/navigation/Screen.kt - API card · Reusable action card with trigger and response area
app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiSectionCard.kt - API state · Interaction state model for API request/response flows
app/src/main/java/com/synkroniqsdk/sampleapp/ui/components/ApiState.kt - Categories · Service-category API demonstrations
app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/CategoriesScreen.kt - Tickets · Ticket listing, creation, and state APIs
app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/TicketsScreen.kt - Articles · Ticket article listing and creation APIs
app/src/main/java/com/synkroniqsdk/sampleapp/ui/screens/ArticlesScreen.kt - 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 · Local binary SDK consumed by the app
app/libs/synkroniq1.0.0.aar - Backend API · Synkroniq backend accessed through the SDK
Connections 23
- 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