# johnkgs/kivy-order-app architecture

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

- Interactive diagram: https://gitdiagram.com/johnkgs/kivy-order-app
- Repository: https://github.com/johnkgs/kivy-order-app

## Overview

##### Project type and purpose
- This is a distributed system for managing “orders” in a teaching context (“Programação Distribuída e Paralela”).
- It consists of three cooperating services (API, Queue worker, and UI client) plus an embedded message broker (ActiveMQ) and a local database (SQLite).

##### Main components
A. API service (`order_app/api`)
- FastAPI (or similar) application defined in `main.py`.
- Exposes REST endpoints under `modules/orders` (`order_router.py`, `order_schemas.py`).
- Persists order data to `api/db/orders.db` via `order_repository.py`.
- Publishes “new order” events to the message broker.

B. Message broker (ActiveMQ)
- Defined in the `activemq` folder and orchestrated via `docker-compose.yaml`.
- Routes messages between producers (API) and consumers (Queue worker).

C. Queue worker (`order_app/queue`)
- Connects to ActiveMQ (settings in `config/settings.py`).
- Listens on the “order” queue (`queues/order_queue.py`).
- On receipt, processes the order (e.g., logging, forwarding, analytics).
- Optionally writes results back to the database or calls external services.

D. UI client (`order_app/web`)
- Kivy-based GUI (files ending in `.kv` and `*.py` under `pages` and `uix`).
- Provides two screens: list existing orders and add a new order.
- Interacts with the API via `order_service.py` (HTTP calls).

E. Shared database
- SQLite file under `api/db/orders.db`.
- Used by the API for reads/writes; can also be accessed by the queue worker if needed.

##### Relationships and interactions
- UI → API: HTTP GET/POST over REST to retrieve and create orders.
- API ↔ SQLite: direct file-based database connection.
- API → ActiveMQ: publishes “order.created” messages.
- ActiveMQ → Queue worker: delivers messages to the consumer queue.
- Queue worker → (optional) Database or external system: processes the event.

##### Architectural patterns & design principles
- Microservices / modular monolith split into three logical services.
- Event-driven / message-based communication between API and worker.
- Single source of truth for data (SQLite) with clear separation of read/write paths.
- Client-server pattern for the UI and API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Client Layer
    subgraph "UI Client (Kivy Desktop App)"
        direction TB
        UI["UI Client"]:::frontend
        UI -->|"HTTP"| API
    end

    %% API Service Layer
    subgraph "Order API Service"
        direction TB
        API["Order API Service"]:::service
        API -->|"DB driver"| DB
        API -->|"STOMP"| Broker
    end

    %% Message Broker
    subgraph "Message Broker"
        direction TB
        Broker["ActiveMQ Broker"]:::broker
        Broker -->|"STOMP"| Worker
    end

    %% Queue Worker Layer
    subgraph "Queue Worker"
        direction TB
        Worker["Order Queue Worker"]:::worker
        Worker -->|"optional DB"| DB
    end

    %% Shared Storage
    subgraph "Shared Storage"
        direction TB
        DB["SQLite Orders DB"]:::storage
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Infra["Docker Compose"]:::infra
        Infra -.->|orchestrates| Broker
        Infra -.->|configures| API
    end

    %% Legend
    subgraph "Legend"
        direction TB
        A["Client"]:::frontend
        B["Service"]:::service
        C["Worker"]:::worker
        D["Broker"]:::broker
        E["Storage"]:::storage
        F["Infra"]:::infra
    end

    %% Click Events - API Service
    click API "https://github.com/johnkgs/kivy-order-app/tree/main/order_app/api"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/main.py"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/config/database.py"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/modules/orders/order_router.py"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/modules/orders/order_schemas.py"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/modules/orders/order_repository.py"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/modules/orders/order_entity.py"
    click API "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/utils/tags.py"

    %% Click Events - Message Broker
    click Broker "https://github.com/johnkgs/kivy-order-app/tree/main/activemq"
    click Broker "https://github.com/johnkgs/kivy-order-app/blob/main/activemq/conf/activemq.xml"
    click Broker "https://github.com/johnkgs/kivy-order-app/blob/main/docker-compose.yaml"

    %% Click Events - Queue Worker
    click Worker "https://github.com/johnkgs/kivy-order-app/tree/main/order_app/queue"
    click Worker "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/queue/main.py"
    click Worker "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/queue/config/settings.py"
    click Worker "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/queue/queues/order_queue.py"

    %% Click Events - UI Client
    click UI "https://github.com/johnkgs/kivy-order-app/tree/main/order_app/web"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/main.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/pages/main/main_screen.kv"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/pages/main/main_screen.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/pages/orders/orders_screen.kv"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/pages/orders/orders_screen.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/pages/orders/add_new_order/add_new_order_screen.kv"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/pages/orders/add_new_order/add_new_order_screen.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/services/order_service.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/services/types/order.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/uix/header/header.kv"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/utils/decorators/debounce.py"
    click UI "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/web/utils/path.py"

    %% Click Events - Shared DB
    click DB "https://github.com/johnkgs/kivy-order-app/blob/main/order_app/api/db/orders.db"

    %% Styles
    classDef frontend fill:#D8BFD8,stroke:#9932CC,color:#000
    classDef service fill:#98FB98,stroke:#228B22,color:#000
    classDef worker fill:#AFEEEE,stroke:#008B8B,color:#000
    classDef broker fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef storage fill:#FFD700,stroke:#FF8C00,color:#000
    classDef infra fill:#D3D3D3,stroke:#696969,color:#000
```
