docs/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

---