build: establish Kotlin library foundation and shared contract

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: gradle
+      - uses: gradle/actions/setup-gradle@v4
+      - name: Validate wrapper
+        uses: gradle/actions/wrapper-validation@v4
+      - name: Build, test, lint, and verify local publication
+        run: ./gradlew build lint :flextrack:publishToMavenLocal --stacktrace

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- Android library and sample module foundation.
+- Maven publication metadata and local publishing support.
+- FlexTrack Core Specification 1.0.0 contract baseline.
+- CI quality gates for build, unit tests, lint, and publication verification.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Reza Taghizadeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,37 @@
+# FlexTrack Kotlin
+
+Native Android/Kotlin implementation of FlexTrack: consent-aware analytics
+routing with deterministic cross-SDK behavior.
+
+The Kotlin SDK targets Android API 21+ and implements
+[FlexTrack Core Specification 1.0.0](contract/README.md), shared with
+[FlexTrack Flutter 2.1.0](https://pub.dev/packages/flex_track).
+
+## Project status
+
+The SDK is under active development toward Kotlin 1.0.0. The current version is
+`0.1.0-SNAPSHOT` and is not ready for production use.
+
+## Modules
+
+- `flextrack`: publishable Android library (`AAR`).
+- `sample`: Android application that consumes `flextrack` as a project dependency.
+- `contract`: shared specification and deterministic Flutter/Kotlin fixtures.
+
+## Build
+
+```bash
+./gradlew build
+./gradlew :flextrack:publishToMavenLocal
+```
+
+## Roadmap
+
+1. Library foundation and shared contract.
+2. Event, enrichment, routing, consent, and deterministic sampling.
+3. Tracker runtime, client lifecycle, debug records, and conformance.
+4. Sample application, documentation, and Kotlin 1.0.0 release.
+
+## License
+
+MIT

build.gradle.kts

@@ -1,5 +1,6 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
     alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.android.library) apply false
     alias(libs.plugins.kotlin.android) apply false
-}
+}

contract/README.md

