IQV Platform

IQV Platform; kurumların platform modüllerini, notlarını, hatırlatıcılarını ve kullanıcı erişim yetkilerini tek bir yönetim panelinden takip etmesini sağlayan, rol tabanlı bir yönetim panelidir. Depo bir monorepo'dur: React + TypeScript arayüz ile Node.js + TypeScript API aynı çatı altında, ortak bir CI kalite hattıyla birlikte tutulur.

Bu depoyu ilk kez açıyorsanız doğrudan Hızlı başlangıç bölümüne geçebilirsiniz.

---

Quick Start (production kurulumu)

Tek komutla kurulum. npm install, npm run build, docker compose, servis oluşturma, nginx ayarlama veya klasör açma gerekmez — hepsini scriptler yapar.

git clone https://github.com/iqvizyon-development/iqv-platform.git
cd iqv-platform

Senaryo	Kurulum	Güncelleme	Kaldırma
Windows + Auto	.\scripts\windows\install.ps1	.\scripts\windows\update.ps1	.\scripts\windows\uninstall.ps1
Linux + Auto	sudo ./scripts/linux/install.sh	sudo ./scripts/linux/update.sh	sudo ./scripts/linux/uninstall.sh
Windows + Docker	.\scripts\windows\install.ps1 -Mode docker	.\scripts\windows\update.ps1 -Mode docker	.\scripts\windows\uninstall.ps1 -Mode docker
Windows + Native	.\scripts\windows\install.ps1 -Mode native	.\scripts\windows\update.ps1 -Mode native	.\scripts\windows\uninstall.ps1 -Mode native
Linux + Docker	sudo ./scripts/linux/install.sh --mode docker	sudo ./scripts/linux/update.sh --mode docker	sudo ./scripts/linux/uninstall.sh --mode docker
Linux + Native	sudo ./scripts/linux/install.sh --mode native	sudo ./scripts/linux/update.sh --mode native	sudo ./scripts/linux/uninstall.sh --mode native

Mod seçimi (auto) — -Mode / --mode verilmezse mod otomatik belirlenir ve seçilen mod ekrana yazılır: önce kayıtlı kurulum modu (varsa) kullanılır, yoksa Docker daemon çalışıyorsa docker, çalışmıyorsa native seçilir. Sessizce yanlış moda düşme yoktur; mod uygun değilse script tek ve açık bir hata ile durur.

Linux'ta ilk kez çalıştırmadan önce:

