# sat-14/app architecture

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

- Interactive diagram: https://gitdiagram.com/sat-14/app
- Repository: https://github.com/sat-14/app

## Overview

##### Project Type & Purpose
- This is a full-stack “Smart Bills Reminder” system combining:
- A Flask-based REST API backend (Python 3.9+)
- A cross-platform mobile GUI built with Kivy
- A lightweight SQLite data store
- Background scheduling for reminders
- Integrations with AI (Gemini/OpenAI/ElevenLabs) and communications (Twilio/Bland AI)

##### File Structure Analysis
- Top-level:
- .gitattributes, LICENSE, README.md
- backend/ (all server code + mobile UI under backend/frontend/)
- backend/
- app.py, config.py, models.py: core Flask entry and DB models
- auth.py, bills.py, loans.py, receipts.py, reminders.py, chatbot.py, reset_password.py: API endpoints (business logic)
- ai_service.py, elevenlabs_service.py, reminder_service.py, local_storage_service.py: integration services
- scheduler.py: APScheduler job definitions
- requirements.txt, .env, bills_reminder.json: configs & dependencies
- frontend/: Kivy application (main.py + .kv screen layouts)

##### Key README Insights
- Client Layer (mobile app) → API Gateway → Business Logic → Data Layer → External Services
- Core features: recurring bills, loan tracking, receipts, AI chatbot, multi-channel reminders

a. Main Components
– Mobile App (Kivy screens & API manager)
– Flask API Server
– Scheduler (APScheduler)
– Database (SQLite)
– File Storage (local receipts folder)
– AI Services (Google Gemini, OpenAI GPT-4, ElevenLabs TTS)
– Communication Services (Twilio WhatsApp/SMS, Bland AI voice calls)
b. Component Relationships
– Mobile App → (HTTP/REST) → Flask API
– Flask API ↔ SQLite (via SQLAlchemy)
– Flask API → Scheduler (schedule definitions)
– Scheduler → Flask API (invoke reminder logic)
– Reminder Service in API → Communication Services → End Users
– API → AI Services (chatbot & content generation)
– Receipt uploads → stored on local filesystem → served by API
c. Architectural Patterns
– Layered Architecture (Client, API Gateway/Controllers, Services/Business Logic, Persistence)
– Modular service integrations (AI, communications, storage)
– Background job scheduling for asynchronous tasks
– MVC flavor in Kivy frontend (Screen Manager + .kv templates)
d. Key Technologies
– Backend: Python, Flask, SQLAlchemy, APScheduler, Flask-JWT-Extended, Bcrypt, Cryptography
– Frontend: Python, Kivy, KivyMD
– Database: SQLite
– AI: Google Gemini, OpenAI GPT-4, ElevenLabs TTS
– Comm: Twilio API (WhatsApp/SMS), Bland AI

##### Diagramming Conventions
- Related components in labeled containers (“Mobile App,” “Backend Services,” “External Services”)

##### Detail & Scope
- Every major module: auth, bills, loans, receipts, reminders, chatbot
- Scheduler loop triggering reminder logic
- Optional flows (WhatsApp vs. SMS vs. voice)
- AI decision point in the chatbot/reminder services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        MobileApp["Kivy Mobile App"]:::frontend
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        direction TB
        App["Flask API Server"]:::backend
        Config["Configuration (config.py)"]:::backend
        Auth["Auth Endpoints"]:::backend
        Reset["Reset Password Endpoint"]:::backend
        CheckUsers["User Check Endpoint"]:::backend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Bills["Bills Management"]:::service
        Loans["Loans Management"]:::service
        Receipts["Receipts Management"]:::service
        Reminders["Reminders Management"]:::service
        Chatbot["Chatbot Endpoint"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Models["ORM Models (models.py)"]:::database
        LocalStorage["Local File Storage Service"]:::storage
        SQLite["SQLite Database"]:::database
        FileStore["Receipts File Storage"]:::storage
    end

    %% Scheduler Layer
    subgraph "Scheduler Layer"
        direction TB
        Scheduler["APScheduler Jobs"]:::backend
        ReminderService["Reminder Service"]:::service
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        AIService["Generic AI Service"]:::external
        ElevenLabs["ElevenLabs TTS Service"]:::external
        ChatbotModels["Chatbot Models"]:::external
        Comm["Communication Services"]:::external
    end

    %% Data Stores
    SQLite --> Models
    FileStore --> LocalStorage

    %% Flow Connections
    MobileApp -->|"HTTP/REST"| App
    App --> Config
    App --> Auth
    App --> Reset
    App --> CheckUsers
    App --> Bills
    App --> Loans
    App --> Receipts
    App --> Reminders
    App --> Chatbot

    Bills --> Models
    Loans --> Models
    Receipts --> LocalStorage
    Receipts --> Models
    Reminders --> Models
    Chatbot --> Models

    App --> Scheduler
    Scheduler --> ReminderService
    ReminderService --> App

    ReminderService -->|"SMS/WhatsApp/Voice"| Comm
    ReminderService -->|"TTS request"| ElevenLabs
    Chatbot --> AIService
    Chatbot --> ChatbotModels

    %% Click Events
    click MobileApp "https://github.com/sat-14/app/tree/main/backend/frontend/"
    click App "https://github.com/sat-14/app/blob/main/backend/app.py"
    click Config "https://github.com/sat-14/app/blob/main/backend/config.py"
    click Auth "https://github.com/sat-14/app/blob/main/backend/auth.py"
    click Reset "https://github.com/sat-14/app/blob/main/backend/reset_password.py"
    click CheckUsers "https://github.com/sat-14/app/blob/main/backend/check_users.py"
    click Bills "https://github.com/sat-14/app/blob/main/backend/bills.py"
    click Loans "https://github.com/sat-14/app/blob/main/backend/loans.py"
    click Receipts "https://github.com/sat-14/app/blob/main/backend/receipts.py"
    click Reminders "https://github.com/sat-14/app/blob/main/backend/reminders.py"
    click Chatbot "https://github.com/sat-14/app/blob/main/backend/chatbot.py"
    click Models "https://github.com/sat-14/app/blob/main/backend/models.py"
    click LocalStorage "https://github.com/sat-14/app/blob/main/backend/local_storage_service.py"
    click Scheduler "https://github.com/sat-14/app/blob/main/backend/scheduler.py"
    click ReminderService "https://github.com/sat-14/app/blob/main/backend/reminder_service.py"
    click AIService "https://github.com/sat-14/app/blob/main/backend/ai_service.py"
    click ElevenLabs "https://github.com/sat-14/app/blob/main/backend/elevenlabs_service.py"
    click ChatbotModels "https://github.com/sat-14/app/blob/main/backend/chatbot_models.py"

    %% Styles
    classDef frontend fill:#E8F0FE,stroke:#4285F4,color:#202124
    classDef backend fill:#ECECEC,stroke:#757575,color:#202124
    classDef service fill:#E3FCEF,stroke:#34A853,color:#202124
    classDef database fill:#FFF3CD,stroke:#FBBC05,color:#202124
    classDef storage fill:#FCE8E6,stroke:#EA4335,color:#202124
    classDef external fill:#F1F3F4,stroke:#5F6368,color:#202124
```
