IQV Dictionary

IQV Dictionary, Türkçe/İngilizce endüstriyel terminoloji sözlüğü ve personel yönetim paneli: React + Ant Design tabanlı bir dashboard (dashboard/) ve Express + MongoDB tabanlı bir API (backend/) içerir.

Bu README, projeyi production seviyesinde tek komutla kurmak/ güncellemek/kaldırmak için gereken operasyonel özeti verir. Mimari, Backend API ve test stratejisi gibi ayrıntılı geliştirici dokümantasyonu için bkz. Documentation.

Components

Bileşen	Teknoloji	Konum
Frontend	React 18 + TypeScript + Vite + Ant Design + Redux Toolkit	dashboard/
Backend	Node.js + Express + TypeScript (derlenmiş dist/)	backend/
Veritabanı	MongoDB (dışarıda çalışır, bu proje tarafından containerize edilmez)	backend/.env → MONGODB_URI
API Dokümantasyonu	Swagger UI + OpenAPI 3.0.3 (backend-native)	backend/docs/openapi.yaml, /api-docs
Dokümantasyon Sitesi	MkDocs + Material for MkDocs (TR/EN, açık/koyu tema, GitHub Pages)	docs/, mkdocs.yml
CI/CD	GitHub Actions — IQV Dictionary CI, IQV Dictionary Docs	.github/workflows/

Requirements

