# stcvit/livstory architecture

> Architecture diagram of the GitHub repository stcvit/livstory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stcvit/livstory
- Repository: https://github.com/stcvit/livstory

## Overview

Based on our analysis of the file tree and README content, LivStory is an Android-based mobile application system that brings stories to life by incorporating real-time sound effects using Natural Language Processing. The project is structured into multiple key components:

##### Android Client Applications
- There are two Android projects (“AdminApp” and “App”) that represent different facets of the LivStory ecosystem. The “App” module is the primary user-facing application, featuring activities (MainActivity, SplashActivity, SignInActivity, etc.), adapters, fragments, and various UI layouts. The presence of Retrofit2 in the dependencies indicates that this app makes network calls.
- The “AdminApp” could be used for administrative purposes or testing variations, following a similar Android project structure.
- Both projects follow standard Android architecture patterns with separate layers for UI (activities, fragments, layouts), business logic (Java classes, adapters), and integrations (Retrofit for REST communication).

##### Backend – Flask API with ML Integration
- The “Backend” folder contains a Flask API (in the flask_api directory) which hosts the ML model. The README mentions that this ML model, which utilizes text-rank algorithms for identifying key words in input text, is hosted on Azure.
- The backend folder includes Python scripts, a Jupyter Notebook (LivStoryModelFinalDraft.ipynb), and a requirements file, outlining its dependencies as well as integration with Natural Language Toolkit (nltk) and other libraries.
- This component is essential for processing the text data sent by the mobile clients and returning appropriate sound recommendations.

##### External and Supporting Services
- Firebase is used for analytics, crash reporting (Firebase Analytics and Crashlytics), and to store the collection of sounds.
- Azure is mentioned as the hosting platform for the ML model provided by the Flask API.
- There is also a “Privacy Policy” directory which includes configuration files (e.g., firebase.json) and static assets for public hosting, indicating additional support for the mobile ecosystem.

A. Identify the Main Components:
- Mobile Client Layer:
– Primary Android Application (“App”) that interacts with users.
– Admin/Secondary Android Application (“AdminApp”), if applicable.
- API/Middleware Layer:
– Flask API (hosted on Azure) that processes text input using the ML model based on text-rank. This API is the core “intelligence” service.
- Data and External Services:
– Firebase is used for storing sound assets, tracking app crashes, and analytics.
– Azure infrastructure where the machine learning model is deployed.
– External dependencies (Retrofit2, Firebase libraries, etc.) that manage communications and data processing.

B. Determine Relationships and Interactions:
- The client apps send user-generated data (e.g., spoken or input text) to the Flask API using Retrofit2 over HTTP/HTTPS.
- The Flask API receives and processes the text (utilizing the text-rank algorithm and other NLP operations) and returns a response that maps to a specific sound effect.
- Sound assets are dynamically retrieved from Firebase, either by the API or directly by the mobile app, depending on the implementation.
- Analytics and crash reports from the client apps flow into Firebase for monitoring and diagnostic purposes.

C. Emphasize Important Architectural Patterns/Principles:
- Separation of concerns: Distinct mobile client layer, server-side processing, and external service integration.
- Client-Server Communication: Clear API boundaries using RESTful calls (facilitated by Retrofit2) between the Android apps and the Flask API.
- Modular design: The Android projects are modularized (with packages for adapters, fragments, models, and utilities) and the backend is isolated within its own directory structure.
- Scalability, as both the client and server rely on external cloud resources (Azure and Firebase).

D. Include Relevant Technologies:
- Android/Java (Activities, Fragments, Adapters)
- Retrofit2 for API calls
- Flask (Python) for the backend API
- Azure for hosting the ML model
- Firebase for analytics, crash reporting, and sound storage
- NLP libraries (like nltk) and ML model integration for text analysis

- For a full-stack mobile application:
– Clearly separate the mobile client components from the backend services.
– Make distinct nodes for the AdminApp and the main App if both need to be shown (or consider stacking them together as “Android Clients” if the roles are similar).
– Include a dedicated backend API server (Flask API) node, which should show the ML processing and text-rank analysis.

- Use clear labels for each component (e.g., “Android App”, “Admin App”, “Flask API”, “Firebase”, “Azure ML Model”).
- From Android clients to the Flask API (data submission via Retrofit2).
- From the Flask API back to the Android clients (sound response).
- From both clients and API to Firebase for analytics or sound fetching purposes.
– Mobile clients (e.g., rounded rectangles)
– Backend services (e.g., rectangles or servers)
- Notes or legends to indicate protocol (RESTful API calls) and integration technologies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Mobile Client Layer"
        AA["Android App"]:::mobile
        AB["Admin App"]:::mobile
    end

    subgraph "Backend API Layer"
        BA["Flask API"]:::backend
    end

    subgraph "External Services"
        ES1["Firebase"]:::external
        ES2["Azure ML Model"]:::external
    end

    AA -->|"RESTcall"| BA
    AB -->|"RESTcall"| BA
    BA -->|"SoundResponse"| AA
    BA -->|"MLProcessing"| ES2
    ES2 -->|"MLResult"| BA
    AA -->|"AnalyticsAssets"| ES1
    AB -->|"AnalyticsAssets"| ES1
    BA -->|"DataLogging"| ES1

    click AA "https://github.com/stcvit/livstory/tree/main/App/app/src/main/java/in/stcvit/livstory"
    click AB "https://github.com/stcvit/livstory/tree/main/AdminApp/app/src/main/java/com/yashkasera/livstoryuploaddata"
    click BA "https://github.com/stcvit/livstory/tree/main/Backend/flask_api"
    click ES1 "https://github.com/stcvit/livstory/blob/main/Privacy Policy/firebase.json"

    classDef mobile fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
