# ahmetcolak251113/yzta_bootcamp_team35 architecture

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

- Interactive diagram: https://gitdiagram.com/ahmetcolak251113/yzta_bootcamp_team35
- Repository: https://github.com/ahmetcolak251113/yzta_bootcamp_team35

## Overview

1. **Repository purpose**
   - This is a **FastAPI backend** for the “Akıllı Dolap” app, focused on two AI-backed capabilities: **LLM chatbot** and **outfit recommendation**.
   - The system is designed around three main concerns: **API orchestration**, **persistent wardrobe storage**, and **Google Gemini integration**.

2. **Top-level runtime boundary**
   - The running service is started with **Uvicorn** against `main:app`.
   - From the outside, there are two main clients:
     - a browser-based test panel at `/`
     - API consumers via FastAPI endpoints and `/docs` Swagger UI

3. **`main.py` as the application entry and orchestration layer**
   - `main.py` is the central integration point.
   - It exposes the REST endpoints for:
     - wardrobe CRUD
     - category management
     - chat
     - outfit recommendation
   - It sits between the HTTP layer, the database module, and the Gemini client, so the architecture is a classic **controller/orchestrator** pattern.

4. **`database.py` as the persistence boundary**
   - `database.py` owns all SQLite access.
   - The repo is intentionally structured so the storage backend can later move to PostgreSQL by changing the connection layer in this file, without rewriting the API layer.
   - This means `main.py` should be diagrammed as depending on a **storage abstraction**, not directly on SQL details.

5. **Domain data model in the database**
   - The backend stores two key domain tables:
     - **`kategoriler`**: editable option lists for clothing attributes such as fabric, cut, collar type, sleeve type, pattern, season, style tag, and usage frequency
     - **`kiyafetler`**: the actual wardrobe inventory
   - `kategoriler` is important architecturally because these values are **not hardcoded enums**; they are managed through API endpoints and persist in the database.

6. **Wardrobe management flow**
   - CRUD endpoints on `kiyafetler` handle add, list, detail, update, and delete operations.
   - Each clothing item is scoped by `user_id`, so the wardrobe is effectively **multi-user** even though the database is local SQLite.
   - Clothing records include both required fields (`tur`, `renk`) and richer optional metadata like `marka`, `beden`, `kumas`, `kesim`, `yaka_tipi`, `kol_tipi`, `desen`, `mevsim`, `stil_etiketi`, `kullanim_sikligi`, `kombin_notu`, `temiz`, and `foto_url`.

7. **`gemini_client.py` as the external AI boundary**
   - This module isolates all interaction with **Google Gemini API**.
   - It likely contains the system prompts and request/response handling for two separate AI behaviors:
     - chatbot conversation
     - outfit generation
   - Architecturally, this keeps LLM-specific logic out of the API and database layers.

8. **Chatbot data flow**
   - The `/chat` endpoint accepts a user message and a `user_id`, then delegates to Gemini through `gemini_client.py`.
   - The chatbot is designed to collect missing context through follow-up questions until it can mark the situation as ready (`hazir_mi`).
   - This is a conversational workflow, not just a single prompt/response call.

9. **Outfit recommendation data flow**
   - The `/kombin/oner` endpoint combines:
     - user wardrobe data from SQLite
     - event context such as occasion, weather, and style preference
     - Gemini-generated reasoning/recommendation
   - The response includes a `secilen_kiyafetler` list with **clothing IDs and `foto_url` values**, which is a deliberate downstream integration boundary for AR or social-media modules.

10. **`index.html` as a lightweight browser test surface**
   - `index.html` is not a separate application tier; it is a simple UI for testing the backend from the browser.
   - It exposes four functional areas: wardrobe, categories, chatbot, and outfit recommendation.
   - In the architecture diagram, this should be shown as a **client-side test/ops interface** talking to the FastAPI backend.

11. **Configuration and environment**
   - Secrets and model selection are externalized through environment variables, with `.env.example` documenting the required settings.
   - The backend depends on a Gemini API key and a model name, so model availability is a real runtime dependency.
   - The README explicitly warns that older model names may fail, which makes Gemini model selection part of operational configuration.

12. **Important system boundaries to show in a diagram**
   - Browser/UI layer: `index.html` and Swagger `/docs`
   - API layer: `main.py`
   - Persistence layer: `database.py` + SQLite
   - AI integration layer: `gemini_client.py` + Google Gemini
   - Shared domain boundary: editable clothing categories and user-scoped wardrobe records

13. **What is intentionally not in the repo**
   - There is no separate frontend SPA, message queue, background worker, or auth service.
   - The architecture is a relatively compact monolith: one FastAPI process coordinating local persistence and remote AI calls.

