# ktt-ol/hacs architecture

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

- Interactive diagram: https://gitdiagram.com/ktt-ol/hacs
- Repository: https://github.com/ktt-ol/hacs

## Overview

##### Main Components

a. Client-Side (Android App):
- Following sub-components:
- UI Layer (Activities and Fragments)
- SSH Management Module
- MQTT Client Module
- Status Management Service
- Cashbox Management
- Settings Management
- Authentication/Security Layer

b. Server-Side Infrastructure:
- MQTT Broker (mainframe.io:8883)
- SSH Server (for door control)
- Status Service
- Cashbox Service

##### Component Relationships

- Android App → MQTT Broker (SSL/TLS secured connection)
- Android App → SSH Server (secured with private key authentication)
- Status Service → MQTT Broker (publishes status updates)
- Android App → Cashbox Service (HTTPS connection)

##### Specific Implementation Details

Technical elements:
- BKS Keystore for MQTT SSL certification
- SSH Key Authentication (with "mf-door.*" naming convention)
- Background Services for Status Monitoring
- Permission Management System
- Local Storage for Settings and Credentials

##### Data Flow Indicators

Primary flows:
- Door Status Updates (MQTT → App)
- Door Control Commands (App → SSH)
- Cashbox Transactions (App ↔ Cashbox Service)
- Status Updates (Status Service → App)

##### Security Layer Representation

Security measures:
- SSL/TLS Encryption for MQTT
- SSH Key-based Authentication
- HTTPS for Cashbox Operations
- Local Credential Storage

##### Additional Elements

Include:
- Version/Build Information
- External Dependencies (JSch, ACRA, EasyPermissions)
- Permission Requirements
- Error Handling Paths

Key Architectural Patterns to Emphasize:
- Event-Driven Architecture (MQTT)
- Service-Oriented Architecture (Multiple Services)
- Fragment-based UI Architecture
- Background Service Pattern
- Observer Pattern (Status Updates)

Level of Detail:
- Keep high-level components visible
- Related functionality (e.g., all door-related operations)
- Security boundaries clearly
- Asynchronous vs synchronous operations

Remember to:
- Use clear, consistent naming
- Primary and backup paths
- Error handling flows
- Critical security boundaries
- Version information
- External service dependencies

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Android_Application
        MainApp[MainApplication]
        click MainApp "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/MainApplication.kt"
        
        subgraph UI_Layer
            Activities[Activities & Fragments]:::ui
            click Activities "https://github.com/ktt-ol/hacs/tree/master/app/src/main/java/io/mainframe/hacs/PageFragments/"
            Layout[Layout Resources]:::ui
            click Layout "https://github.com/ktt-ol/hacs/tree/master/app/src/main/res/layout/"
            MainAct[MainActivity]:::ui
            click MainAct "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/main/MainActivity.kt"
        end

        subgraph Security
            KeyStore[BKS Keystore]:::security
            click KeyStore "https://github.com/ktt-ol/hacs/blob/master/app/src/main/assets/keystore/hacs_keystore.bks"
            PermHandler[Permission Handler]:::security
            click PermHandler "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/main/PermissionHandler.kt"
        end

        subgraph Core_Services
            SSHMgmt[SSH Management]:::core
            click SSHMgmt "https://github.com/ktt-ol/hacs/tree/master/app/src/main/java/io/mainframe/hacs/ssh/"
            StatusMgmt[Status Management]:::core
            click StatusMgmt "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/status/SpaceStatusService.kt"
            CashboxMgmt[Cashbox Management]:::core
            click CashboxMgmt "https://github.com/ktt-ol/hacs/tree/master/app/src/main/java/io/mainframe/hacs/cashbox/"
            SettingsMgmt[Settings Management]:::core
            click SettingsMgmt "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/settings/SettingsActivity.kt"
        end

        subgraph Door_Control
            DoorButtons[Door Buttons]:::door
            click DoorButtons "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/components/DoorButtons.kt"
            DoorStatus[Door Status]:::door
            click DoorStatus "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/main/BackDoorStatus.kt"
            DoorCmd[Door Commands]:::door
            click DoorCmd "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/ssh/DoorCommand.kt"
        end

        subgraph Logging
            LogConfig[Log Configuration]:::logging
            click LogConfig "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/common/logging/LogConfig.kt"
            LogViewer[Log Viewer]:::logging
            click LogViewer "https://github.com/ktt-ol/hacs/blob/master/app/src/main/java/io/mainframe/hacs/log_view/LogViewerActivity.kt"
        end
    end

    subgraph External_Services
        MQTTBroker[MQTT Broker\nmainframe.io:8883]:::external
        SSHServer[SSH Server]:::external
        StatusService[Status Service]:::external
        CashboxService[Cashbox Service]:::external
    end

    MainApp --> Activities
    Activities --> DoorButtons
    DoorButtons --> DoorCmd
    DoorCmd --> SSHMgmt
    SSHMgmt --> SSHServer
    StatusMgmt --> MQTTBroker
    CashboxMgmt --> CashboxService
    StatusService --> MQTTBroker
    MQTTBroker --> StatusMgmt
    KeyStore --> MQTTBroker
    PermHandler --> MainApp
    LogConfig --> LogViewer

    classDef ui fill:#FFE5CC,stroke:#FF9933
    classDef security fill:#FFB3B3,stroke:#FF0000
    classDef core fill:#B3E6CC,stroke:#339966
    classDef door fill:#CCE6FF,stroke:#3399FF
    classDef logging fill:#E6CCE6,stroke:#993399
    classDef external fill:#E6E6E6,stroke:#666666

    %% Legend
    subgraph Legend
        UI[UI Components]:::ui
        SEC[Security Components]:::security
        CORE[Core Services]:::core
        DOOR[Door Control]:::door
        LOG[Logging]:::logging
        EXT[External Services]:::external
    end
```
