Update docs/ARCHITECTURE.md

docs/ARCHITECTURE.md

@@ -0,0 +1,194 @@
+<!-- ARCHITECTURE.md -->
+
+# Shasha AI — Architecture Overview
+
+A high‑level view of the components and data flow in the Shasha AI code‑generation platform.
+
+## 1. Core Layers
+
+### 1.1 Frontend (Gradio UI)
+- **app.py**: Defines the Gradio Blocks UI — input panels (prompt, file, website, image), model selector, language selector, buttons, and output panes (Code, Preview, History).
+- **static/**: Holds `index.html`, `index.js`, `style.css` for any transformers.js demos and custom styling.
+- **assets/**: Images, logos, and other static assets.
+
+### 1.2 Backend Services
+
+#### 1.2.1 Inference Routing
+- **hf_client.py**  
+  - `get_inference_client(model_id, provider)`  
+  - Wraps HF/OpenAI/Gemini/Groq providers into a unified interface.
+  - Automatically selects/falls back based on model prefix and available credentials.
+
+- **inference.py**  
+  - `chat_completion(...)` and `stream_chat_completion(...)`  
+  - Encapsulates request/response logic, streaming vs. blocking, and error handling.
+
+#### 1.2.2 Model Registry
+- **models.py**  
+  - `ModelInfo` dataclass & `AVAILABLE_MODELS` registry  
+  - Central source of truth for supported models, identifiers, descriptions, and default providers.
+  - Helper `find_model()` for lookup by name or ID.
+
+#### 1.2.3 Prompt & History Management
+- **constants.py**  
+  - System prompts for HTML/transformers.js modes, search/replace tokens, Gradio language support.
+- **utils.py**  
+  - `history_to_messages()`, `remove_code_block()`, multimodal image encoding, parsing transformers.js outputs, search/replace utilities.
+
+#### 1.2.4 Deployment & Project Import
+- **deploy.py**  
+  - `send_to_sandbox()` → live HTML preview in iframe  
+  - `load_project_from_url()` → import existing HF Spaces (app.py/index.html)  
+  - `deploy_to_spaces*()` → create/update HF Space via Hub API
+
+## 2. Extensions & Plugins
+- **plugins.py** (future)  
+  - Plugin discovery/loading for community‑created extensions (e.g., DB runners, snippet libraries).
+
+- **auth.py** (future)  
+  - OAuth flows for GitHub, Google Drive, Slack — enable private file loading.
+
+## 3. Project Structure
+
+.
+├── app.py # Gradio application
+├── constants.py # System prompts & app‑wide constants
+├── hf_client.py # Inference client factory
+├── models.py # Model registry & metadata
+├── inference.py # Chat completion wrappers
+├── utils.py # Helpers: history, code parsing, multimodal
+├── deploy.py # Sandbox preview & HF Spaces import/deploy
+├── plugins.py # (planned) Plugin architecture
+├── auth.py # (planned) OAuth integrations
+├── notebooks/ # Demo Jupyter notebooks
+├── tests/ # pytest suites & UI smoke tests
+├── ci.yaml # CI pipeline for lint/test/deploy
+├── docs/
+│ ├── QUICKSTART.md
+│ ├── ARCHITECTURE.md
+│ └── API_REFERENCE.md
+└── static/ # transformers.js demos & CSS/JS assets
+
+yaml
+Copy
+Edit
+
+## 4. Data Flow
+
+1. **User Interaction**: User enters prompt / uploads file / selects model & language.
+2. **Preprocessing**:  
+   - File → `extract_text_from_file()`  
+   - Website → `extract_website_content()`  
+   - Image → `process_image_for_model()`
+3. **Message Assembly**:  
+   - System prompt + history → OpenAI‑style message list  
+   - Enhanced via optional web search (Tavily)
+4. **Inference Call**:  
+   - `get_inference_client()` → select provider & billing  
+   - `chat_completion()` or streaming  
+5. **Postprocessing**:  
+   - Parse code blocks / transformers.js multi‑file output  
+   - Apply search/replace to existing code if editing  
+6. **UI Update**:  
+   - Code pane  
+   - Live preview iframe (`send_to_sandbox`)  
+   - Chat history pane
+
+---
+
+```markdown
+<!-- API_REFERENCE.md -->
+
+# Shasha AI — API Reference
+
+This document describes the public interfaces provided by each module.
+
+---
+
+## `hf_client.py`
+
+### `get_inference_client(model_id: str, provider: str = "auto") → InferenceClient`
+Creates and configures a Hugging Face Hub client for chat completions.
+
+- **model_id**: HF model ID or external provider prefix (e.g. `"openai/gpt-4"`, `"gemini/pro"`, `"moonshotai/Kimi-K2-Instruct"`).
+- **provider**: Override provider; one of `auto`, `groq`, `openai`, `gemini`, `fireworks`.
+- **Returns**: `InferenceClient` instance with proper API key & billing target.
+
+---
+
+## `models.py`
+
+### `ModelInfo`
+Dataclass representing model metadata.
+
+- **name**: Human‑readable model name.
+- **id**: Model identifier for API calls.
+- **description**: Short description.
+- **default_provider**: Preferred inference provider.
+
+### `AVAILABLE_MODELS: List[ModelInfo]`
+Registry of all supported models.
+
+### `find_model(identifier: str) → Optional[ModelInfo]`
+Lookup model by name (case‑insensitive) or ID.
+
+---
+
+## `inference.py`
+
+### `chat_completion(model_id: str, messages: List[Dict[str, str]], provider: str = None, max_tokens: int = 4096) → str`
+Synchronously sends a chat completion request.
+
+- **messages**: List of `{"role": "...", "content": "..."}`  
+- **provider**: Optional override; defaults to model’s `default_provider`.
+- **Returns**: Response content string.
+
+### `stream_chat_completion(model_id: str, messages: List[Dict[str, str]], provider: str = None, max_tokens: int = 4096) → Generator[str]`
+Streams a chat completion, yielding incremental content chunks.
+
+---
+
+## `utils.py`
+
+### `history_to_messages(history: History, system: str) → List[Dict]`
+Converts internal history list to OpenAI‑style messages.
+
+### `remove_code_block(text: str) → str`
+Strips markdown code fences from AI output and returns raw code.
+
+### `parse_transformers_js_output(text: str) → Dict[str, str]`
+Extracts `index.html`, `index.js`, `style.css` from a multi‑file markdown output.
+
+### `format_transformers_js_output(files: Dict[str, str]) → str`
+Formats a dict of file contents into a single combined string with section headers.
+
+*(Other utilities: multimodal image processing, search/replace, history rendering)*
+
+---
+
+## `deploy.py`
+
+### `send_to_sandbox(code: str) → str`
+Wraps HTML code in a base64 data‑URI iframe for live preview.
+
+### `load_project_from_url(url: str) → Tuple[str, str]`
+Fetches `app.py` or `index.html` from a public HF Space URL.
+
+*(Also: HF Spaces deploy helpers: `deploy_to_spaces()`, `deploy_to_spaces_static()`, `deploy_to_user_space()`)*
+
+---
+
+## `app.py`
+
+### `generation_code(query, image, file, website_url, _setting, _history, _current_model, enable_search, language, provider) → Tuple[str, History, str, List[Dict]]`
+Main generation handler bound to the “Generate” button.
+
+- **Returns**:  
+  1. `code_str`: Generated (or edited) source code  
+  2. `new_history`: Updated prompt/response history  
+  3. `sandbox_html`: Live preview HTML iframe string  
+  4. `chat_msgs`: Chatbot‑style history for the UI  
+
+---
+
+_For more examples, see the Jupyter notebooks in_ `notebooks/` and the quick‑start guide in `QUICKSTA