Bileşen	Docker modu	Native (Docker'sız) mod
Docker + Compose v2	✅ gerekli	—
Node.js 20+ (npm + corepack ile birlikte gelir)	yalnızca script'in kendisi için	✅ gerekli
pnpm	—	corepack ile install script'i otomatik etkinleştirir
PM2	—	install script'i otomatik kurar
Çalışan bir MongoDB örneği	✅ (dışarıda — bkz. aşağıda)	✅ (dışarıda)

IQV Dictionary, MongoDB'yi kendi başına kurmaz/containerize etmez — backend/.env'deki MONGODB_URI neyi gösteriyorsa oraya bağlanır (varsayılan: host makinede/LAN'da çalışan bir MongoDB, 127.0.0.1:27017).

Quick Start

# Windows
.\scripts\windows\install.ps1

# Linux
chmod +x ./scripts/linux/*.sh
./scripts/linux/install.sh

Bu tek komut: gerekli .env dosyalarını (yoksa, güvenli üretilmiş bir JWT_SECRET ile) oluşturur, Docker'ın mevcut olup olmadığını algılar, backend + dashboard'u production modda derler/başlatır ve /health ile gerçek bir healthcheck yapar. Kurulum bittiğinde:

• Backend: http://localhost:3001
• Frontend: http://localhost:8080 (Docker) veya http://localhost:5173 (Native)

Configuration Layers

IQV Dictionary'nin production kurulumu dört katmana ayrılmıştır. GitHub'daki kaynak generic kalır; sunucuya/müşteriye özel her şey Git'e girmeyen configuration dosyalarında durur. Böylece production sunucusunda tracked dosyaları elle patchlemek gerekmez ve git pull --ff-only hiçbir zaman çakışmaz.

Katman	Git	Ne içerir
.env (repo kökü)	❌ gitignored (.env.example tracked)	Deployment portları ve frontend build ayarı: IQV_FRONTEND_PORT, IQV_BACKEND_PORT, IQV_BIND_HOST, VITE_API_BASE_URL
backend/.env	❌ gitignored (backend/.env.example tracked)	Backend runtime: MONGODB_URI, MONGODB_DB, koleksiyonlar, JWT_SECRET, JWT_EXPIRES_IN, CORS_ORIGIN
docker-compose.prod.yml	✅ tracked	Generic production Docker tanımı — credential yok, müşteriye/sunucuya özel network/IP/port yok
docker-compose.server.yml	❌ gitignored (docker-compose.server.example.yml tracked)	Opsiyonel sunucu/müşteri override'ı: external Docker network, container topolojisi vb.

Kurallar:

• docker-compose.prod.yml MONGODB_URI'yi ezmez. MongoDB bağlantısının tek kaynak-doğrusu backend/.env'dir. Compose yalnızca extra_hosts ile host.docker.internal adının çözülebilmesini sağlar; bu adresin kullanılıp kullanılmayacağına backend/.env karar verir.
• Gerçek credential/secret (MongoDB parolası, JWT secret, token, API key) hiçbir zaman repository'ye girmez; .env.example dosyalarında yalnızca değişken ADLARI ve güvenli placeholder'lar bulunur.
• docker-compose.server.yml varsa install/update/uninstall script'leri ve npm run docker:* komutları onu otomatik algılayıp -f docker-compose.prod.yml -f docker-compose.server.yml --env-file .env şeklinde uygular. Bu çözümleme tek bir helper'da tanımlıdır (scripts/linux/lib.sh → iqv_compose, scripts/windows/lib.psm1 → Invoke-IqvCompose, scripts/common/compose.mjs), script'ler kendi compose argümanlarını üretmez.

Reverse proxy'li production örneği (Caddy)

Internet -> Caddy :443 -> iqv_proxy -> iqv-dictionary-frontend-prod
                                    `-> iqv-dictionary-backend-prod
                                            |
                                            `-> host/external MongoDB

Sunucuda (bir kereye mahsus):

cp docker-compose.server.example.yml docker-compose.server.yml

.env (sunucuda, Git'e girmez):

IQV_FRONTEND_PORT=8082
IQV_BACKEND_PORT=3002
IQV_BIND_HOST=127.0.0.1
VITE_API_BASE_URL=https://dictionary.example.com

IQV_BIND_HOST=127.0.0.1 container portlarını yalnızca loopback'e yayınlar — servisler doğrudan internete açılmaz, Caddy onlara iqv_proxy networkü üzerinden container adıyla ulaşır. docker-compose.server.example.yml içinde !override ile portları tamamen değiştiren alternatif de yorum satırı olarak verilmiştir.

Installation

install.ps1/install.sh, -Mode/--mode parametresiyle çalışma modunu seçer:

.\scripts\windows\install.ps1 -Mode auto     # varsayılan: Docker varsa Docker, yoksa native
.\scripts\windows\install.ps1 -Mode docker   # Docker'ı zorla
.\scripts\windows\install.ps1 -Mode native   # Native'i zorla (Docker'sız)

./scripts/linux/install.sh --mode auto
./scripts/linux/install.sh --mode docker
./scripts/linux/install.sh --mode native

auto modunda script Docker'ın gerçekten çalışır durumda olup olmadığını kontrol eder (docker info + docker compose version) ve kararını her zaman loglar:

[INFO] Docker detected.
[INFO] Installation mode: docker

Script'ler idempotenttir — ikinci kez çalıştırmak var olan .env dosyalarını, container'ları veya PM2 process'lerini bozmaz, yalnızca gerekeni günceller.

Docker Installation

docker-compose.prod.yml (repo kökü) gerçek production imajlarını kullanır: backend/Dockerfile.prod (derlenmiş dist/, node dist/server.js — asla npm run dev) ve dashboard/Dockerfile.prod (derlenmiş statik dist/, nginx ile servis edilir — asla Vite dev server). Bu, mevcut docker-compose.yml (bind-mount + hot-reload geliştirme ortamı, docker compose up -d) ile karışmaz; o dosya hiç değiştirilmedi ve olduğu gibi çalışmaya devam ediyor.

Portlar ve frontend'in build-time API adresi kök .env dosyasından okunur (yoksa .env.example'dan otomatik oluşturulur): IQV_BACKEND_PORT (varsayılan 3001), IQV_FRONTEND_PORT (varsayılan 8080), VITE_API_BASE_URL.

Native Installation

Docker olmadan: backend npm ci && npm run build ile derlenir, dashboard pnpm install --frozen-lockfile && pnpm run build ile derlenir, ikisi de PM2 (scripts/common/ecosystem.config.js) altında çalıştırılır — backend derlenmiş dist/server.js'i, frontend ise bağımlılıksız bir statik dosya sunucusunu (scripts/common/static-server.mjs, SPA fallback'li — Docker imajındaki nginx'in native karşılığı) servis eder.

Terminal kapatılsa/bilgisayar yeniden başlasa bile IQV Dictionary otomatik ayağa kalkar:

• Windows — pm2-windows-startup (admin gerektirmez, oturum açılışında PM2'nin kayıtlı process listesini geri yükler).
• Linux — pm2 startup systemd (systemd birimi üretir; parolasız sudo varsa otomatik kurulur, yoksa çalıştırılacak komut ekrana basılır).

Update

Production sunucusunda güncelleme tek komuttur — başka manuel git/Docker işlemi gerekmez:

cd /opt/iqv/apps/iqv-dictionary
bash ./scripts/linux/update.sh --branch main

.\scripts\windows\update.ps1 -Branch main

--branch/-Branch verilmezse mevcut branch güncellenir.

Akış: repo kökünü doğrular → kurulu modu (Docker/native) .iqv-install/state.json'dan tespit eder → .env, backend/.env ve docker-compose.server.yml dosyalarını korur ve yedekler → tracked kaynak dosyalarında yerel değişiklik varsa güvenli şekilde durur → git fetch + hedef branch doğrulaması + fast-forward-only git pull → değişen dosyalara göre yalnızca gerekeni yeniden derler/başlatır → varsa docker-compose.server.yml override'ını otomatik uygular → healthcheck → commit/sürüm geçişini raporlar:

IQV Dictionary
Current version : 1.1.0
Target version  : 1.2.0
...
[OK] IQV Dictionary updated successfully.
Version: 1.2.0

Güvenlik garantileri:

• Tracked kaynak dosyalarında yerel değişiklik varsa update iptal edilir ve hangi dosyaların kirli olduğu listelenir.
• Untracked/gitignored sunucu configuration'ı (.env, backend/.env, docker-compose.server.yml) update'i engellemez — dirty kontrolü git status --porcelain --untracked-files=no ile yalnızca tracked kaynağa bakar.
• .env ve backend/.env asla overwrite/silme/.env.example ile değiştirme işlemine tabi tutulmaz; update öncesi .iqv-install/backups/<zaman-damgası>/ altına yedeklenir. Yeni .env.example anahtarları geldiyse yalnızca eksik anahtar ADLARI uyarı olarak yazdırılır, değerler hiç okunmaz/basılmaz.
• git reset --hard, git clean -fd, git checkout ., git merge ve git rebase script'lerin hiçbirinde kullanılmaz; standart git pull --ff-only'dır.
• Build başarısız olursa çalışan container'lar kaldırılmaz; mevcut sürüm hizmet vermeye devam eder.

Ayrıntılar için docs/deployment/installation.md.

Uninstall

.\scripts\windows\uninstall.ps1                      # servisleri/container'ları durdur, kaynak kodu KORU
.\scripts\windows\uninstall.ps1 -Purge                # + node_modules/dist/imajlar/.env dosyaları
.\scripts\windows\uninstall.ps1 -Purge -RemoveSource   # + TÜM repository (ekstra onay ister)

./scripts/linux/uninstall.sh
./scripts/linux/uninstall.sh --purge
./scripts/linux/uninstall.sh --purge --remove-source

MongoDB bu kurulum tarafından hiçbir zaman yönetilmez/silinmez — zaten bir DB container'ı/volume'u oluşturulmaz. -PurgeData/ --purge-data bunu açıkça loglar (üretim veritabanına dokunulmadığını teyit eden bir no-op'tur).

Version Management

Tek kaynak-doğrusu repo kökündeki VERSION dosyasıdır (düz metin, örn. 1.1.0). backend/package.json ve dashboard/package.json'daki version alanları her alt projenin kendi bağımsız modül sürümüdür ve değiştirilmedi — install/update script'leri "Current version"/"Target version" için yalnızca VERSION'ı okur.

Environment Variables

Dosya	Kim oluşturur	İçerik
backend/.env	Yoksa install script'i .env.example'dan, rastgele üretilmiş bir JWT_SECRET ile oluşturur	PORT, MONGODB_URI, MONGODB_DB, JWT_SECRET, CORS_ORIGIN, ...
dashboard/.env	Yoksa install script'i .env.example'dan oluşturur	VITE_API_BASE_URL
.env (repo kökü)	Yoksa install script'i .env.example'dan oluşturur — yalnızca Docker modunda kullanılır	IQV_BACKEND_PORT, IQV_FRONTEND_PORT, IQV_BIND_HOST, VITE_API_BASE_URL
docker-compose.server.yml	Elle (opsiyonel): cp docker-compose.server.example.yml docker-compose.server.yml	Sunucuya özel Docker override'ı — external network vb. Secret içermez.

Gerçek secret'lar hiçbir zaman .env.example dosyalarına yazılmaz; sadece değişken ADLARI belgelenir (bkz. her dosyanın kendisi). Var olan bir .env/backend/.env install veya update tarafından hiçbir zaman overwrite edilmez.

Docker'da host MongoDB: container içinde 127.0.0.1 container'ın kendisidir. Host makinedeki MongoDB'ye bağlanmak için backend/.env içinde şu biçimi kullanın (gerçek credential yalnızca sunucuda, repository'de değil):

MONGODB_URI=mongodb://<user>:<password>@host.docker.internal:27017/<db>?authSource=<auth-db>

Health Check

Install/update, yalnızca process ayakta diye başarı saymaz — gerçek HTTP healthcheck yapar:

[CHECK] Backend ........ OK
[CHECK] Frontend ....... OK
[CHECK] Docker ......... OK
[CHECK] Health .......... OK
IQV Dictionary installation completed successfully.

Backend: GET /health (backend/src/app.ts, {"success":true,"data":{"status":"ok"}}). Frontend: kök / üzerinden HTTP 2xx/3xx doğrulaması.

API Documentation

Swagger UI (standart, native görünüm; gruplama betiği yalnızca TOTAL/INTERNAL/EXTERNAL/SYSTEM üst başlıklarını toplar, gerçek operasyon listesini/renklerini değiştirmez), backend tarafından (swagger-ui-express) servis edilir. Geliştirmede erişim, önceki gibi Vite dev sunucusu (5173) üzerinden aynı origin'de kalır — Vite bu isteği sunucu tarafında gerçek backend'e iletir:

http://localhost:5173/api-docs

Ağdaki başka bir cihazdan (Vite zaten 0.0.0.0 üzerinde dinliyor):

http://<host-ip>:5173/api-docs

Production'da frontend (nginx, statik dosya sunucusu) API trafiğini proxy'lemez — mevcut, değişmemiş davranış gereği tarayıcı zaten VITE_API_BASE_URL üzerinden doğrudan backend'e gider (bkz. "Environment Variables"); Swagger de aynı şekilde backend'in kendi portundan (varsayılan 3001, bkz. IQV_BACKEND_PORT) doğrudan erişilir: http://<host>:3001/api-docs.

Tek kaynak-doğrusu OpenAPI 3.0.3 dosyası: backend/docs/openapi.yaml (gerçek backend route/controller/validation kodundan çıkarılmıştır; her operasyon x-iqv-classification — INTERNAL/EXTERNAL/SYSTEM — ve x-iqv-domain uzantı alanlarıyla etiketlenmiştir). Ham JSON hâli her zaman GET /openapi.json'dan (aynı origin üzerinden, ör. http://localhost:5173/openapi.json) gerçek JSON olarak döner — hiçbir zaman HTML değildir. "Try it out" istekleri, mevcut Vite dev proxy'si üzerinden gerçek backend'e gider — IP/port hiçbir yerde hardcode edilmemiştir.

CI/CD

Proje GitHub Actions kullanır, iki ayrı workflow ile: IQV Dictionary CI (uygulama kodu) ve IQV Dictionary Docs (dokümantasyon) — bkz. .github/workflows/ci.yml / docs.yml.

IQV Dictionary CI, her push/pull_request'te (main) şu gerçek aşamaları çalıştırır:

Aşama	Ne yapar
Frontend	dashboard/: typecheck → lint → prettier → test → coverage → build
Backend	backend/: typecheck → lint → prettier → test → coverage → build → /health duman testi
k6 Smoke	Backend'den sonra, in-memory test sunucusuna karşı kısa performans testleri
Docker Build	Dev + production imajlarının build'i, docker compose config doğrulaması (registry'ye push yok)
Scripts Lint	scripts/linux/*.sh (bash -n) ve scripts/windows/*.ps1/*.psm1 (gerçek PowerShell parser) syntax denetimi
Quality Pipeline	Yukarıdaki aşamaların sonuçlarını toplayıp kalite raporu üretir (aşağıya bakın)

k6 load/stress testleri her push'ta ÇALIŞMAZ — yalnızca manuel workflow_dispatch ile tetiklenir.

Quality Pipeline: gerçek aşama sonuçlarından 100 puanlık bir rapor üretir (Backend 30, Dashboard 30, Docker 15, k6 Smoke 15, Scripts 10) — REPORT.md, REPORT.json, QUALITY.svg. Bu çıktılar hem çalışan run'ın GitHub Actions Job Summary bölümüne (REPORT.md) eklenir, hem de iqv-dictionary-quality-report adıyla opsiyonel bir artifact olarak yüklenir (1 gün saklama, yükleme kota nedeniyle başarısız olsa bile sonuç etkilenmez). Skor yalnızca raporlama içindir — zorunlu bir aşama gerçekten FAIL/iptal olduğunda sonuç her zaman FAILEDdir (strict gate, skorla yumuşatılmaz).

Ayrıntı için bkz. docs/development/git-ci.md (yayınlanmış dokümantasyon sitesinde "Git ve CI" sayfası).

Documentation

Bu README, projeyi kurmak/güncellemek/kaldırmak için operasyonel bir özet sunar. Mimari, Backend API, Frontend, test stratejisi ve CI/CD'nin ayrıntılı, Türkçe/İngilizce dokümantasyonu MkDocs (Material) ile üretilir ve GitHub Pages'te yayınlanır:

https://iqvizyon-development.github.io/iqv-dictionary/

Yerelde çalıştırmak için:

pip install -r requirements-docs.txt
mkdocs serve

Kaynak: docs/ (yapı: mkdocs.yml). Dokümantasyon sitesi her main push'unda otomatik yeniden yayınlanır (IQV Dictionary Docs workflow'u).

Troubleshooting

• Docker/Docker Compose not available, but -Mode docker was requested — Docker Desktop/Engine kurulu ve ÇALIŞIYOR olmalı (docker info başarılı dönmeli).
• Local modifications detected... Update aborted — git status --short ile değişiklikleri görün, commit/stash edin, tekrar deneyin.
• Backend healthcheck FAIL — backend/.env'deki MONGODB_URI'nin gerçekten erişilebilir bir MongoDB'ye işaret ettiğinden emin olun (Docker modunda bu, host'un host.docker.internal'da dinlediği anlamına gelir).
• Loglar — Docker: docker compose -f docker-compose.prod.yml logs -f. Native: pm2 logs.
• Daha fazlası için docs/deployment/installation.md.

Developer Mode

Mevcut geliştirici deneyimi hiç değişmedi — backend ve frontend hâlâ ayrı paket yöneticileriyle (backend: npm, dashboard: pnpm), ayrı dev script'leriyle çalışır:

cd backend  && npm ci   && npm run dev     # http://localhost:3001
cd dashboard && pnpm install --frozen-lockfile && pnpm run dev   # http://localhost:5173

Önemli: Frontend (Vite, 5173) /api, /api-docs, /openapi.json ve /health isteklerini backend'e (3001) proxy'ler — backend çalışmıyorsa bu istekler ECONNREFUSED verir. Sadece dashboard> npm run dev çalıştırıp backend> npm run dev'i unutmak bunun en sık nedenidir.

Bu iki komutu iki ayrı terminalde unutmadan çalıştırmak yerine, repo kökünden tek komutla ikisini birlikte başlatabilirsiniz (yeni bir bağımlılık eklemez, sadece mevcut backend/dashboard dev script'lerini birlikte çalıştırır — bkz. scripts/common/dev.js):

npm run dev   # backend (3001) + frontend (5173) aynı anda, Ctrl+C ikisini de kapatır

veya Docker ile hot-reload (bind-mount, dosya kaydettiğinizde anında yansır):

docker compose up -d

Production Mode

Yukarıdaki Quick Start / Installation bölümlerine bakın — production'da hiçbir zaman npm run dev/pnpm run dev çalıştırılmaz; her zaman derlenmiş bir build (node dist/server.js, statik dashboard/dist) servis edilir.

Directory Structure

Dictionary/
├── backend/                 # Express + MongoDB API
│   ├── Dockerfile            # geliştirme (hot reload, docker-compose.yml)
│   ├── Dockerfile.prod        # PRODUCTION (docker-compose.prod.yml)
│   └── src/
├── dashboard/                # React + Ant Design frontend
│   ├── Dockerfile            # geliştirme (hot reload, docker-compose.yml)
│   ├── Dockerfile.prod        # PRODUCTION (docker-compose.prod.yml)
│   ├── nginx.conf             # yalnızca Dockerfile.prod kullanır
│   └── src/
├── scripts/
│   ├── windows/               # install.ps1 / update.ps1 / uninstall.ps1 / lib.psm1
│   ├── linux/                 # install.sh / update.sh / uninstall.sh / lib.sh
│   │   └── tests/             # deployment/update güvenlik testleri (Docker'sız)
│   └── common/                # ecosystem.config.js (PM2), static-server.mjs, compose.mjs
├── docs/                     # MkDocs kaynağı (`mkdocs serve`)
├── docker-compose.yml         # geliştirme (bind-mount, hot reload) — DEĞİŞMEDİ
├── docker-compose.prod.yml    # PRODUCTION, GENERIC (bu README'nin kurduğu sistem)
├── docker-compose.server.example.yml  # opsiyonel sunucu override ŞABLONU (tracked)
│                             # → sunucuda: docker-compose.server.yml (gitignored)
├── VERSION                   # tek sürüm kaynak-doğrusu (bkz. Version Management)
├── .env.example               # yalnızca docker-compose.prod.yml için (port/bind/build-arg)
└── package.json               # kök: yalnızca `npm run docker:*` kısayolları — kurulum mantığı scripts/ altında

Feedback

Sorunlar/öneriler için thumbs-down veya proje deposu üzerinden geri bildirim verin.