update diagrams

README.md

@@ -20,6 +20,22 @@ An interactive geography game where you try to guess the country I'm thinking of
 
 Built with [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
 
+## Architecture
+
+The application follows a modular architecture with clear separation between the UI, game logic, and AI inference:
+
+
+![Architecture diagram showing the modular design of the World Geography Game with Application Layer, Data Layer, External Services, and User Interface Layer](images/arch.png)
+
+### Key Components:
+
+- **Gradio ChatInterface**: Provides the web-based chat UI
+- **Game Logic**: Manages the 20-questions game flow and state
+- **Country Selector**: Randomly selects countries and fetches facts
+- **Response Cleaner**: Processes and formats AI model responses
+- **Dual Mode Support**: Seamlessly switches between local and cloud inference
+- **Facts Fetcher**: Enriches game data with real country information
+
 ## Features
 
 - 🎯 20 Questions gameplay format

arch.dot

@@ -0,0 +1,79 @@
+```dot
+digraph WorldGeographyArchitecture {
+    rankdir=TB;
+    node [shape=box, style=rounded];
+    
+    // User Interface Layer
+    subgraph cluster_ui {
+        label="User Interface Layer";
+        style=filled;
+        color=lightblue;
+        gradio [label="Gradio ChatInterface"];
+        oauth [label="HF OAuth\n(Cloud Mode)"];
+    }
+    
+    // Application Layer
+    subgraph cluster_app {
+        label="Application Layer";
+        style=filled;
+        color=lightgreen;
+        
+        app [label="app.py\nMain Application"];
+        game_logic [label="Game Logic\n• Question tracking\n• Response formatting\n• Session management"];
+        response_cleaner [label="Response Cleaner\n• JSON parsing\n• Artifact removal\n• Text formatting"];
+    }
+    
+    // Data Layer
+    subgraph cluster_data {
+        label="Data Layer";
+        style=filled;
+        color=lightyellow;
+        
+        countries_db [label="Countries Database\n(COUNTRIES list)"];
+        country_selector [label="Country Selector\n• Random selection\n• Session initialization"];
+        facts_fetcher [label="Facts Fetcher\n• Web scraping\n• HTML parsing"];
+    }
+    
+    // External Services
+    subgraph cluster_external {
+        label="External Services";
+        style=filled;
+        color=lightcoral;
+        
+        hf_api [label="HuggingFace\nInference API"];
+        local_model [label="Local Model Server\n(LM Studio/Ollama)"];
+        travel_guide [label="Kids World Travel Guide\nWebsite"];
+    }
+    
+    // Environment
+    env_vars [label=".env Configuration\n• BASE_URL\n• TOKEN\n• MODEL_NAME", shape=ellipse, style=dashed];
+    
+    // User flow
+    user [label="User", shape=ellipse];
+    
+    // Connections
+    user -> gradio [label="Interact"];
+    gradio -> oauth [label="Authenticate\n(Cloud Mode)"];
+    gradio -> app [label="Send Message"];
+    
+    app -> game_logic [label="Process Question"];
+    app -> country_selector [label="Initialize Game"];
+    app -> response_cleaner [label="Clean Response"];
+    
+    country_selector -> countries_db [label="Select Country"];
+    country_selector -> facts_fetcher [label="Fetch Facts"];
+    facts_fetcher -> travel_guide [label="Scrape Data"];
+    
+    game_logic -> hf_api [label="Cloud Mode"];
+    game_logic -> local_model [label="Local Mode"];
+    
+    env_vars -> app [label="Configure", style=dashed];
+    
+    response_cleaner -> gradio [label="Formatted Response"];
+    gradio -> user [label="Display"];
+    
+    // Styling
+    user [fillcolor=lightsteelblue, style=filled];
+    env_vars [fillcolor=lavender, style="filled,dashed"];
+}
+```