@@ -0,0 +1,22 @@
+# FlexTrack shared contract
+
+This directory contains the language-neutral inputs used to keep the Flutter
+and Kotlin SDKs behaviorally compatible.
+
+- Core specification: `1.0.0`
+- Fixture version: `1.0.0`
+- Flutter reference: `flex_track` `v2.1.0`
+- Flutter reference commit: `78d7f46c2479b9680268ab794443375e3959d441`
+
+Canonical sources:
+
+- [Core MVP specification](https://github.com/alirezat66/flex_track/blob/v2.1.0/doc/core-mvp-specification.md)
+- [Conformance runner contract](https://github.com/alirezat66/flex_track/blob/v2.1.0/doc/conformance.md)
+- [Flutter fixtures](https://github.com/alirezat66/flex_track/tree/v2.1.0/test/fixtures/conformance)
+
+The JSON files in this directory are vendored so Kotlin CI never depends on
+network availability or a moving Flutter branch. Updates require an explicit
+fixture version change and source-reference update.
+
+Queues, persistence, retry/backoff, session management, SDK-owned identity,
+and optimized batching are intentionally outside Core MVP 1.0.0.

contract/core_mvp.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextrack.taghizadeh.dev/schemas/core-mvp-1.0.0.json",
+  "title": "FlexTrack Core MVP conformance fixtures",
+  "type": "object",
+  "required": ["specVersion", "fixtureVersion", "cases"],
+  "properties": {
+    "specVersion": {"const": "1.0.0"},
+    "fixtureVersion": {"type": "string", "pattern": "^1\\.[0-9]+\\.[0-9]+$"},
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "behavior", "input", "expected"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "behavior": {
+            "enum": ["routing", "consent", "sampling", "enrichment", "debug"]
+          },
+          "input": {"type": "object"},
+          "expected": {"type": "object"}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

contract/core_mvp_cases.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "core_mvp.schema.json",
+  "specVersion": "1.0.0",
+  "fixtureVersion": "1.0.0",
+  "cases": [
+    {
+      "id": "routing.priority-overlap",
+      "behavior": "routing",
+      "input": {
+        "event": {"name": "purchase", "category": "business"},
+        "availableTrackers": ["analytics", "archive"],
+        "rules": [
+          {"category": "business", "priority": 10, "targets": ["analytics"]},
+          {"default": true, "priority": 0, "targets": ["archive"]}
+        ]
+      },
+      "expected": {"targets": ["analytics"], "appliedPriorities": [10]}
+    },
+    {
+      "id": "routing.same-tier-merge",
+      "behavior": "routing",
+      "input": {
+        "event": {"name": "purchase"},
+        "availableTrackers": ["analytics", "archive"],
+        "rules": [
+          {"nameContains": "purchase", "priority": 5, "targets": ["analytics"]},
+          {"nameContains": "purchase", "priority": 5, "targets": ["archive", "analytics"]}
+        ]
+      },
+      "expected": {"targets": ["analytics", "archive"], "appliedPriorities": [5, 5]}
+    },
+    {
+      "id": "routing.default-group-fallback",
+      "behavior": "routing",
+      "input": {
+        "event": {"name": "unmatched"},
+        "availableTrackers": ["archive"],
+        "defaultGroup": ["archive"],
+        "rules": [{"nameContains": "purchase", "priority": 5, "targets": ["archive"]}]
+      },
+      "expected": {"targets": ["archive"], "appliedPriorities": [0]}
+    },
+    {
+      "id": "consent.general-missing",
+      "behavior": "consent",
+      "input": {
+        "event": {"name": "view", "requiresConsent": true},
+        "generalConsent": false,
+        "piiConsent": false,
+        "rule": {"requireConsent": true, "targets": ["analytics"]}
+      },
+      "expected": {"targets": [], "skipReasons": ["Consent requirements not met"]}
+    },
+    {
+      "id": "consent.pii-missing",
+      "behavior": "consent",
+      "input": {
+        "event": {"name": "profile", "containsPII": true, "requiresConsent": true},
+        "generalConsent": true,
+        "piiConsent": false,
+        "rule": {"requireConsent": true, "requirePIIConsent": true, "targets": ["analytics"]}
+      },
+      "expected": {"targets": [], "skipReasons": ["Consent requirements not met"]}
+    },
+    {
+      "id": "sampling.unicode-utf8",
+      "behavior": "sampling",
+      "input": {"identity": "नमस्ते", "sampleRate": 0.25},
+      "expected": {"hash": 538106393, "accepted": true}
+    },
+    {
+      "id": "enrichment.identity-and-properties",
+      "behavior": "enrichment",
+      "input": {
+        "eventId": "fixture-event-1",
+        "timestamp": "2026-08-17T12:30:00.000Z",
+        "name": "purchase",
+        "properties": {"plan": "free"},
+        "extraProperties": {"plan": "pro", "route": "/pay"}
+      },
+      "expected": {
+        "eventId": "fixture-event-1",
+        "timestamp": "2026-08-17T12:30:00.000Z",
+        "name": "purchase",
+        "properties": {"plan": "pro", "route": "/pay"}
+      }
+    },
+    {
+      "id": "debug.routing-decision",
+      "behavior": "debug",
+      "input": {
+        "event": {"name": "purchase"},
+        "availableTrackers": ["analytics"],
+        "rules": [{"nameContains": "purchase", "priority": 7, "targets": ["analytics"]}]
+      },
+      "expected": {"targetTrackers": ["analytics"], "successfulTrackerIds": ["analytics"]}
+    }
+  ]
+}

doc/architecture.md

@@ -0,0 +1,27 @@
+# Architecture
+
+FlexTrack Kotlin follows the language-neutral Core Specification rather than a
+line-by-line Dart translation.
+
+The `flextrack` module is organized into four layers:
+
+1. **Model** — immutable events, routing rules, groups, and result values.
+2. **Policy** — enrichment, consent gates, deterministic sampling, and routing.
+3. **Runtime** — tracker registry, event processor, and isolated clients.
+4. **Diagnostics** — debug decisions and conformance reporting.
+
+Android framework usage stays at the library boundary. Core decisions remain
+deterministic JVM-testable Kotlin so they can be compared directly with the
+shared Flutter fixtures. Offline persistence, retries, and SDK-owned identity
+are deliberately deferred until a later versioned contract.
+
+## Module dependency direction
+
+```text
+sample -> flextrack
+
+diagnostics -> runtime -> policy -> model
+```
+
+Dependencies MUST point to the right in this diagram. The Core model never
+depends on tracker vendors, application code, or the sample module.

flextrack/.gitignore

@@ -0,0 +1 @@
+/build

flextrack/build.gradle.kts

@@ -0,0 +1,88 @@
+plugins {
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.android)
+    `maven-publish`
+}
+
+group = "dev.taghizadeh.flextrack"
+version = "0.1.0-SNAPSHOT"
+
+android {
+    namespace = "dev.taghizadeh.flextrack"
+    compileSdk {
+        version = release(36)
+    }
+
+    defaultConfig {
+        minSdk = 21
+        consumerProguardFiles("consumer-rules.pro")
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+
+    kotlinOptions {
+        jvmTarget = "11"
+    }
+
+    testOptions {
+        unitTests.all {
+            it.useJUnitPlatform()
+        }
+    }
+
+    publishing {
+        singleVariant("release") {
+            withSourcesJar()
+        }
+    }
+}
+
+dependencies {
+    testImplementation(libs.junit.jupiter)
+}
+
+publishing {
+    publications {
+        register<MavenPublication>("release") {
+            groupId = project.group.toString()
+            artifactId = "flextrack"
+            version = project.version.toString()
+
+            afterEvaluate {
+                from(components["release"])
+            }
+
+            pom {
+                name.set("FlexTrack Kotlin")
+                description.set("Consent-aware, deterministic analytics routing for Android and Kotlin.")
+                url.set("https://github.com/alirezat66/flex_track_kotlin")
+                licenses {
+                    license {
+                        name.set("MIT License")
+                        url.set("https://opensource.org/licenses/MIT")
+                    }
+                }
+                developers {
+                    developer {
+                        id.set("alirezat66")
+                        name.set("Reza Taghizadeh")
+                    }
+                }
+                scm {
+                    url.set("https://github.com/alirezat66/flex_track_kotlin")
+                    connection.set("scm:git:https://github.com/alirezat66/flex_track_kotlin.git")
+                    developerConnection.set("scm:git:ssh://git@github.com/alirezat66/flex_track_kotlin.git")
+                }
+            }
+        }
+    }
+}

flextrack/consumer-rules.pro

@@ -0,0 +1 @@
+# FlexTrack has no reflection-based runtime in the Core MVP.

flextrack/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest />

flextrack/src/main/kotlin/dev/taghizadeh/flextrack/FlexTrack.kt

@@ -0,0 +1,10 @@
+package dev.taghizadeh.flextrack
+
+/** Package metadata for the FlexTrack Kotlin SDK. */
+public object FlexTrack {
+    /** Current pre-release SDK version. */
+    public const val VERSION: String = "0.1.0-SNAPSHOT"
+
+    /** Language-neutral FlexTrack Core specification implemented by this SDK. */
+    public const val CORE_SPEC_VERSION: String = "1.0.0"
+}