Quorra is a high-performance Decision-Intelligence (DI) platform for Android. It transforms complex, fragmented operational data into explainable, auditable, and trustworthy recommendations using a Human-on-the-Loop (HOTL) approach.
Designed for multi-facility enterprises, Quorra bridges the gap between passive Business Intelligence (dashboards) and opaque automation, providing managers with the tools to simulate, decide, and learn from operational outcomes.
- Business Problem & Overview
- Target Users & Personas
- Key Features & Business Value
- Technology Stack
- System Architecture
- Project Structure
- Environment Configuration
- Local Development Setup
- Operational Best Practices
- Troubleshooting & FAQ
- Contribution & License
Modern enterprises are "drowning in dashboards but starving for decisions." Fragmented data across ERP, CRM, and WMS systems leads to:
- Decision Paralysis: Managers can't absorb data fast enough to act.
- Trust Deficit: Black-box AI recommendations are ignored because they lack reasoning.
- High Reversal Costs: Misallocated inventory or mispriced contracts are expensive to unwind.
Quorra introduces a Reasoning Layer over enterprise data. Every recommendation comes with a plain-language justification, a dual-confidence score (Data vs. Model), and a sandbox laboratory for "What If" simulation.
| Persona | Responsibility | Core Use Case |
|---|---|---|
| Operator | P&L Owner / Facility Lead | Monitors the feed for stock-outs or risk; simulates recovery paths. |
| Approver | Audit / Finance Lead | Reviews high-stakes escalations and signs off on capital commitments. |
| Configurer | Data Manager / IT Admin | Manages "Playbook" logic and monitors upstream data source health. |
| Admin | System Administrator | Sets governance rules and manages cross-facility permissions. |
- π Prioritized Recommendation Feed: Actionable insights ranked by financial impact and urgency.
- π§ͺ Simulation Laboratory ("What If Room"): Sandboxed environment to test variables (e.g., "What if the shipment is 2 days late?") before committing.
- π‘οΈ Immutable Audit Ledger: A verified "Black Box" recording every decision, persona, and reasoning for compliance.
- π Executive Analytics (Learning Loop): Real-time tracking of recommendation accuracy and net business impact.
- ποΈ Governance Engine: Automated escalation rules based on financial thresholds or confidence deficits.
- π‘ Data Source Integrity: Real-time monitoring of the "connective tissue" (SAP, WMS, CRM connections).
- π± Kotlin 2.1.0: Modern, concise language for Android development.
- π¨ Jetpack Compose: Declarative UI framework for the modern "Command Center" aesthetic.
- π Material 3: Standardized design system for premium enterprise visuals.
- π Canvas API: Custom high-performance charting for trendlines and gauges.
- π Room Database: Local SQLite persistence for offline-first operational reliability.
- π° Retrofit 2.11: Type-safe HTTP client for enterprise API synchronization.
- 𧬠Coroutines & StateFlow: Reactive, multi-threaded state management.
- π¦ Gson: High-performance JSON serialization for complex data models.
- π KSP (Kotlin Symbol Processing): Next-gen annotation processing for Room.
- π Gradle (Kotlin DSL): Robust build automation.
- π§ͺ MockK & JUnit: Industry-standard unit testing.
- π Android Notifications: High-importance channels for critical early warnings.
graph TD
subgraph Mobile_App [Quorra Android Application]
UI[Jetpack Compose UI]
VM[MainViewModel]
REPO[QuorraRepository - SSOT]
LOCAL[(Room SQLite DB)]
end
subgraph External_Services [Enterprise Infrastructure]
API[REST API Service]
ERP[SAP ERP / WMS]
CRM[Salesforce CRM]
end
UI <--> VM
VM <--> REPO
REPO <--> LOCAL
REPO <--> API
API <--> ERP
API <--> CRM
Responsibilities:
- UI Layer: Declarative components that observe StateFlow and render based on the current Persona/Facility context.
- ViewModel: Manages UI state, navigation logic, and triggers repository refreshes.
- Repository (SSOT): The Single Source of Truth. Manages the logic between local persistence (Room) and remote synchronization.
- Local DB: Ensures the platform remains functional in low-connectivity facility environments.
sequenceDiagram
participant U as User
participant V as ViewModel
participant R as Repository
participant D as Room DB
participant N as Network (API)
U->>V: Trigger Decision (Approve)
V->>V: Show Reasoning Dialog
U->>V: Provide Reasoning
V->>R: makeDecision(id, notes)
R->>D: Insert AuditLog & Update Status
R->>N: Sync Decision to Backend
D-->>V: Flow Emit Updated State
V-->>U: Update Feed (Success)
com.example.quorra
βββ data
β βββ local # Room Database, DAOs, and Type Converters
β βββ model # Core Domain Entities (Recommendation, Playbook, etc.)
β βββ remote # Retrofit API definitions and HTTP Client
β βββ repository # Single Source of Truth (SSOT) logic
βββ ui
β βββ components # Reusable UI Atoms (ConfidenceMeter, Badges, etc.)
β βββ theme # Modern Navy/Teal Color System & Typography
β βββ util # Notification and Helper utilities
β βββ *Screen.kt # High-level Screen definitions (Feed, Lab, Analytics)
βββ MainActivity.kt # Entry point & Global Navigation Controller
Quorra requires specific environment variables for backend integration. Duplicate .env.example to .env (or configure local.properties):
# Example local.properties config
QUORRA_API_BASE_URL="https://api.example.com/v1/"
ENABLE_CRITICAL_NOTIFICATIONS=true- Android Studio Ladybug (or newer)
- JDK 17
- Android SDK 34+
- Kotlin 2.1.0
- Clone the repository:
git clone https://github.com/alfinohatta/quorra.git
- Open the project in Android Studio.
- Sync Gradle and ensure all dependencies are resolved.
- Debug Build: Use the
app:assembleDebugtask or press Run in Android Studio. - Unit Tests:
./gradlew test
- Data Isolation: All recommendations are filtered by
companyIdto support multi-tenancy. - Audit Integrity: Decision logs are designed to be append-only (immutable) in the production backend.
- Persona Restrictions: UI elements (e.g., "Approve" buttons) are reactively disabled based on the
UserRoleof the active session.
Q: Why am I not seeing recommendations? A: Ensure your active Persona is set correctly and the "Facility Switcher" is targeting a region with active data.
Q: How are confidence scores calculated?
A: Data Confidence measures input signal health; Model Confidence measures prediction stability. See RecommendationItem.kt for visual thresholds.
- Fork the repo and create your branch from
main. - Ensure all UI components follow the navy/teal theme in
Theme.kt. - Document all new DAOs in the
QuorraDaointerface.
Distributed under the License. See LICENSE for more information.
- Human-on-the-Loop: Never automate "Approved" status for items with
RiskLevel.HIGH. - Reasoning Requirement: Always enforce the reasoning dialog for overrides to maintain ledger integrity.
- Early Warnings: Use the high-importance notification channel for
UrgencyLevel.CRITICALalerts only.