<!-- 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

---