chmod +x scripts/linux/*.sh

Kurulum sonrası: http://localhost:5173/

Ayrıntılar için Production Installation bölümüne bakın.

---

İçindekiler

0. Production Installation
1. Sistem bileşenleri
2. Gereksinimler
3. Hızlı başlangıç
4. Kurulum — Docker olmadan
5. Kurulum — Docker ile
6. Ortam değişkenleri
7. Kurulum doğrulama
8. Komut referansı
9. Öne çıkan özellikler
10. Proje yapısı
11. CI / Quality Pipeline
12. Dokümantasyon
13. Sorun giderme
14. Geri bildirim

---

---

Production Installation

Bu bölüm, depoyu kurulabilir bir ürün olarak çalıştırmak içindir. Üç operasyon (install / update / uninstall), iki işletim sistemi (Windows / Linux) ve iki mod (Docker / Native) — toplam 4 dağıtım senaryosu.

1. Architecture

Katman	Production çalışma şekli
Frontend (dashboard/)	React 18 + TypeScript + Vite. Production çıktısı dashboard/dist/ (statik). Vite dev server production'da ÇALIŞMAZ. Docker'da Nginx (dashboard/nginx.conf), Linux native'de sistem Nginx'i, Windows native'de scripts/serve-spa.mjs (Node yerleşik modülleri; ek bağımlılık yok) sunar.
Backend (backend/)	Node.js + TypeScript + Express. tsc ile backend/dist/ üretilir, node dist/server.js ile çalışır (tsx watch kullanılmaz).
Database	Harici MongoDB — veritabanı iqvizyon, kullanıcı koleksiyonu iqvizyon-users, platform koleksiyonu platform-data. Compose MongoDB container'ı oluşturmaz; adres backend/.env içinden gelir.
MinIO / SMTP / Gemini	Harici servisler. Installer bunları kurmaz, başlatmaz, silmez.

API çağrıları her modda aynı origin üzerinden gider (/api/v1 göreli yolu); frontend derlemesinde sabit backend adresi bulunmaz ve CORS devreye girmez.

Tarayıcı ──► :5173  Nginx / serve-spa.mjs ──► /api/*  ──► backend :3001 ──► harici MongoDB
                    (SPA fallback: /platform, /notlar, /ayarlar)

2. Prerequisites

Installer büyük sistem bağımlılıklarını (Docker, Node, nginx) kendiliğinden kurmaz; eksikse açık hata verir ([ERROR] Docker not installed).

Mod	Gerekli
Docker	Docker Engine / Docker Desktop çalışır durumda (CLI'nin varlığı yeterli sayılmaz; docker info kontrol edilir).
Native	Node.js 22 (dashboard/package.json → engines.node: ">=22 <23"; backend >=20 — kesişim 22), npm, git. Linux'ta ayrıca nginx ve systemd. Windows'ta Administrator PowerShell.
Her ikisi	Erişilebilir harici MongoDB (iqvizyon).

3. Environment

• Tek gizli-değer kaynağı: backend/.env (.gitignore içindedir).
• Installer .env yoksa .env.example'dan oluşturur; varsa asla üzerine yazmaz.
• .env.example yeni anahtar kazandıysa update sırasında eksik anahtarlar uyarı olarak listelenir, değer yazılmaz.
• Zorunlu ve dolu olması gereken anahtarlar: JWT_SECRET, MONGODB_DATABASE. Boşsa kurulum [ERROR] ile durur (exit 3).
• Installer varsayılan parola/secret ÜRETMEZ. Değerleri siz doldurursunuz.

4. Docker Installation

# Windows
.\scripts\windows\install.ps1 -Mode docker

# Linux
chmod +x scripts/linux/*.sh
sudo ./scripts/linux/install.sh --mode docker

Yapılanlar: docker compose -p iqv-platform up -d --build → imajlar iqv-platform-backend:<VERSION> ve iqv-platform-frontend:<VERSION> → network iqv-platform-net → health check.

5. Native Installation

# Windows (Administrator PowerShell)
.\scripts\windows\install.ps1 -Mode native

# Linux
sudo ./scripts/linux/install.sh --mode native

Yapılanlar: npm ci (backend + dashboard) → production build → servis kaydı (Windows: Scheduled Task, Linux: systemd + nginx site) → health check.

6. Windows

İşlem	Komut
Kurulum	.\scripts\windows\install.ps1 -Mode docker / .\scripts\windows\install.ps1 -Mode native
Güncelleme	.\scripts\windows\update.ps1 -Mode docker / .\scripts\windows\update.ps1 -Mode native
Kaldırma	.\scripts\windows\uninstall.ps1 -Mode docker / .\scripts\windows\uninstall.ps1 -Mode native
Yardım	Get-Help .\scripts\windows\install.ps1 -Full
Ne yapılacağını gör	.\scripts\windows\install.ps1 -DryRun, .\scripts\windows\uninstall.ps1 -DryRun

Native modda otomatik başlatma Windows Scheduled Task ile yapılır (IQV-Platform-Backend, IQV-Platform-Frontend); trigger AtStartup ve principal SYSTEM'dir → makine yeniden başladığında kullanıcı oturumu açılmasa da çalışır.

7. Linux

İşlem	Komut
Kurulum	sudo ./scripts/linux/install.sh --mode docker / --mode native
Güncelleme	sudo ./scripts/linux/update.sh --mode docker / --mode native
Kaldırma	sudo ./scripts/linux/uninstall.sh --mode docker / --mode native
Yardım	./scripts/linux/install.sh --help
Ne yapılacağını gör	./scripts/linux/install.sh --dry-run, ./scripts/linux/uninstall.sh --dry-run

Native modda backend systemd (iqv-platform-backend.service, Restart=on-failure), frontend sistem nginx'i (/etc/nginx/sites-available/iqv-platform) tarafından sunulur.

8. Update

.\scripts\windows\update.ps1 -Mode docker            # Windows

sudo ./scripts/linux/update.sh --mode docker       # Linux

Akış:

1. Mevcut sürüm ve commit okunur (VERSION + kurulum kaydı).
2. backend/.env yedeklenir (.env.bak.<zaman>) — içerik değiştirilmez.
3. Çalışma ağacı kirliyse durur (exit 5). git reset --hard / git clean kullanılmaz.
4. git fetch --prune + git pull --ff-only. Non-fast-forward ise durur, otomatik merge üretilmez.
5. Sürüm ve commit aynıysa Already up to date → NO-OP (--force / -Force ile zorlanır).
6. Native'de önce build, sonra restart — build başarısızsa çalışan servis durdurulmaz.
7. Health check; başarısızsa rollback.

Parametreler: --mode / -Mode, --branch / -Branch, --remote / -Remote, --force / -Force, --dry-run / -DryRun. Varsayılan remote origin, varsayılan branch mevcut checkout branch'idir (bu depoda main).

9. Uninstall

.\scripts\windows\uninstall.ps1 -Mode docker [-PurgeData] [-RemoveCode] [-DryRun] [-Yes]

sudo ./scripts/linux/uninstall.sh --mode docker [--purge-data] [--remove-code] [--dry-run] [--yes]

Siler: uygulama container'ları / Scheduled Task / systemd unit, uygulamaya ait Docker imajları ve iqv-platform-net network'ü, uygulamanın nginx site config'i, build çıktıları (dist, node_modules), startup kayıtları, kurulum kaydı.

Silmez: harici MongoDB (drop edilmez), harici MinIO, SMTP yapılandırması, backend/.env ve .env.bak.* yedekleri, başka uygulamaların container/servis/nginx kaynakları, paylaşılan Docker network/volume'ları. docker system prune kullanılmaz.

--purge-data yalnızca bu projeye ait local Docker volume'larını siler; harici veritabanına hiçbir koşulda uygulanmaz.

dashboard/dist bu depoda bilerek git ile izlenir. Native uninstall bunu korur — silinse çalışma ağacı kirlenir ve sonraki update fail-safe durur.

--remove-code / -RemoveCode recursive delete guard: silme yapılmadan önce hedef yol doğrulanır — mutlak yol olmalı, var olan bir dizin olmalı, filesystem/sürücü kökü ve sistem dizinleri (/usr, /var, /home, /tmp, %SystemRoot%, %ProgramFiles%, %ProgramData%, %USERPROFILE%) reddedilir, en az iki seviye derinlikte olmalı ve IQV imzası (docker-compose.yml + backend/ + dashboard/ + scripts/<platform>/lib.*) eksiksiz bulunmalıdır. Kontrollerden biri bile başarısız olursa işlem reddedilir ve hiçbir şey silinmez; rm -rf / benzeri davranış yapısal olarak mümkün değildir. Ayrıca silinecek dizinin içinden çalıştırılırsa self-delete koruması devreye girer ve doğru komut yazdırılır.

10. Versioning

• Tek kaynak: depo kökündeki VERSION dosyası (SemVer, örn. 1.1.0).
• Docker imaj etiketi bu sürümden üretilir (iqv-platform-backend:1.1.0) — tek başına mutable latest kullanılmaz.
• Kurulum kaydı 3 satırdır: sürüm, mod, commit.
  • Linux: /var/lib/iqv-platform/installed-version (root) veya ~/.local/state/iqv-platform/installed-version
  • Windows: %ProgramData%\iqv-platform\installed-version
• Update, VERSION ve commit karşılaştırır; ikisi de aynıysa NO-OP.

11. Health Checks

Health kontrolü "process ayakta mı" değil, gerçek HTTP 200 kontrolüdür.

Mod	Frontend	Backend
Docker	http://localhost:5173/	http://localhost:5173/api/v1/health (Nginx proxy)
Native	http://localhost:5173/	http://localhost:3001/health

Container HEALTHCHECK tanımları docker-compose.yml içindedir (backend: Node fetch ile /health; frontend: wget /).

12. Logs

Ortam	Komut
Docker	docker compose -p iqv-platform logs -f
Linux native (backend)	journalctl -u iqv-platform-backend.service -f
Linux native (frontend)	/var/log/nginx/access.log, /var/log/nginx/error.log
Windows native	Görev geçmişi: Get-ScheduledTaskInfo -TaskName IQV-Platform-Backend · Olay günlüğü: Get-WinEvent -LogName Microsoft-Windows-TaskScheduler/Operational

Docker'da log rotasyonu compose içinde tanımlıdır (max-size: 10m, max-file: 3). Linux native'de loglar journald'a gider (rotasyon sistem tarafından yönetilir) — ayrı bir log dosyası büyümez.

13. Status commands

docker compose -p iqv-platform ps                       # Docker
systemctl status iqv-platform-backend.service           # Linux native

Get-ScheduledTask -TaskName IQV-Platform-*              # Windows native

14. Directory structure (deployment)

<repo>/                       # git checkout = kurulum kökü (update `git pull` yapar)
├── VERSION                   # sürüm tek kaynağı
├── docker-compose.yml        # production stack (project: iqv-platform)
├── scripts/windows/  install.ps1 / update.ps1 / uninstall.ps1 / lib.psm1
├── scripts/linux/    install.sh  / update.sh  / uninstall.sh  / lib.sh
├── scripts/
│   ├── linux/lib.sh          # Linux ortak sabitler + yardımcılar
│   ├── windows/lib.psm1      # Windows ortak sabitler + yardımcılar (PowerShell modülü)
│   └── serve-spa.mjs         # Windows native statik sunucu (+/api proxy)
├── backend/                  # API   → dist/ (build), .env (gizli, korunur)
└── dashboard/                # UI    → dist/ (build)

Kurulum kaydı (sürüm/mod/commit) kod dizininin dışında tutulur, böylece update kodu değiştirdiğinde kaybolmaz.

15. Source install model

Update git pull ile çalışır; bu yüzden production kurulumu geçerli bir git checkout olmalıdır:

git clone https://github.com/iqvizyon-development/iqv-platform.git
cd iqv-platform && sudo ./scripts/linux/install.sh --mode docker

Kodu ZIP olarak indirdiyseniz update çalışmaz ([ERROR] Git deposu bulunamadı, exit 5) — bu durumda yeniden git clone yapın.

16. Exit codes

Kod	Anlamı
0	Başarılı
2	Hatalı parametre / kullanım
3	Eksik veya uyumsuz ön koşul (Docker yok, Node sürümü uyumsuz, zorunlu env boş)
4	Port çakışması
5	Git hatası (kirli ağaç, non-fast-forward, fetch başarısız, repo yok)
6	Bağımlılık veya derleme hatası
7	Health check başarısız (rollback denendi)
8	Kurulum durumu (zaten kurulu — --force gerekir)

17. Troubleshooting

Belirti	Neden / Çözüm
[ERROR] Docker daemon not running	Docker Desktop/servisi kapalı. sudo systemctl start docker veya Docker Desktop'ı başlatın.
[ERROR] Port 5173 already in use by ...	Port başka bir süreçte. Script process öldürmez; süreci kapatın veya IQV_FRONTEND_PORT=8080 verin.
[ERROR] Node version unsupported: 20	Node 22 gerekir (dashboard engines >=22 <23). Installer major yükseltme yapmaz.
MongoDB'ye ulaşılamıyor	backend/.env → MONGODB_HOST/PORT/DATABASE. Docker'da host makine adresi host.docker.internal'dır. Health check backend'i unhealthy bırakır.
Frontend saglik kontrolu BASARISIZ	Docker: docker compose -p iqv-platform logs frontend. Native: nginx/Scheduled Task durumu.
Backend saglik kontrolu BASARISIZ	journalctl -u iqv-platform-backend.service -n 100 veya docker compose -p iqv-platform logs backend. Genelde MongoDB veya .env kaynaklıdır.
[ERROR] Git dirty	Commit edilmemiş değişiklik var. git stash veya commit edin. Script hiçbir değişikliği silmez.
Update non-fast-forward	Yerel branch remote'tan ayrışmış. git log --oneline origin/main..HEAD ile inceleyin; script otomatik merge üretmez.
[ERROR] VERSION dosyasi bulunamadi	Kurulum kökü repo kökü değil ya da eksik checkout.

18. Security notes

• .env git'e commit edilmez (.gitignore), Docker imajına kopyalanmaz (.dockerignore), env_file ile çalışma anında okunur.
• Secret'lar loglanmaz: JWT_SECRET, SMTP/MinIO parolaları ve Mongo URI hiçbir script çıktısında görünmez; yalnızca eksik/boş anahtar adları raporlanır.
• Varsayılan production parolası üretilmez.
• Harici servis kimlik bilgileri installer içine hard-code edilmez.
• Backend container root ile çalışmaz (USER node), backend portu host'a yayınlanmaz — dış dünyaya tek giriş Nginx'tir.
• Uninstall harici veritabanına dokunmaz; docker system prune kullanılmaz.
• Port çakışmasında hiçbir süreç öldürülmez, yalnızca PID/isim raporlanır.

19. Swagger / API Documentation

Canonical dokümantasyon rotaları backend'e aittir (backend/src/routers/docs.routes.ts); SPA içinde aynı URL'yi sahiplenen ikinci bir React sayfası yoktur.

Rota	Ne döner
/api-docs	301/302 → /api-docs/ (trailing slash normalizasyonu)
/api-docs/	Swagger UI (HTML) — swagger-ui-express
/api-docs/iqv-swagger-groups.js	TOTAL / INTERNAL / OUTPUT / SYSTEM iki seviyeli gruplama betiği
/openapi.json	OpenAPI 3.0.3 (application/json)
/openapi.yaml	Aynı doküman (YAML)
/api/v1/... önekli eşdeğerleri	Aynı yanıtlar

PWA notu (önemli)

Bu uygulama production'da PWA'dır ve Service Worker kök kapsamda (/) çalışır. Workbox'ın navigateFallback (app-shell) kuralı kapsamı daraltılmazsa, backend'e ait /api-docs/ navigasyonu ağa hiç çıkmadan önbellekteki React index.html ile cevaplanır ve kullanıcı Swagger yerine IQV Platform 404 ekranını görür.

Bu yüzden backend-owned documentation paths are excluded from the SPA navigation fallback. Politika tek bir yerde tanımlıdır:

dashboard/src/routes/nonSpaPaths.ts     -> NON_SPA_NAVIGATION_PATHS  (tek kaynak)
dashboard/vite.config.ts                -> workbox.navigateFallbackDenylist
dashboard/nginx.conf                    -> location = /api-docs, ^~ /api-docs/, ~ ^/openapi\.(json|yaml)$
scripts/linux/install.sh (Linux native nginx site)    -> aynı location blokları
scripts/serve-spa.mjs (Windows native)  -> NON_SPA_PREFIXES
src/components/platform/index.tsx       -> göreli non-SPA URL'de navigate() yerine gerçek navigasyon

Yeni bir backend-owned HTML rotası eklerseniz (örn. /api-middleware-docs, /swagger) yalnızca dashboard/src/routes/nonSpaPaths.ts listesine ekleyin; aynı hata sınıfı tekrar oluşmaz. PWA kapatılmaz, Service Worker kapsamı değiştirilmez.

Doğrulama

# Frontend: politika + üretilen Service Worker denylist regresyonu
cd dashboard && node scripts/verify-pwa-nonspa-routes.mjs

# Backend: /api-docs ve /openapi.* gerçekten backend'den geliyor mu
#          (React app-shell dönmediği NEGATİF olarak da doğrulanır)
cd backend && npx tsx scripts/test-api-docs-routes.ts

install / update scriptleri frontend'i her zaman yeniden derler (npm run build), bu yüzden düzeltme yeni dist/sw.js içine otomatik girer — ayrıca elle "sw.js kopyala" adımı yoktur. registerType: 'autoUpdate' korunduğu için yeni Service Worker mevcut istemcileri de devralır.

---

Sistem bileşenleri

Dizin	Görevi
dashboard/	Frontend — React 18 + TypeScript + Vite. Ant Design (@ant-design/pro-components), Tailwind CSS, Redux Toolkit + redux-persist. Jest + React Testing Library test paketi dashboard/iqv-platform-test/ altındadır.
backend/	API — Node.js + TypeScript (Express). MongoDB (native driver), MinIO dosya deposu, SMTP mail gönderimi, JWT kimlik doğrulama ve OpenAPI/Swagger sözleşmesi.
ci/	CI / Quality Pipeline — faz koşucusu (scripts/run-ci.mjs), kalite politikası (scripts/ci-policy.mjs), rapor üreticisi, karantina listesi (quarantine.json) ve yerel çalıştırma için Docker Compose dosyası.
docs/	MkDocs dokümantasyonu (TR + EN). Yapılandırma kökteki mkdocs.yml, Python bağımlılıkları requirements-docs.txt dosyasındadır.
.github/workflows/	GitHub Actions — ci-quality.yml (kalite hattı) ve ci.yml (elle tetiklenen ayrıntılı iş akışı), mkdocs-pages.yml (dokümantasyon yayını).
scripts/	Depo genelinde kullanılan yardımcı betikler + deployment yardımcıları (linux/lib.sh, windows/lib.psm1, serve-spa.mjs).

Docker dosyaları

Dosya	Görevi
backend/Dockerfile	Backend API'nin production imajını üretir.
dashboard/Dockerfile	Frontend'i build edip Nginx ile sunan production imajını üretir (dashboard/nginx.conf).
ci/Dockerfile	CI koşucusunun imajı (Node 22 + git). Kod imaja kopyalanmaz, bind-mount edilir.
docker-compose.yml	Production stack — backend + frontend servisleri, healthcheck, restart policy ve iqv-platform-net network'u. MongoDB/MinIO container'i oluşturmaz (harici).
ci/docker-compose.ci.yml	Yalnızca test/CI içindir. Geçici mongo-ci, minio-ci, mailpit-ci servislerini ve kalite hattını ayağa kaldırır. Üretim veritabanına/bucket'ına dokunmaz.

Not: Depo kökündeki docker-compose.yml production stack'ini (backend + frontend) ayağa kaldırır ve scripts/windows/install.ps1 / scripts/linux/install.sh tarafından -p iqv-platform proje adıyla kullanılır. Tek komutluk kurulum için Production Installation bölümüne bakın; aşağıdaki bölüm elle (manuel) kurulum adımlarını anlatır.

---

Gereksinimler

Docker olmadan çalıştırmak için

Gereksinim	Sürüm / Not
İşletim sistemi	Windows 10/11 veya uyumlu bir Linux dağıtımı
Node.js	22 — Frontend engines.node: ">=22 <23" (dashboard/package.json) ve dashboard/.nvmrc = 22 gerektirir. Backend engines.node: ">=20" ister; iki paketin kesişimi Node 22'dir, bu yüzden tüm depoda Node 22 kullanın.
npm	Node 22 ile birlikte gelen sürüm yeterlidir. Kurulum için daima npm ci tercih edin (package-lock.json birebir uygulanır).
Git	Depoyu klonlamak ve sürüm bilgisi için gereklidir.
MongoDB	Erişilebilir bir MongoDB örneği zorunludur — backend başlangıçta bağlanır.
MinIO	Yalnızca dosya yükleme (notlara dosya ekleme) özelliği kullanılacaksa gereklidir.
SMTP	Yalnızca mail özellikleri (manuel mail, hatırlatıcı e-postası) kullanılacaksa gereklidir.
İnternet erişimi	Yalnızca Gemini/LLM gibi dış servisler kullanılacaksa gereklidir (GEMINI_API_KEY).

MinIO, SMTP ve Gemini opsiyoneldir: yapılandırılmazsa ilgili özellikler devre dışı kalır, uygulamanın geri kalanı çalışmaya devam eder.

Docker ile çalıştırmak için

Gereksinim	Not
Docker Desktop (Windows/macOS) veya Docker Engine (Linux)	Windows'ta Docker Desktop'ın çalışır durumda olması gerekir; aksi halde docker komutları "cannot connect to the Docker daemon" hatası verir.
Docker Compose v2	docker compose (tire olmadan) biçimi kullanılır. Eski docker-compose v1 desteklenmez.
Git	Depoyu klonlamak için.
Dış servisler	Uygulamanın ihtiyaç duyduğu MongoDB / MinIO / SMTP erişimi (kendi ortamınızdan sağlanır).

Kurulum öncesi kontrol komutları

node -v
npm -v
git --version
docker version
docker compose version

Beklenen çıktı: node -v → v22.x.x, docker compose version → v2.x.x.

---

Hızlı başlangıç

git clone <repo-url>
cd "Platform Frontend"

# 1) Backend
cd backend
npm ci
cp .env.example .env      # Windows cmd: copy .env.example .env
# .env dosyasını düzenleyin (en azından MONGODB_* ve JWT_SECRET)
npm run dev

# 2) Frontend (yeni bir terminalde)
cd ../dashboard
npm ci
cp .env.example .env      # Windows cmd: copy .env.example .env
# VITE_PLATFORM_API_BASE_URL değerini backend adresine ayarlayın
npm run dev

Tarayıcıda açın: http://localhost:5173

---

Kurulum — Docker olmadan

1. Depoyu klonlayın

git clone <repo-url>
cd "Platform Frontend"

2. Backend'i kurun

cd backend
npm ci

Ortam dosyasını oluşturun ve düzenleyin:

cp .env.example .env

copy .env.example .env

backend/.env.example tüm anahtarları açıklamalarıyla içerir. En az şunlar doldurulmalıdır:

• MONGODB_HOST, MONGODB_PORT, MONGODB_DATABASE (ve kimlik doğrulama varsa MONGODB_USERNAME, MONGODB_PASSWORD, MONGODB_AUTH_SOURCE)
• JWT_SECRET — üretimde mutlaka güçlü ve benzersiz bir değer
• CORS_ORIGIN — frontend adresi (geliştirmede http://localhost:5173)

Backend'i başlatın:

npm run dev          # geliştirme (tsx watch)

Üretim için:

npm run build        # TypeScript -> dist/
npm start            # dist/ üzerinden çalıştırır

3. Frontend'i kurun

cd ../dashboard
npm ci
cp .env.example .env

dashboard/.env içinde VITE_PLATFORM_API_BASE_URL değerini backend adresine ayarlayın.

npm run dev          # http://localhost:5173

Üretim build'i ve yerel önizleme:

npm run build
npm run preview

---

Kurulum — Docker ile

Windows kullanıyorsanız önce Docker Desktop'ı başlatın ve docker version komutunun hatasız çalıştığını doğrulayın.

Servis imajlarını üretme ve çalıştırma

Depoda kök seviyede bir uygulama compose dosyası bulunmadığı için imajlar ayrı ayrı üretilir:

# Backend imajı
docker build -t iqv-platform-backend:latest ./backend

# Frontend imajı (build sırasında API adresi gömülür)
docker build -t iqv-platform-dashboard:latest ./dashboard

Çalıştırma:

# Backend — ortam değişkenleri .env dosyasından okunur
docker run -d --name iqv-backend \
  --env-file backend/.env \
  -p 3001:3001 \
  iqv-platform-backend:latest

# Frontend — Nginx üzerinden statik build sunulur
docker run -d --name iqv-dashboard \
  -p 8080:80 \
  iqv-platform-dashboard:latest

Frontend: http://localhost:8080 · Backend: http://localhost:3001

Konteynerden host üzerindeki MongoDB/MinIO'ya erişmek için localhost yerine host.docker.internal (Windows/macOS) ya da host IP'si kullanın.

Kalite hattını Docker ile çalıştırma

Bu compose dosyası yalnızca test içindir; kendi geçici MongoDB, MinIO ve Mailpit servislerini ayağa kaldırır ve iş bitince siler:

docker compose -p iqv-ci -f ci/docker-compose.ci.yml run --rm ci-runner
docker compose -p iqv-ci -f ci/docker-compose.ci.yml down -v

---

Ortam değişkenleri

Her iki pakette de .env.example dosyası tam ve açıklamalı referanstır; aşağıdaki tablolar özet niteliğindedir.

⚠️ .env dosyaları depoya commit edilmez (.gitignore). Gerçek parola, API anahtarı veya bağlantı dizesini kaynak koda yazmayın.

backend/.env

Grup	Anahtarlar	Zorunlu mu?
Sunucu	NODE_ENV, PORT, TRUST_PROXY	Hayır (varsayılanları var)
MongoDB	MONGODB_HOST, MONGODB_PORT, MONGODB_DATABASE, MONGODB_USERNAME, MONGODB_PASSWORD, MONGODB_AUTH_SOURCE, MONGODB_PLATFORM_COLLECTION, MONGODB_PLATFORM_QUEUE_COLLECTION, PLATFORM_SCOPE_FILTER	Evet
Kimlik doğrulama	JWT_SECRET, JWT_EXPIRES_IN, CORS_ORIGIN	Evet
MinIO / dosya	MINIO_ENDPOINT, MINIO_PORT, MINIO_USE_SSL, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, PLATFORM_FILE_BUCKET, UPLOAD_ALLOWED_BUCKETS, PLATFORM_UPLOAD_BODY_LIMIT	Dosya yükleme kullanılacaksa
Mail	SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_TLS, SMTP_USER, SMTP_PASSWORD, SMTP_FROM	Mail kullanılacaksa
LLM	GEMINI_API_KEY, NOTES_LLM_RATE_LIMIT_WINDOW_MS, NOTES_LLM_RATE_LIMIT_MAX	LLM kullanılacaksa

dashboard/.env

Değişken	Açıklama
VITE_PLATFORM_API_BASE_URL	IQV Platform backend adresi (zorunlu)
VITE_DEMO_MODE	true ise giriş formu demo bilgileriyle önceden doldurulur
VITE_REQRES_API_KEY	Yalnızca demo "Kullanıcılar" / "Dashboard" sayfaları için ReqRes mock API anahtarı

---

Kurulum doğrulama

Kurulumun doğru olduğunu hızlıca sınamak için:

# Backend
cd backend
npm run typecheck
npm run build

# Frontend
cd ../dashboard
npm run typecheck
npm run build

Uçtan uca doğrulama için depo kökünde kalite hattını çalıştırabilirsiniz:

node ci/scripts/run-ci.mjs
node ci/scripts/generate-ci-report.mjs

Rapor ci/reports/REPORT.md dosyasında oluşur.

---

Komut referansı

Backend (backend/)

Komut	Açıklama
npm run dev	Geliştirme sunucusu (watch)
npm run build	TypeScript derlemesi → dist/
npm start	Derlenmiş çıktıyı çalıştırır
npm run typecheck	Tip kontrolü (derleme çıktısı üretmez)
npm run swagger:test	OpenAPI/Swagger sözleşme testleri
npm run nodered:test	Node-RED'den taşınan uçların regresyon testleri
npm run logs:test	Denetim (audit) log testleri
npm run logs:migrate	Log şeması geçişi

Frontend (dashboard/)

Komut	Açıklama
npm run dev	Vite geliştirme sunucusu
npm run build	Tip kontrolü + production build
npm run preview	Production build'i yerelde önizleme
npm run lint / npm run lint:fix	ESLint kontrolü / otomatik düzeltme
npm run prettier / npm run prettier:fix	Format kontrolü / otomatik format
npm run typecheck / npm run typecheck:test	Production / test TypeScript kontrolü
npm run test:iqv	Jest test paketini çalıştırır
npm run test:iqv:ci	Jest'i coverage ile CI modunda çalıştırır
npm run ci:verify	Lint + typecheck + testler + build'i sırayla çalıştırır

---

Öne çıkan özellikler

• Rol tabanlı erişim kontrolü: superadmin, companyadmin, organizationadmin, admin ve user rolleri için farklı menü ve sayfa erişimi (ör. user rolü yalnızca Platformlar ekranına erişebilir; diğer sayfalara doğrudan URL ile de girilemez).
• Platformlar: modül listesi, arama ve platform kartlarından tek tıkla URL yönlendirme.
• Notlar: dosya ekli not oluşturma/düzenleme (MinIO dosya sunucusu entegrasyonu).
• Hatırlatıcılar (zamanı gelince otomatik e-posta) ve Mail Box ekranları.
• Ayarlar ve denetim (audit) günlüğü ile kullanıcı eylemlerinin izlenmesi.
• Ant Design ve Tailwind CSS ile özelleştirilebilir arayüz; açık/koyu tema desteği.
• @ant-design/pro-components ile güçlü layout ve tablo bileşenleri.
• react-redux + @reduxjs/toolkit ile durum yönetimi; redux-persist ile kalıcı oturum.
• @loadable/component ile code splitting / lazy loading.
• Progressive Web App (PWA) desteği (yalnızca production build'de).
• Axios interceptor ile JWT tabanlı kimlik doğrulama ve oturum yönetimi.
• OpenAPI 3 tabanlı Swagger dokümantasyonu.
• ESLint (flat config) + Prettier ile kod kalitesi; Jest + React Testing Library ile geniş bir test paketi.

Giriş bilgileri

Uygulama gerçek IQV Platform backend'ine (VITE_PLATFORM_API_BASE_URL) bağlanır. Giriş yapmak için kendi kullanıcı adınızı ve parolanızı kullanın; hesabınız yoksa sistem yöneticinizden bir hesap talep edin.

Not: Uygulama içindeki "Kullanıcılar" ve "Dashboard" demo sayfaları hâlâ ReqRes mock API'sini kullanır; bu sayfaları görüntülemek isterseniz .env dosyanıza bir VITE_REQRES_API_KEY eklemeniz gerekir.

---

Proje yapısı

Platform Frontend/
├── backend/                    # Node.js + TypeScript API
│   ├── api/                    # OpenAPI/Swagger sözleşmeleri (YAML)
│   ├── src/                    # Router, servis, model ve middleware katmanları
│   ├── scripts/                # Bakım ve tanılama betikleri
│   ├── tests/                  # Unit + integration test paketi
│   ├── .env.example            # Ortam değişkeni şablonu (açıklamalı)
│   └── Dockerfile
├── dashboard/                  # React + TypeScript frontend
│   ├── config.ts               # Uygulama ayarları (isim, tema, meta etiketler, PWA)
│   ├── public/                 # Statik dosyalar
│   ├── src/
│   │   ├── components/         # Sayfa ve UI bileşenleri
│   │   ├── routes/             # Route tanımları ve rol bazlı erişim koruması
│   │   ├── store/              # Redux store ve slice'lar
│   │   └── utils/, services/   # Paylaşılan yardımcılar, HTTP istemcisi ve servisler
│   ├── iqv-platform-test/      # Jest + React Testing Library test paketi
│   ├── .env.example            # Ortam değişkeni şablonu
│   ├── .nvmrc                  # Node 22
│   ├── nginx.conf              # Production imajının web sunucusu yapılandırması
│   ├── vite.config.ts          # Vite ve PWA yapılandırması
│   └── Dockerfile
├── ci/                         # CI / Quality Pipeline
│   ├── scripts/                # Faz koşucusu, kalite politikası, rapor üreticisi
│   ├── quarantine.json         # Bilinen (non-blocking) test hataları listesi
│   ├── docker-compose.ci.yml   # Yalnızca test için geçici servisler
│   └── Dockerfile
├── docs/                       # MkDocs dokümantasyonu (TR + EN)
├── scripts/                    # Depo genelinde yardımcı betikler
├── .github/workflows/          # GitHub Actions iş akışları
├── mkdocs.yml
└── requirements-docs.txt

---

CI / Quality Pipeline

Monorepo genelinde çalışan kalite hattı: backend + dashboard testleri, Swagger sözleşme doğrulaması, tip kontrolü, ESLint, production build'ler ve güvenlik taraması. Sonuç deterministik bir puana ve PASS/FAIL kararına dönüşür; test sayıları hiçbir yerde sabit değildir, her çalışmada gerçek çıktıdan hesaplanır.

Docker ile yerel çalıştırma (host Node sürümünden bağımsız):

docker compose -p iqv-ci -f ci/docker-compose.ci.yml run --rm ci-runner
docker compose -p iqv-ci -f ci/docker-compose.ci.yml down -v

Docker'sız (Node 22):

node ci/scripts/run-ci.mjs
node ci/scripts/generate-ci-report.mjs

GitHub Actions: .github/workflows/ci-quality.yml — main ve develop push'larında, tüm pull request'lerde ve elle (workflow_dispatch) çalışır. CI kendi mongo-ci / minio-ci / mailpit-ci servislerini normal bir adımda ayağa kaldırır; üretim veritabanına, bucket'ına veya SMTP hesabına dokunmaz ve gerçek alıcıya e-posta göndermez. Servisler ayağa kalkmazsa hat durmaz; ilgili aşamalar ENVIRONMENT_UNAVAILABLE olarak raporlanır.

Karantina: ci/quarantine.json içinde açıkça ilan edilen bilinen test hataları kaliteyi bloklamaz ancak raporda Known Quarantined Tests olarak görünür kalır. Testler silinmez ve CI'da çalışmaya devam eder. İlan edilen sayıyı aşan veya listede olmayan her hata CI'ı durdurur.

Soft Gate Mode: CI çalışması blocking build/typecheck/security kontrolleri başarılı olduğu sürece yeşil tamamlanır. Test ve lint bulguları geçici olarak non-blocking quality findings olarak raporlanır. Bu mod .github/workflows/ci-quality.yml içindeki IQV_CI_SOFT_GATE değişkeni ile yönetilir; teknik borç kapandığında '0' yapılarak katı moda dönülür.

Quality Result: Actions çalışma sayfasındaki Job Summary bölümünde proje, sürüm, sonuç (PASSED/FAILED), 100 üzerinden puan ve etiketi, critical / blocking error / warning sayıları, karantina ve ortam atlama bilgileri görünür.

Artifact: iqv-platform-quality-report — test kırmızı olsa da yüklenir (if: always()); iqv-platform-ci-report.json, iqv-platform-ci-report.md, REPORT.json, REPORT.md, results.json, environment.json, ci/quarantine.json ve ham logları içerir.

---

Dokümantasyon

MkDocs dokümantasyonunu yerelde çalıştırmak için:

pip install -r requirements-docs.txt
mkdocs serve

Kurulum / güncelleme / kaldırma dokümanları (README ile birebir aynı komutlar): docs/deployment/installation.md · docs/deployment/update.md · docs/deployment/uninstall.md

CI hattının ayrıntılı dokümantasyonu: docs/ci/index.md — mimari, faz listesi, yerel çalıştırma, GitHub Actions, kalite politikası ve sorun giderme.

Katkı süreci için: CONTRIBUTE.MD

---

Sorun giderme

Belirti	Olası neden ve çözüm
npm ci sürüm hatası veriyor	Node sürümünüz 22 değil. node -v ile doğrulayın; nvm kullanıyorsanız dashboard/ içinde nvm use.
Backend başlangıçta MongoDB hatası veriyor	backend/.env içindeki MONGODB_* değerleri hatalı ya da veritabanı erişilemiyor.
Frontend'de istekler CORS hatası veriyor	Backend .env içindeki CORS_ORIGIN değeri frontend adresiyle eşleşmiyor.
Giriş yapılıyor ama istekler 401 dönüyor	JWT_SECRET değiştirilmiş olabilir; oturumu kapatıp yeniden giriş yapın.
Dosya yükleme başarısız	MinIO yapılandırılmamış veya bucket mevcut değil (MINIO_*, PLATFORM_FILE_BUCKET).
Mail gönderilemiyor	SMTP_* değerleri eksik. Tanılama için: cd backend && npx tsx scripts/test-smtp.ts (mail göndermez, sır yazdırmaz).
docker komutu bağlanamıyor	Windows'ta Docker Desktop çalışmıyor. Başlatıp docker version ile doğrulayın.
docker-compose bulunamadı	Compose v2 kullanılıyor: docker compose (tire olmadan) yazın.

---

Geri bildirim

Proje ile ilgili geri bildirim, hata bildirimi veya soru için ekip içi iletişim kanallarınızı ya da repository issue takibini kullanın.