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