IQV API Middleware

API tanımlarını (API adı, URL, engine türü, Total/Input/Output sayaçları) yöneten web uygulaması. Kurulum, güncelleme ve kaldırma tek komutla yapılır — manuel npm install / npm run build adımı gerekmez.

---

Quick Start

İşlem	Windows (PowerShell, Yönetici)	Linux
Install (Docker)	.\install.ps1 -Mode docker	sudo ./install.sh --mode docker
Install (Native)	.\install.ps1 -Mode native	sudo ./install.sh --mode native
Update	.\update.ps1	sudo ./update.sh
Uninstall	.\uninstall.ps1	sudo ./uninstall.sh

-Mode / --mode verilmezse: önce kayıtlı kurulum modu, o da yoksa Docker çalışıyorsa docker, değilse native seçilir.

Kurulum sonrası:

• Uygulama : http://localhost:8080/
• Swagger : http://localhost:8080/api-docs
• OpenAPI : http://localhost:8080/openapi.json

---

Architecture

Katman	Teknoloji
Frontend	React + TypeScript + Vite (dashboard/)
Backend	Node.js + TypeScript + Express (backend/)
Database	MongoDB (harici)
Storage	MinIO (harici)
Mail	SMTP (harici)
Swagger UI	React route: /api-docs (frontend)
OpenAPI dokümanı	GET /openapi.json, GET /openapi.yaml (backend)

Tek OpenAPI kaynağı: backend/api/openapi.yaml. Backend Swagger HTML render etmez, yalnızca dokümanı sunar; arayüz React tarafındadır.

MongoDB / MinIO / SMTP bu depo tarafından kurulmaz ve yönetilmez; adresleri backend/.env içinden okunur.

---

Requirements

Gereksinim	Docker modu	Native modu
Git	✔	✔
Docker + Compose v2	✔	—
Node.js 22 (>=22 <23)	—	✔
Nginx	—	✔ (Linux)
Yönetici / root	—	✔

Node sürümü dashboard/package.json → engines ile eşleşmelidir. Installer beklenmedik major yükseltme yapmaz; uyumsuz sürümde hata verip durur.

---

Install

Windows — Docker

.\install.ps1 -Mode docker

Windows — Native

.\install.ps1 -Mode native

Linux — Docker

sudo ./install.sh --mode docker

Linux — Native

sudo ./install.sh --mode native

Install akışı: dependency kontrol → .env doğrulama (mevcut olan korunur) → frontend/backend kurulum → production build → servis/container başlatma → health check → sürüm kaydı.

---

Update

.\update.ps1 -Mode docker     # veya -Mode native, ya da mod otomatik
.\update.ps1 -Force           # sürüm aynı olsa da yeniden derle

sudo ./update.sh --mode docker   # veya --mode native
sudo ./update.sh --force

Akış: mevcut sürüm/commit oku → backend/.env yedekle (değiştirme) → git fetch → git pull --ff-only → yeni sürümü tespit et → bağımlılık + build → restart → health check → sürüm kaydını güncelle.

• Commit edilmemiş yerel değişiklik varsa güncelleme durdurulur (körlemesine overwrite yok).
• git reset --hard kullanılmaz.
• Fast-forward yapılamıyorsa (diverge/conflict) sistem değiştirilmeden çıkılır.
• Sürüm aynıysa Already up to date denir, gereksiz rebuild yapılmaz.
• Build/health başarısızsa önceki commit'e kontrollü rollback denenir; takip edilmeyen dosyalar ve .env silinmez.

---

Uninstall

.\uninstall.ps1 -Mode docker
.\uninstall.ps1 -Mode native -Yes
.\uninstall.ps1 -Mode docker -PurgeData      # SADECE bu projeye ait local volume
.\uninstall.ps1 -Mode native -RemoveCode     # uygulama kodunu da siler

sudo ./uninstall.sh --mode docker
sudo ./uninstall.sh --mode native --yes
sudo ./uninstall.sh --mode docker --purge-data
sudo ./uninstall.sh --mode native --remove-code

Kaldırılanlar: uygulama container'ları / Windows görevleri / systemd unit'i, proje network'ü, yalnızca bu projeye ait imajlar, build çıktıları (dist/, node_modules/), Nginx site config'i, kurulum kaydı.

