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