Main entry points: [`main.py`](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/main.py) (App Entry), [`database.py`](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/database.py) (Storage Layer), [`gemini_client.py`](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/gemini_client.py) (Gemini Client), [`env.example`](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/env.example) (Env Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client/UI"]
  node_index_html["Test Panel<br/>browser UI<br/>[index.html]"]
  node_swagger_docs["API Docs<br/>browser UI"]
end

subgraph group_api["FastAPI Backend"]
  node_main_py["App Entry<br/>FastAPI app<br/>[main.py]"]
  node_wardrobe_api["Wardrobe API<br/>CRUD routes"]
  node_category_api["Category API<br/>admin routes"]
  node_chat_api["Chat API<br/>conversation routes"]
  node_recommend_api["Recommend API<br/>outfit routes"]
  node_uvicorn_runtime(("Uvicorn<br/>server runtime"))
end

subgraph group_storage["Persistence"]
  node_database_py[("Storage Layer<br/>SQLite access<br/>[database.py]")]
  node_kategoriler_table[("Categories<br/>domain table")]
  node_kiyafetler_table[("Wardrobe<br/>domain table")]
  node_sqlite_db[("SQLite Store<br/>local database")]
end

subgraph group_ai["AI Integration"]
  node_gemini_client_py["Gemini Client<br/>AI adapter<br/>[gemini_client.py]"]
  node_gemini_api{{"Gemini API<br/>external LLM"}}
end

subgraph group_config["Config"]
  node_env_example["Env Config<br/>runtime config<br/>[env.example]"]
end

node_uvicorn_runtime -->|"serves"| node_main_py
node_index_html -->|"calls"| node_main_py
node_swagger_docs -->|"explores"| node_main_py
node_main_py -->|"routes"| node_wardrobe_api
node_main_py -->|"routes"| node_category_api
node_main_py -->|"routes"| node_chat_api
node_main_py -->|"routes"| node_recommend_api
node_wardrobe_api -->|"reads/writes"| node_database_py
node_category_api -->|"reads/writes"| node_database_py
node_chat_api -->|"delegates"| node_gemini_client_py
node_recommend_api -->|"loads"| node_database_py
node_recommend_api -->|"delegates"| node_gemini_client_py
node_database_py -->|"uses"| node_sqlite_db
node_database_py -->|"owns"| node_kategoriler_table
node_database_py -->|"owns"| node_kiyafetler_table
node_gemini_client_py -->|"calls"| node_gemini_api
node_env_example -->|"configures"| node_gemini_client_py
node_env_example -->|"configures"| node_main_py

click node_index_html "https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/index.html"
click node_main_py "https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/main.py"
click node_database_py "https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/database.py"
click node_gemini_client_py "https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/gemini_client.py"
click node_env_example "https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/env.example"

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_index_html,node_swagger_docs toneBlue
class node_main_py,node_wardrobe_api,node_category_api,node_chat_api,node_recommend_api,node_uvicorn_runtime toneAmber
class node_database_py,node_kategoriler_table,node_kiyafetler_table,node_sqlite_db toneMint
class node_gemini_client_py,node_gemini_api toneRose
class node_env_example toneIndigo
```

## Components

### Client/UI

Browser-facing test surfaces for exercising the backend.

- [Test Panel](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/index.html): browser UI · Lightweight browser surface for wardrobe, categories, chat, and outfit recommendation. · `index.html`
- **API Docs**: browser UI · FastAPI interactive docs surface for exploring endpoints.

### FastAPI Backend

Single-process API orchestration layer.

- [App Entry](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/main.py): FastAPI app · Central orchestration layer exposed through Uvicorn as the main HTTP service. · `main.py`
- **Wardrobe API**: CRUD routes · Add, list, detail, update, and delete clothing items scoped by user.
- **Category API**: admin routes · Manages editable clothing attribute lists persisted in the database.
- **Chat API**: conversation routes · Accepts user messages and coordinates Gemini-powered chatbot flow.
- **Recommend API**: outfit routes · Combines wardrobe data and context to generate outfit recommendations.
- **Uvicorn**: server runtime · Process host that launches the FastAPI app.

### Persistence

Local database boundary and domain tables.

- [Storage Layer](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/database.py): SQLite access · Owns database connections and isolates the persistence backend from the API layer. · `database.py`
- **Categories**: domain table · Editable option lists for fabric, cut, collar, sleeve, pattern, season, style, and usage frequency.
- **Wardrobe**: domain table · User-scoped clothing inventory with core fields and rich metadata.
- **SQLite Store**: local database · Current persistence engine backing wardrobe and category data.

### AI Integration

Gemini-backed conversational and recommendation capabilities.

- [Gemini Client](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/gemini_client.py): AI adapter · Encapsulates all Google Gemini request, response, and prompt handling. · `gemini_client.py`
- **Gemini API**: external LLM · Remote Google Gemini service used for chat and outfit reasoning.

### Config

Externalized runtime settings and secrets.

- [Env Config](https://github.com/ahmetcolak251113/yzta_bootcamp_team35/blob/Ahmet/env.example): runtime config · Documents required environment variables such as API key and model name. · `env.example`

## Connections

- Uvicorn → App Entry: serves · Uvicorn starts the application entrypoint.
- Test Panel → App Entry: calls · Browser test panel sends requests to the backend API.
- API Docs → App Entry: explores · Swagger UI is generated from the FastAPI app.
- App Entry → Wardrobe API: routes · Main application exposes wardrobe CRUD endpoints.
- App Entry → Category API: routes · Main application exposes category management endpoints.
- App Entry → Chat API: routes · Main application exposes the chatbot endpoint.
- App Entry → Recommend API: routes · Main application exposes outfit recommendation endpoints.
- Wardrobe API → Storage Layer: reads/writes · Wardrobe operations persist through the storage boundary.
- Category API → Storage Layer: reads/writes · Category values are loaded and updated via the storage layer.
- Chat API → Gemini Client: delegates · Chat flow delegates conversational reasoning to Gemini adapter.
- Recommend API → Storage Layer: loads · Recommendation flow reads the user's wardrobe from storage.
- Recommend API → Gemini Client: delegates · Recommendation flow uses Gemini for ranking and explanation.
- Storage Layer → SQLite Store: uses · Storage layer currently persists to local SQLite.
- Storage Layer → Categories: owns · Database module manages editable clothing-category records.
- Storage Layer → Wardrobe: owns · Database module manages user-scoped wardrobe records.
- Gemini Client → Gemini API: calls · Adapter sends prompts and receives model responses.
- Env Config → Gemini Client: configures · Environment variables provide API key and model selection.
- Env Config → App Entry: configures · Runtime settings are externalized from the application code.