# muhammad-hashir-code/sugar-ai architecture

> Architecture diagram of the GitHub repository muhammad-hashir-code/sugar-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhammad-hashir-code/sugar-ai
- Repository: https://github.com/muhammad-hashir-code/sugar-ai

## Overview

Sugar-AI is a FastAPI coding assistant with retrieval-augmented and direct/chat generation, code debugging, API-key quotas, OAuth access, and an admin web interface. The main workflow is request authentication and routing, optional document retrieval and prompt construction, model-provider generation, then an API response. Startup configures the selected backend, initializes the RAG agent and document index, and injects the agent into API routes. Provider implementations and web/auth capabilities are represented where the README or sampled source supports them; unsampled routes are not assigned speculative call relationships.

Main entry points: [`main.py`](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/main.py) (Startup wiring), [`app/providers/__init__.py`](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/__init__.py) (Provider factory), [`app/ai.py`](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/ai.py) (RAG and generation), [`app/auth.py`](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["Startup wiring<br/>[main.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_api["AI endpoints<br/>[api.py]"]
end

subgraph group_ai["AI workflow"]
  node_agent["RAG and generation<br/>[ai.py]"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_retrieval["Document retrieval<br/>[ai.py]"]
end

subgraph group_providers["Model providers"]
  node_provider_factory["Provider factory<br/>[__init__.py]"]
  node_provider_base["Provider interface<br/>[base.py]"]
  node_huggingface["Hugging Face<br/>[huggingface.py]"]
  node_ollama["Ollama backend<br/>[ollama.py]"]
  node_gemini["Gemini backend<br/>[gemini.py]"]
end

subgraph group_access["Identity and access"]
  node_database[("API key store<br/>[database.py]")]
  node_auth["Authentication<br/>[auth.py]"]
  node_auth_routes["Login and key requests<br/>[auth.py]"]
  node_admin_routes["Admin controls<br/>[admin.py]"]
end

subgraph group_web["Web experience"]
  node_web_routes["Web pages<br/>[web.py]"]
  node_webhook["Repository webhook<br/>[webhook.py]"]
end

node_client(("API client"))
node_openai_service{{"OpenAI-compatible API"}}
node_ollama_service{{"Ollama service"}}
node_gemini_service{{"Gemini service"}}
node_oauth_services{{"OAuth providers"}}

node_client -->|"submits request"| node_api
node_main -->|"creates provider"| node_provider_factory
node_main -->|"initializes agent"| node_agent
node_main -->|"builds index"| node_retrieval
node_main -->|"injects agent"| node_api
node_main -->|"reads settings"| node_config
node_main -->|"syncs keys"| node_auth
node_api -->|"authenticates"| node_auth
node_api -->|"invokes workflows"| node_agent
node_agent -->|"searches documents"| node_retrieval
node_agent -->|"uses templates"| node_prompts
node_agent -->|"generates responses"| node_provider_base
node_provider_factory -->|"selects backend"| node_huggingface
node_provider_factory -->|"selects backend"| node_ollama
node_provider_factory -->|"selects backend"| node_gemini
node_provider_factory -->|"selects backend"| node_provider_base
node_provider_base -->|"calls completions"| node_openai_service
node_ollama -.->|"calls model service"| node_ollama_service
node_gemini -.->|"calls model service"| node_gemini_service
node_auth -->|"checks and syncs keys"| node_database
node_auth_routes -->|"reads and updates"| node_database
node_auth_routes -->|"starts OAuth"| node_oauth_services
node_admin_routes -->|"uses authentication"| node_auth
node_admin_routes -->|"manages keys"| node_database
node_web_routes -->|"uses authentication"| node_auth
node_webhook -.->|"accepts repository events"| node_client

click node_main "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/main.py"
click node_config "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/config.py"
click node_api "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/api.py"
click node_agent "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/ai.py"
click node_prompts "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/prompts.py"
click node_retrieval "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/ai.py"
click node_provider_factory "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/__init__.py"
click node_provider_base "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/base.py"
click node_huggingface "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/huggingface.py"
click node_ollama "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/ollama.py"
click node_gemini "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/gemini.py"
click node_database "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/database.py"
click node_auth "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/auth.py"
click node_auth_routes "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/auth.py"
click node_admin_routes "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/admin.py"
click node_web_routes "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/web.py"
click node_webhook "https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/webhook.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_api,node_client toneBlue
class node_agent,node_prompts,node_retrieval toneAmber
class node_provider_factory,node_provider_base,node_huggingface,node_ollama,node_gemini,node_openai_service toneMint
class node_database,node_auth,node_auth_routes,node_admin_routes toneRose
class node_web_routes,node_webhook,node_ollama_service,node_gemini_service,node_oauth_services toneIndigo
```

## Components

### Application entry

- [Startup wiring](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/main.py): `main.py`
- [Runtime settings](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/config.py): `app/config.py`
- [AI endpoints](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/api.py): `app/routes/api.py`

### AI workflow

- [RAG and generation](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/ai.py): `app/ai.py`
- [Prompt templates](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/prompts.py): `app/prompts.py`
- [Document retrieval](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/ai.py): `app/ai.py`

### Model providers

- [Provider factory](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/__init__.py): `app/providers/__init__.py`
- [Provider interface](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/base.py): `app/providers/base.py`
- [Hugging Face](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/huggingface.py): `app/providers/huggingface.py`
- [Ollama backend](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/ollama.py): `app/providers/ollama.py`
- [Gemini backend](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/providers/gemini.py): `app/providers/gemini.py`

### Identity and access

- [API key store](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/database.py): `app/database.py`
- [Authentication](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/auth.py): `app/auth.py`
- [Login and key requests](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/auth.py): `app/routes/auth.py`
- [Admin controls](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/admin.py): `app/routes/admin.py`

### Web experience

- [Web pages](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/web.py): `app/routes/web.py`
- [Repository webhook](https://github.com/muhammad-hashir-code/sugar-ai/blob/main/app/routes/webhook.py): `app/routes/webhook.py`

### Other components

- **API client**
- **OpenAI-compatible API**
- **Ollama service**
- **Gemini service**
- **OAuth providers**

## Connections

- API client → AI endpoints: submits request (evidence: `README.md`)
- Startup wiring → Provider factory: creates provider (evidence: `main.py`)
- Startup wiring → RAG and generation: initializes agent (evidence: `main.py`)
- Startup wiring → Document retrieval: builds index (evidence: `main.py`)
- Startup wiring → AI endpoints: injects agent (evidence: `main.py`)
- Startup wiring → Runtime settings: reads settings (evidence: `main.py`)
- Startup wiring → Authentication: syncs keys (evidence: `main.py`)
- AI endpoints → Authentication: authenticates (evidence: `app/routes/api.py`)
- AI endpoints → RAG and generation: invokes workflows (evidence: `app/routes/api.py`)
- RAG and generation → Document retrieval: searches documents (evidence: `app/ai.py`)
- RAG and generation → Prompt templates: uses templates (evidence: `app/ai.py`)
- RAG and generation → Provider interface: generates responses (evidence: `app/ai.py`)
- Provider factory → Hugging Face: selects backend (evidence: `app/providers/__init__.py`)
- Provider factory → Ollama backend: selects backend (evidence: `app/providers/__init__.py`)
- Provider factory → Gemini backend: selects backend (evidence: `app/providers/__init__.py`)
- Provider factory → Provider interface: selects backend (evidence: `app/providers/__init__.py`)
- Provider interface → OpenAI-compatible API: calls completions (evidence: `app/providers/base.py`)
- Ollama backend → Ollama service: calls model service
- Gemini backend → Gemini service: calls model service
- Authentication → API key store: checks and syncs keys (evidence: `app/auth.py`)
- Login and key requests → API key store: reads and updates (evidence: `app/routes/auth.py`)
- Login and key requests → OAuth providers: starts OAuth (evidence: `app/routes/auth.py`)
- Admin controls → Authentication: uses authentication (evidence: `app/routes/admin.py`)
- Admin controls → API key store: manages keys (evidence: `app/routes/admin.py`)
- Web pages → Authentication: uses authentication (evidence: `app/routes/web.py`)
- Repository webhook → API client: accepts repository events
