Cat Facts Codex 🐱

Cat Facts Codex is a minimalist Android application that showcases a modern, testable Compose stack. It fetches random cat facts from the public catfact.ninja API and lets you request fresh facts on demand.

Built 100% by Codex using GPT-5.

Features

• Material 3 UI built entirely with Jetpack Compose.
• MVVM presentation layer backed by Kotlin coroutines and StateFlow.
• Manual dependency container that wires Retrofit, OkHttp, and kotlinx.serialization.
• Clear loading, success, and error states with retry support.
• Unit-tested ViewModel logic using TestDispatcher and fake repositories.

Tech Stack

• Kotlin, Jetpack Compose, Material 3
• AndroidX Lifecycle (ViewModel, Compose integration)
• Kotlin coroutines & StateFlow
• Retrofit 2 + kotlinx.serialization converter
• OkHttp with logging interceptor

Architecture

flowchart TD
    subgraph UI["UI Layer (Jetpack Compose)"]
        CatFactScreen["CatFactScreen"]
    end

    subgraph Presentation["Presentation Layer"]
        CatFactViewModel["CatFactViewModel\n(StateFlow + Coroutines)"]
    end

    subgraph Domain["Domain Layer"]
        CatFactRepository["CatFactRepository\n(Interface)"]
    end

    subgraph Data["Data Layer"]
        CatFactRepositoryImpl["CatFactRepositoryImpl"]
        CatFactApiService["CatFactApiService"]
        CatFactDto["CatFactDto"]
    end

    subgraph Platform["Platform Services"]
        Retrofit["Retrofit + OkHttp"]
        CatFactApi["catfact.ninja API"]
    end

    AppContainer["DefaultAppContainer\n(Dependency Provider)"]
    App["CatFactsApplication"]

    CatFactScreen -->|collects state| CatFactViewModel
    CatFactViewModel -->|calls| CatFactRepository
    CatFactRepository -->|implemented by| CatFactRepositoryImpl
    CatFactRepositoryImpl -->|requests| CatFactApiService
    CatFactApiService -->|parses| CatFactDto
    CatFactApiService --> Retrofit --> CatFactApi

    AppContainer -->|provides| CatFactRepositoryImpl
    App -->|exposes| AppContainer
    CatFactViewModel -->|obtains deps from| AppContainer

Loading

app/
├── data/              # Retrofit service + repository implementation
├── di/                # Application-level dependency container
├── domain/            # Domain models and repository abstraction
├── ui/                # Compose screens, ViewModel, UI state
└── CatFactsApplication.kt

• Presentation — CatFactViewModel exposes a StateFlow<CatFactUiState> consumed by Compose.
• Domain — CatFactRepository defines the contract for fetching facts.
• Data — CatFactRepositoryImpl bridges the API service (CatFactApiService) with the domain layer.
• DI — DefaultAppContainer wires dependencies and is exposed via CatFactsApplication.

Getting Started

Prerequisites

• Android Studio Ladybug or newer (with JDK 17 configured)
  If running Gradle from the CLI, ensure JAVA_HOME points to a compatible JDK.
• An Android device or emulator (API level 24+)

Setup

1. Clone the repository:

   git clone https://github.com/<your-username>/cat-facts-codex.git
   cd cat-facts-codex

2. Open the project in Android Studio and let Gradle sync.

Run the app

• Choose a device (physical or emulator) and press Run from Android Studio, or invoke:

  ./gradlew installDebug

Run tests

./gradlew test

Note: The command requires a local JDK. If you see “Unable to locate a Java Runtime”, install a JDK (Temurin/OpenJDK 17+), update JAVA_HOME, and rerun.

API

• Endpoint: GET https://catfact.ninja/fact
• Response sample:

  {
    "fact": "Cats can jump up to six times their length.",
    "length": 52
  }

Contributing

Issues and pull requests are welcome. Feel free to suggest improvements, new features, or additional tests.

---

Enjoy the cat facts! 😺

---

Original Prompt

“This is a default android project. I need you to fully write an app that fetches a cat fact from this API https://catfact.ninja/ and displays it in the UI. Add a button to fetch a new cat fact. Make it using the latest trends in Android Architecture. And make it testable.”

The starting point was an Android Studio “Empty Activity” template; everything else was generated collaboratively with Codex (GPT-5).