Korunanlar (varsayılan): harici MongoDB verisi, harici MinIO verisi, SMTP yapılandırması, backend/.env, local Docker volume'ları.

• --purge-data / -PurgeData yalnızca bu projeye ait local volume'ları siler, onay ister ve harici veritabanlarına asla uygulanmaz.
• --remove-code / -RemoveCode script kaldırılacak dizinin içinden çalışıyorsa güvenlik gereği reddedilir; dizin dışından çalıştırılmalıdır.
• docker system prune kullanılmaz; başka projelerin kaynaklarına dokunulmaz.

---

Versioning

Tek kaynak: repo kökündeki VERSION dosyası (SemVer X.Y.Z).

• MAJOR → geriye uyumsuz değişiklik
• MINOR → geriye uyumlu yeni özellik
• PATCH → geriye uyumlu düzeltme

Kurulu sürüm kaydı:

• Windows: %ProgramData%\iqv-api-middleware\installed-version
• Linux (root): /var/lib/iqv-api-middleware/installed-version
• Linux (kullanıcı): ~/.local/state/iqv-api-middleware/installed-version

Kayıt üç satır tutar: sürüm, mod (docker/native), commit hash. Update bu kaydı okuyup Current / Available karşılaştırması yapar.

---

Environment Variables

Gerçek .env asla commit edilmez (.gitignore ile korunur). Şablon: backend/.env.example.

Installer mevcut .env dosyasını korur, üzerine yazmaz; şablonda olup .env içinde olmayan anahtarları yalnızca raporlar (değer üretmez).

Grup	Anahtarlar
Çalışma	NODE_ENV, PORT, TRUST_PROXY
MongoDB	MONGODB_HOST, MONGODB_PORT, MONGODB_DATABASE, MONGODB_USERNAME, MONGODB_PASSWORD, MONGODB_AUTH_SOURCE, MONGODB_PLATFORM_COLLECTION, MONGODB_PLATFORM_QUEUE_COLLECTION
Kimlik	JWT_SECRET, JWT_EXPIRES_IN
CORS	CORS_ORIGIN
MinIO	MINIO_ENDPOINT, MINIO_PORT, MINIO_USE_SSL, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, PLATFORM_FILE_BUCKET, UPLOAD_ALLOWED_BUCKETS, PLATFORM_UPLOAD_BODY_LIMIT
SMTP	SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_TLS, SMTP_USER, SMTP_PASSWORD, SMTP_FROM
AI	GEMINI_API_KEY, NOTES_LLM_RATE_LIMIT_WINDOW_MS, NOTES_LLM_RATE_LIMIT_MAX
Sentry (opsiyonel)	SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_TRACES_SAMPLE_RATE

SENTRY_DSN boş bırakılırsa hata izleme devre dışıdır; uygulama normal çalışır.

