Improve docs

README.md

@@ -2,12 +2,24 @@
 
 A Telegram bot for meme management with cloud storage integration and a web interface for display.
 
-## Features
-- 🤖 Telegram bot that handles image and video memes
-- ☁️ Cloud storage integration (AWS S3/Yandex Cloud compatible)
-- 🖼️ Web interface with auto-refreshing media display
-- 🔐 Approver user system for content moderation
-- 📁 Local development mode with dummy storage
+## Core Functionality (User Stories)
+
+### Suggesting a Meme (User)
+
+* User scans QR code.
+* User sends media (video/picture) to the bot.
+* Bot forwards the media to the **Approver Group**.
+
+### Approving a Meme (Approver)
+
+* **Approver** replies to media in the **Approver Group** with an approval command (e.g., `!SOXOK`, `this`).
+* **Processing:** If video, bot re-encodes to WebM (AV1 + Opus).
+* Bot uploads the final media to **S3**.
+* **Client Update:** Frontend detects S3 resource change and downloads the latest media.
+
+### Direct Meme Submission (Approver)
+
+* **Approver** sends media directly to the **Approver Group** or the bot.
 
 ## Architecture
 The system consists of:
@@ -16,75 +28,12 @@ The system consists of:
 - **Web Interface**: Simple HTML page for viewing memes
 - **Spring Boot**: Kotlin-based backend with dependency injection
 
+![structurizr-1-ContainerDiagram.svg](docs/structurizr/out/structurizr-1-ContainerDiagram.svg)
+
 ## Setup
 
 The application is configured via Spring Boot properties.
 
-### Local Development
-
-1.  Copy the sample local configuration file:
-    ```bash
-    cp src/main/resources/application-local.properties.dist src/main/resources/application-local.properties
-    ```
-
-2.  Edit `src/main/resources/application-local.properties` and fill in your bot details:
-    ```properties
-    # Telegram Bot Configuration
-    bot.token=your_bot_token
-    bot.forward-chat-id=your_forward_chat-id
-    bot.approver-user-ids=id1,id2,id3
-    ```
-
-3.  Run the application with the `local` profile active:
-    ```bash
-    ./gradlew bootRun --args='--spring.profiles.active=local'
-    ```
-    In this mode, memes are stored in memory and are not persisted.
-
-### Production
-
-For a production deployment (e.g., in Docker), you can provide configuration via environment variables or an `application.properties` file.
-
-**Example using environment variables:**
-
-Spring Boot automatically maps environment variables (e.g., `BOT_TOKEN`) to application properties (e.g., `bot.token`).
-
-```bash
-export BOT_TOKEN="your_bot_token"
-export BOT_FORWARD_CHAT_ID="your_forward_chat_id"
-export BOT_APPROVER_USER_IDS="id1,id2,id3"
-
-export S3_ENDPOINT="https://s3.example.com"
-export S3_REGION="us-east-1"
-export S3_BUCKET="your_bucket_name"
-export S3_ACCESS_KEY_ID="your_key"
-export S3_SECRET_ACCESS_KEY="your_secret"
-
-java -jar build/libs/memevizor-*.jar
-```
-
-**Example `application.properties` file:**
-
-```properties
-# Telegram Bot Configuration
-bot.token=your_bot_token
-bot.forward-chat-id=your_forward_chat_id
-bot.approver-user-ids=id1,id2,id3
-
-# S3 Configuration
-s3.endpoint=https://s3.example.com
-s3.region=us-east-1
-s3.bucket=your_bucket_name
-s3.access-key-id=your_key
-s3.secret-access-key=your_secret
-```
-
-## Usage
-
-1.  Send a meme (image or video) to the Telegram bot.
-2.  To approve and upload the meme, reply to the message with `this` or `!soxok`.
-3.  View the latest meme at `http://localhost:8080` (or your deployed URL).
-
 ## Deployment
 
 ### Docker

docs/structurizr/.gitignore

@@ -0,0 +1,3 @@
+.structurizr
+workspace.json
+!out

docs/structurizr/launch-structurizr.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+
+docker run -it --rm -p 8080:8080 -v "${PWD}:/usr/local/structurizr" structurizr/lite
+

docs/structurizr/workspace.dsl

@@ -0,0 +1,50 @@
+workspace "memevizor" "A meme sharing service" {
+    model {
+        // Actors
+        u = person "User" "Meme submitter."
+        a = person "Approver" "Moderates/Approves memes."
+        tv = person "Viewer (Any Web Browser)" "Opens the S3-hosted UI on a browser (e.g., on a TV screen) to view the current approved meme."
+
+        // External Systems
+        tg = softwareSystem "Telegram" "Messaging platform used for content submission and moderation."
+
+        // The Software System under development
+        ss = softwareSystem "Memevizor" "A Telegram-based service for submitting, approving, and displaying memes." {
+
+            // Core Application Container (Renamed and specified technology)
+            bot = container "Memevizor Bot Backend" "Kotlin/Spring Application." "Processes Telegram updates, handles media conversion, and manages S3 content."
+
+            // Storage Container (Clarified role)
+            s3 = container "Content S3 Bucket" "AWS S3." "Stores static UI assets (HTML/CSS/JS) and approved media content."
+        }
+
+        // Actor Relationships
+        u -> tg "Sends memes and content to"
+        a -> tg "Moderates/Approves content by replying to messages in"
+
+        // Backend Interactions
+        // 1. Core Telegram Communication (Polling for messages and sending replies)
+        bot -> tg "Polls for updates and sends reactions/replies/Downloads media" "HTTPS/Telegram Bot API"
+
+        // 3. S3 Interactions
+        bot -> s3 "Uploads UI assets/media" "HTTPS"
+
+        // Viewer/Client Interactions
+        tv -> s3 "Fetches UI and polls for media files" "HTTPS"
+    }
+
+    views {
+        systemContext ss "SystemContext" {
+            // Focus on the Memevizor system and its neighbors
+            include *
+            autolayout lr
+            //
+        }
+
+        container ss "ContainerDiagram" {
+            // Focus on the containers within Memevizor and their external dependencies
+            include *
+            autolayout tb
+        }
+    }
+}