Update README.md for deployment instructions and enhance project structure

README.md

@@ -1,46 +1,168 @@
+# CrownCode Backend
+
+YouTube-first backend service for AI music detection workflows.
+
 ---
-title: CrownCode Backend
-emoji: 👑
-colorFrom: yellow
-colorTo: red
-sdk: docker
-pinned: false
-license: mit
+
+## Hugging Face Spaces Deployment
+
+### Quick Deploy
+
+1. **Hugging Face Space Olustur**
+   - [huggingface.co/new-space](https://huggingface.co/new-space) adresine git
+   - Space Name: `crowncode-backend`
+   - SDK: **Docker** (onemli!)
+   - Hardware: **CPU Basic (Free)**
+
+2. **Dosyalari Yukle**
+   - Space sayfasinda "Files" sekmesine git
+   - "Add file" > "Upload files" tikla
+   - Su dosyalari yukle:
+     - `Dockerfile`
+     - `requirements.txt`
+     - `app/` klasoru (tum icerigi ile)
+
+3. **Deploy**
+   - "Commit changes" butonuna bas
+   - 3-5 dakika icinde build tamamlanir
+
+### URL Format
+```
+https://KULLANICI_ADI-crowncode-backend.hf.space
+```
+
+### Test Endpoints
+```
+GET  /api/health     -> {"status": "healthy"}
+GET  /docs           -> Swagger UI
+POST /api/youtube/analyze
+```
+
 ---
 
-# CrownCode Backend API
+## What This Service Does
+
+- Accepts a YouTube URL
+- Downloads audio via `yt-dlp`
+- Optionally forwards the audio to external services:
+  - Music-AIDetector (`/predict`)
+  - Ses-Analizi (`/analyze`)
+- Produces a deterministic preview decision if no model is available
 
-AI-powered music detection and data analysis backend service.
+---
 
-## Endpoints
+## Structure
+
+```
+backend/
+  Dockerfile          <- Hugging Face Spaces icin
+  requirements.txt    <- CPU-compatible dependencies
+  app/
+    main.py
+    schemas.py
+    routes/
+      health.py
+      youtube.py
+      data_processing.py
+    services/
+      external_clients.py
+      url_parser.py
+      youtube_analysis.py
+      youtube_downloader.py
+      audio_processor.py
+      validation.py
+      logging_config.py
+      preview_model.py
+```
+
+---
+
+## API Endpoints
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/health` | Health check |
-| GET | `/docs` | Swagger UI |
 | POST | `/api/youtube/analyze` | Analyze YouTube video |
 | POST | `/api/data/augment/audio` | Audio augmentation |
 | POST | `/api/data/augment/image` | Image augmentation |
 
-## Usage
+### POST /api/youtube/analyze
+
+Request body:
+```json
+{
+  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
+  "include_raw": false
+}
+```
+
+Response:
+```json
+{
+  "summary": {
+    "decision": "ai_generated",
+    "confidence": 0.85,
+    "source": "preview_model"
+  },
+  "music_ai": { ... },
+  "ses_analizi": { ... },
+  "warnings": [],
+  "errors": []
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CROWNCODE_CORS_ORIGINS` | `*` | Allowed CORS origins |
+| `MUSIC_AI_API_URL` | - | Music-AIDetector service URL |
+| `SES_ANALIZI_API_URL` | - | Ses-Analizi service URL |
+| `CROWNCODE_API_TIMEOUT_SEC` | `30` | External service timeout |
+| `SES_ANALIZI_THRESHOLD` | `0.5` | Authenticity score threshold |
+| `LOG_LEVEL` | `INFO` | Logging level |
+
+---
+
+## Frontend Configuration
+
+Backend deploy edildikten sonra frontend `.env` dosyasini guncelle:
+
+```env
+NEXT_PUBLIC_API_URL=https://kullaniciadi-crowncode-backend.hf.space
+```
+
+---
+
+## Local Development
 
 ```bash
-# Health check
-curl https://rthur2003-crowncode-backend.hf.space/api/health
+# Install dependencies
+pip install -r requirements.txt
+
+# Install PyTorch CPU
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
 
-# Swagger docs
-https://rthur2003-crowncode-backend.hf.space/docs
+# Run server
+uvicorn app.main:app --reload --port 8000
 ```
 
-## Tech Stack
+---
 
-- FastAPI
-- PyTorch (CPU)
-- Transformers
-- yt-dlp + FFmpeg
-- Librosa
+## Docker Local Build
+
+```bash
+docker build -t crowncode-backend .
+docker run -p 7860:7860 crowncode-backend
+```
+
+---
 
-## Links
+## Notes
 
-- [CrownCode Platform](https://hasanarthuraltuntas.xyz)
-- [GitHub](https://github.com/Rtur2003/CrownCode)
+- `yt-dlp` requires network access and works best with `ffmpeg` installed
+- When external services are not configured, returns preview decision
+- Hugging Face free tier has 16GB RAM and 2 vCPU
+- Build may take 5-10 minutes due to PyTorch installation

pyproject.toml

@@ -0,0 +1,96 @@
+# CrownCode Backend - Linting and Formatting Configuration
+
+[tool.black]
+line-length = 100
+target-version = ['py311']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "C",   # flake8-comprehensions
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "N",   # pep8-naming
+    "S",   # bandit security
+    "A",   # flake8-builtins
+    "T20", # flake8-print
+]
+ignore = [
+    "E501",  # line too long (handled by black)
+    "B008",  # do not perform function calls in argument defaults
+    "C901",  # too complex
+    "S101",  # use of assert
+    "T201",  # print found (allowed in scripts)
+]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]  # unused imports
+"tests/*" = ["S101"]      # assert allowed in tests
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "yt_dlp.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "httpx.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers --cov=app --cov-report=term-missing"
+testpaths = [
+    "tests",
+]
+python_files = "test_*.py"
+python_functions = "test_*"
+
+[tool.coverage.run]
+source = ["app"]
+omit = [
+    "*/tests/*",
+    "*/test_*.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

requirements.txt

@@ -1,6 +1,6 @@
 # === Core Framework ===
-fastapi>=0.109.0
-uvicorn[standard]>=0.27.0
+fastapi>=0.103.0,<0.104.0
+uvicorn[standard]>=0.23.2,<0.24.0
 pydantic>=2.5.3
 python-multipart>=0.0.6