Frontend build değişkeni: VITE_API_BASE_URL (production'da /api/v1 — göreli yol, CORS oluşmaz). Değerler build zamanında gömülür.

Gizli değerler bu dokümanda, loglarda veya scriptlerde yer almaz.

---

Docker Architecture

• Compose project adı: iqv-api-middleware (uninstall başka projelere dokunmaz)
• Network: iqv-api-middleware-net
• backend : node dist/server.js, 3001, env_file: backend/.env, restart: unless-stopped, healthcheck /health
• frontend: Vite build + Nginx, host 8080 → 80, depends_on: backend (service_healthy)
• Frontend, backend'e container service adıyla ulaşır (http://backend:3001); localhost container-to-container kullanılmaz
• Harici MongoDB/MinIO için host.docker.internal (Linux'ta host-gateway)

Portu değiştirmek için: IQV_FRONTEND_PORT=9090 sudo ./install.sh --mode docker

---

Native Architecture

Linux: backend systemd (iqv-api-middleware-backend.service, EnvironmentFile=backend/.env, Restart=on-failure), frontend Nginx ile dashboard/dist üzerinden servis edilir. SPA fallback: try_files $uri $uri/ /index.html → /login, /api-middleware, /api-docs hard reload'da çalışır. /openapi.json ve /api/ backend'e proxy'lenir.

Windows: tek standart olarak Scheduled Task kullanılır (IQV-API-Middleware-Backend, IQV-API-Middleware-Frontend); AtStartup tetikleyici ile reboot sonrası otomatik başlar, terminal açık kalması gerekmez. npm run dev production servisi olarak kullanılmaz.

Frontend production sunucusu deterministiktir: serve paketi dashboard/package.json → dependencies içinde sabitlenmiştir ve kurulum sırasında npm ci ile yerel node_modules'a iner. Scheduled Task doğrudan node node_modules\serve\build\main.js -s dist -l <port> çalıştırır — çalışma anında npx ile internetten paket indirilmez. -s bayrağı SPA fallback sağlar (/login, /api-middleware, /api-docs hard reload'da çalışır). Elle çalıştırmak için: npm run start:prod (dashboard dizininde).

Kurumsal dağıtımda IIS veya Nginx reverse proxy tercih edilebilir; standart installer bunları zorunlu tutmaz ve kurmaz.

Her iki mod da aynı env sözleşmesini kullanır.

---

Health Checks

Kontrol	Docker	Native
Frontend	http://localhost:8080/	http://localhost:8080/
Backend	http://localhost:8080/api/v1/health	http://localhost:3001/health
OpenAPI	http://localhost:8080/openapi.json	http://localhost:8080/openapi.json
Container	docker compose -p iqv-api-middleware ps	systemctl status iqv-api-middleware-backend

Install/update yalnızca "process başladı" demez; gerçek HTTP yanıtı doğrular.

---

Swagger

• Arayüz: /api-docs — React route (dashboard/src/components/api-docs/SwaggerDocs.tsx)
• Doküman: /openapi.json, /openapi.yaml — backend, backend/api/openapi.yaml

Backend portunda /api-docs/ 404 döner; bu bilinçlidir.

---

Backup / Recovery Notes

• Yedeklenecekler: backend/.env, harici MongoDB dump'ı, MinIO bucket'ları.
• Update her çalıştığında backend/.env.bak.<zaman> yedeği oluşturur (içerik değiştirilmez). Bu yedekler gizli veri taşır — .gitignore ile korunur, dışarı kopyalanmamalıdır.
• Kod geri alma: git log ile hedef commit bulunup git checkout <commit> -- . ardından ilgili install/update komutu çalıştırılır.
• Uninstall veritabanı yedeği almaz; veri sizin harici sisteminizde kalır.

---

Troubleshooting

Belirti	Kontrol
Docker daemon calismiyor	Docker Desktop / systemctl status docker
Uyumsuz Node surumu	node -v → 22.x olmalı
Update durdu: "yerel degisiklikler"	git status → commit/stash
Frontend 200, backend 502	backend/.env → MongoDB adresi; docker compose logs backend
/api-docs boş	/openapi.json 200 dönüyor mu
Port çakışması	IQV_FRONTEND_PORT ile değiştirin

Development (yalnızca geliştirme)

Production kurulumu için scriptleri kullanın. Geliştirme sırasında:

cd backend  && npm run dev     # tsx watch, :3001
cd dashboard && npm run dev    # vite, :5173

---

Security Notes

• .env commit edilmez; .env.example yalnızca şablondur.
• JWT_SECRET güçlü ve ortama özel olmalıdır; varsayılan değerle production'a çıkılmaz.
• MongoDB ve MinIO gereksiz yere public internete açılmamalıdır.
• SMTP kimlik bilgileri yalnızca .env içinde tutulur.
• Production'da CORS_ORIGIN sınırlandırılmalıdır (* kullanılmaz).
• Reverse proxy arkasındaysanız TRUST_PROXY güvenilen atlama sayısıyla ayarlanır.
• Scriptler gizli değer loglamaz.

---

Production Edge / Reverse Proxy

Depo dışında bir edge katmanı (Caddy, bulut LB vb.) kullanıyorsanız routing manuel olarak şöyle olmalıdır:

Yol	Hedef
/api-docs, /api-docs/*	frontend (SPA route)
/openapi.json, /openapi.yaml	backend
/api/v1/*	backend
diğer tüm yollar	frontend (SPA fallback)

/api-docs daha önce backend'e yönlendiriliyorduysa bu kural kaldırılmalıdır.