ahmetcolak251113/yzta_bootcamp_team35

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.