Тарас Шевченко ✦

Welcome to "Тарас Шевченко ✦", a Compose Multiplatform project designed to deliver a cohesive reading experience across Android, iOS, Web, and Desktop. This project aims to celebrate the lyrical beauty of Taras Shevchenko's poetry.

Testing the App:

Join our testing program and provide valuable feedback:

• Android App Tester Invite
• iOS TestFlight Invite

PROJECT SPECIFICATION

• Programming language: Kotlin;

• Framework: Compose Multiplatform;

• SDK: Kotlin Multiplatform;

• Interface: Compose;

• Version control system: Git;

• Git Hosting Service: GitHub;

• Code Readability: code is easily readable with no unnecessary blank lines, no unused variables or methods, and no commented-out code, all variables, methods, and resource IDs are descriptively named such that another developer reading the code can easily understand their function.

• Architectural pattern: Monolith;

Project Structure

• /composeApp: Contains shared code for the Compose Multiplatform applications.

  • commonMain: Houses the common code for all targets.
  • Platform-specific folders (e.g., iosMain, androidMain): These contain code for specific platforms like CoreCrypto for iOS in the iosMain folder.

• /iosApp: Contains the iOS applications. Despite sharing UI code, this serves as the entry point for the iOS app and can include Swift/SwiftUI code if needed.

About the Project

Overview

"Тарас Шевченко ✦" is a digital collection of Taras Shevchenko's works, offering a seamless reading experience with draggable dividers and elegant page transitions. It supports multiple platforms through Compose Multiplatform, sharing a unified codebase.

Features

• Platform Support: A single codebase approach for Android, iOS, Web, and Desktop.
• Interactive UI: Draggable dividers allowing users to switch between the text and images effortlessly.
• Swipe Gestures: Smooth page transitions with horizontal drag gestures.
• Multilingual Support: Access Shevchenko's poetry in its native language.
• Authentic Scans: Includes scanned book spreads of the original "Мала Книжка" with the actual handwriting of Taras Shevchenko, offering a glimpse into the early Ukrainian language and script.

Credits

This project utilizes book spreads and texts from the website t-shevchenko.name. The site's creators kindly allow reproduction with proper referencing. * *Передрук статей із сайту заохочується за умови посилання (гіперпосилання) на наш сайт**. Many thanks for their valuable contributions.

The implementation of this project was inspired by the Get started with Compose Multiplatform – tutorial provided by JetBrains. Their resources were instrumental in guiding the development process.

Getting Started

To get started, ensure you have the necessary development environments for each target platform. For detailed guidelines, refer to the following:

• Kotlin Multiplatform
• Compose Multiplatform
• Kotlin/Wasm

Building and Running the Project

Web Application

Development: Build and run the web application using this Gradle task:

./gradlew :composeApp:wasmJsBrowserDevelopmentRun

Production: To build a production version of the web application and deploy it to Firebase Hosting:

1. Build the production executable:

   ./gradlew :composeApp:wasmJsBrowserDistribution

2. Deploy to Firebase Hosting:

   firebase deploy --only hosting

Troubleshooting: If the build fails with an error like Lock file was changed. Run the 'kotlinWasmUpgradeYarnLock' task to actualize lock file, execute:

./gradlew kotlinWasmUpgradeYarnLock

Browser Compatibility: The web application is specifically designed to run within Google Chrome. While other browsers may technically load the application, they may not display it correctly or support all features. For the best experience, use Google Chrome.

Backend AI Server

To run the AI backend server locally:

1. Configure Environment Variables: Create a server/.env file in the project root and add your API keys:

   GROQ_API_KEY=your_key
   MISTRAL_API_KEY=your_key
   GEMINI_API_KEY=your_key

2. Run the Server:

   ./gradlew :server:run

3. Run Tests: To run the backend unit tests (fallback logic, API structure, etc.):

   ./gradlew :server:test

4. Stop the Server:

   • In the terminal: Press Control + C.
   • In Android Studio: Click the Red Square (Stop) button in the Run tool window.
   • If the process is stuck: kill -9 $(lsof -t -i:8080) (assuming default port 8080).

5. Test the API: You can test the chat endpoint using curl:

   Local:

   curl -X POST http://localhost:8080/chat \
   -H "Content-Type: application/json" \
   -d '{
     "message": "Що ви щойно сказали?",
     "history": [
       {"role": "user", "content": "Привіт, Тарасе!"},
       {"role": "assistant", "content": "Добрий день! Я — Тарас..."}
     ],
     "pageNumber": 10,
     "pageText": "Учітесь, читайте, і чужому научайтесь, й свого не цурайтесь."
   }'

   Production:

   curl -X POST https://mala-knyzhka-server-593576053721.northamerica-northeast1.run.app/chat \
   -H "Content-Type: application/json" \
   -d '{
     "message": "Привіт, Тарасе!",
     "pageNumber": 1,
     "pageText": "Думи мої..."
   }'

   Example Response:

   {
       "answer": "Добрий день, молодій людино! Як ти бачиш на сторінці 10 моєї \"Малої Книжки\"...",
       "providerUsed": "groq"
   }

Postman Testing

To test the AI backend in Postman:

1. Create Request: Click New → HTTP Request. Set method to **POST **.
2. Enter URL: https://mala-knyzhka-server-593576053721.northamerica-northeast1.run.app/chat
3. Headers: In the Headers tab, ensure Content-Type is set to application/json.
4. Body: In the Body tab, select raw → JSON and use:

   {
     "message": "Що ви щойно сказали?",
     "history": [
       {"role": "user", "content": "Привіт, Тарасе!"},
       {"role": "assistant", "content": "Добрий день! Я — Тарас..."}
     ],
     "pageNumber": 1,
     "pageText": "Думи мої..."
   }

5. Send: Click the blue Send button and verify the response.

Cloud Run Deployment

To deploy the backend to Google Cloud Run:

1. Build and Push Image: Use Google Cloud Build to create and push the Docker image to Artifact Registry:

   gcloud builds submit --tag gcr.io/mala-knyzhka/mala-knyzhka-server

2. Deploy to Cloud Run:

   gcloud run deploy mala-knyzhka-server \
     --image gcr.io/mala-knyzhka/mala-knyzhka-server \
     --platform managed \
     --region northamerica-northeast1 \
     --allow-unauthenticated

3. Update Environment Variables: Ensure the following environment variables are set in the Cloud Run service configuration:

   • GROQ_API_KEY
   • MISTRAL_API_KEY
   • GEMINI_API_KEY

   You can update them via the Google Cloud Console or using:

   gcloud run services update mala-knyzhka-server \
     --set-env-vars GROQ_API_KEY=your_key,MISTRAL_API_KEY=your_key,GEMINI_API_KEY=your_key

How to Contribute

We welcome contributions to enhance this project. Here's how you can contribute:

• Report Issues: Encountered a bug or have a suggestion? Report issues on GitHub.

Enjoy the poetic journey! 🌟

Screenshots:

Download