Mobildev Docs Sistemi
Mobildev Docs; Mobildev ürünleri, servisleri, API'leri, süreçleri ve kurumsal bilgi alanları için merkezi dokümantasyon platformudur. Platformun görünen yüzü Docusaurus ile üretilen hızlı ve SEO uyumlu statik sitedir. Bununla birlikte sistem, yalnızca Markdown dosyalarının yayınlandığı bir web sitesi değildir. İçerik yönetimi, onay, yetkilendirme, güvenli yayın, kullanıcı geri bildirimi, kullanım ölçümü ve doküman odaklı yapay zekâ asistanı özellikleriyle gelişen bir bilgi platformudur.
Sistemin temel amacı; müşterilerin, iş ortaklarının ve Mobildev ekiplerinin doğru bilgiye tek bir yerden, tutarlı bir deneyimle erişmesini sağlamaktır. Teknik dokümanların yanında sıkça sorulan sorular, ürün terimleri, mevzuat, rehberler, Hub içerikleri ve güncelleme yazıları da aynı çatı altında yer alır.
Sistemin temel yaklaşımı
Mobildev Docs iki katmanlı çalışır:
- Yayın katmanı: Docusaurus ve React ile oluşturulan, ziyaretçiye sunulan statik dokümantasyon sitesi.
- Yönetim katmanı: Node.js ve Express ile çalışan; içerik, kullanıcı, rol, onay, yayın ve analitik işlemlerini yöneten yerel API servisi.
Bu ayrım, statik sitenin hızını ve erişilebilirliğini korurken içerik yaşam döngüsünü yönetilebilir hâle getirir. Dokümanlar ağırlıklı olarak Markdown veya MDX olarak saklanır; etkileşimli dizinler, aramalar ve yönetim ekranları React bileşenleriyle sağlanır.
Kullanıcıya sunulan bilgi alanları
Ana navigasyon, dokümanları kullanım amacına göre ayırır. Ürün desteği altında SMS Marketing Suite, Cookie Management, İVT, İVT Lite, Access, Insightive (Anket), MDQ, Acil.Care, GİP, Wentro Verify, OTP SMS, Toplu SMS, SMS Inbox ve Infomize gibi çözüm alanları bulunur. Her ürün kendi giriş sayfasına ve gerektiğinde kendi sidebar yapısına sahiptir.
Platformdaki ana bilgi alanları şunlardır:
| Alan | Amacı | Kaynak/yapı |
|---|---|---|
| Çözümler | Ürün veya çözüm bazlı kullanım, teknik ve destek dokümanları | docs/solution/data/ |
| SSS | Genel, popüler ve çözüm bazlı sorular | docs/faq/ ve çözüm SSS içerikleri |
| Sözlük | Ürün ve teknik terimlerin tanımı, ürün bağlamı ve araması | docs/glossary/ |
| Mevzuat | Mevzuat grupları ve ilgili dokümanlar | docs/regulation/ |
| Rehber | Konu veya ürün gruplarına ayrılmış rehber içerikler | docs/guide/ |
| API | API katalogları, açıklama dokümanları ve OpenAPI referansları | docs/apis/, openapi/ |
| Hub | Kategorilere ayrılan ortak bilgi ve kaynak merkezi | docs/hub/ |
| +Docs | Süreç, bilgi, Open API ve güncelleme gibi ek alanlar | docs/extra/, blog/ |
| Yönetim | Yetkili kullanıcılar için içerik, rol, yayın ve istatistik ekranları | docs/admin/ |
Bu ayrım, bir bilginin nerede bulunması gerektiğini açıklaştırır. Örneğin bir ürünün nasıl kullanıldığı çözüm dokümanında, terimin anlamı sözlükte, resmi bir gereklilik mevzuatta, uç noktanın teknik sözleşmesi ise API alanında tutulur.
Docusaurus yayın mimarisi
Yayın sitesi Docusaurus 3, React ve MDX üzerine kuruludur. Docusaurus; Markdown/MDX kaynaklarını sayfalara dönüştürür, sol doküman gezintisini oluşturur, sayfa içi başlık dizinini üretir ve statik HTML/CSS/JavaScript çıktısı sağlar. Üretim adresi docs.mobildev.com olarak yapılandırılmıştır.
sidebars.js, alanların doküman hiyerarşisini tanımlar. SSS, sözlük, mevzuat, rehber, API ve Hub alanları için ayrı sidebar'lar bulunur. Çözüm alanlarında ise ürün dizininden otomatik oluşturulan sidebar'lar kullanılır. Bu sayede ürün içerikleri kendi bağlamında gezilebilir; aynı zamanda merkezi alanlar kendi bilgi mimarisini korur.
Özel tema bileşenleri Docusaurus'un varsayılan görünümünü genişletir. Bunlar arasında yeniden boyutlandırılabilir sol sidebar, breadcrumb ana sayfa bağlantısı, özel navbar, doküman altı bileşenleri, mobil TOC davranışı ve yönetim ekranı koruması yer alır. Karanlık tema ve mobil ekranlar, Docusaurus yapısıyla uyumlu şekilde desteklenir.
MDX ile zengin içerik
MDX, Markdown okunabilirliğini React bileşenlerinin gücüyle birleştirir. Bir içerik yazarı metin, tablo, kod örneği ve görsel kullanırken; gerekli sayfalarda grup listeleri, son güncellenen dokümanlar, ürün içindekiler listesi veya etkileşimli bileşenler de eklenebilir.
Dokümanların üst bilgisinde bulunan front matter alanları, başlık, sidebar sırası, açıklama, içerik türü ve sayfa davranışını tanımlar. Çözüm alanında solution_node_type; rehber, mevzuat, API ve Hub alanlarında ise kendi içerik türünü ifade eden metadata kullanılır. Bu metadata, hem Docusaurus gezinmesini hem de yönetim panelinin dokümanı doğru türde değerlendirmesini sağlar.
İçerik üretim ve indeksleme zinciri
Site başlatılmadan ve build alınmadan önce bir dizi senkronizasyon betiği çalışır. Bu betikler kaynak dosyalardan türetilmiş indeksleri oluşturur ve güncel tutar. Örnekler:
- çözüm veri rotalarının ve kaynak kartlarının senkronize edilmesi,
- sözlük indeksinin üretilmesi,
- çözüm bazlı SSS indeksinin hazırlanması,
- mevzuat, rehber, API ve Hub giriş sayfalarının oluşturulması,
- API kataloglarının OpenAPI tanımlarından eşitlenmesi,
- chatbot bilgi indekslerinin hazırlanmasıdır.
Bu yaklaşımda kaynak içerik ile türetilen veri ayrıdır. Editörün değiştirdiği MDX kaynakları asıl bilgidir; listeleme, arama veya asistan için oluşturulan JSON dosyaları kaynak değildir ve elle düzenlenmemelidir. Böylece kullanıcı arayüzü büyük miktarda içerik içinde hızlı listeleme yapabilir, içerik ise okunabilir dosya biçiminde korunur.
Çözüm dokümanlarının yapısı
Bir çözüm, docs/solution/data/<çözüm-kimliği>/ altında yer alır. Çözüm giriş belgesi ürünün kapısıdır; tekil sayfalar, gruplar, grup altı sayfaları ve SSS yapısı bu dizin altında konumlanabilir. Sistem aşağıdaki türleri ayırt eder:
- çözüm giriş dokümanı,
- normal sayfa dokümanı,
- grup dokümanı,
- SSS grubu,
- grup altı sayfası,
- çözüme bağlamlı sözlük, mevzuat, rehber veya API içeriği.
Bu model, bir ürünün düz bir sayfa listesi olmaktan çıkıp konu gruplarıyla düzenlenen bilgi alanına dönüşmesini sağlar. Özel bilgi bankası türleri ürün sidebar'ında “Bilgi Bankası” altında gruplanabilir.
Sözlük ve bağlamsal terimler
Sözlük terimleri, yayınlanan terimler için merkezi bir indeks üzerinden çalışır. Terim kaynakları doğrudan normal Docusaurus dokümanı olarak yayınlanmaz; bunun yerine sistem her onaylı terim için kanonik /glossary/term/<terim-id> rotasını üretir. Bu yöntem, terimleri standart doküman listelerinden bağımsız yönetmeyi ve yayın kuralını merkezileştirmeyi sağlar.
Terim bir ürün veya etiketle ilişkilendirildiğinde, aynı terim çözüm bağlamında da açılabilir. Böylece ziyaretçi örneğin bir ürünün sözlüğünden açtığı terimde ürün sidebar'ını ve ilgili bağlamı kaybetmez. Ayrıca bir remark eklentisi, yayınlanmış sözlük terimlerini uygun metin alanlarında tooltip bileşenine dönüştürebilir. Kod blokları, bağlantılar, başlıklar ve mevcut tooltip'ler bu otomatik dönüşümün dışında tutulur.
API ve OpenAPI yapısı
API dokümantasyonunda OpenAPI standardı kullanılır. openapi/ dizinindeki YAML tanımları, OpenAPI Docusaurus eklentisiyle doküman rotalarına dönüştürülür. SMS ve Edvantage örnekleri bu mekanizmayı kullanır. Böylece endpoint, parametre, istek şeması, yanıt şeması ve durum kodları tanımdan türetilir; teknik referans ile API sözleşmesi arasındaki uyumsuzluk riski azalır.
Merkezi API alanı, OpenAPI referanslarının yanında katalog/grup/folder düzenindeki açıklayıcı API içeriklerini de barındırabilir. Bu iki katman birbirini tamamlar: OpenAPI makinenin ve geliştiricinin kesin sözleşmesini, MDX sayfaları ise entegrasyon bağlamını, kullanım notlarını ve açıklayıcı rehberleri sunar.
Yönetim paneli ve içerik yaşam döngüsü
Yönetim paneli, Docusaurus sayfaları içinde çalışan React ekranlarından oluşur; işlemler Express API'ye yapılır. İçeriklerin yönetildiği başlıca alanlar şunlardır:
- çözümler, çözüm kategorileri, grup başlıkları ve grup konuları,
- sözlük terimleri ve toplu içe aktarma,
- mevzuat, rehber, API ve Hub grupları ile dokümanları,
- içerik onayları ve bekleyen yayınlar,
- kullanıcılar, roller ve izinler,
- geri bildirimler, görüntüleme ve arama istatistikleri.
İçerik yaşam döngüsü, doğrudan canlı site dosyasını değiştirmek yerine kontrollü ilerler:
- Editör yeni içerik oluşturur veya mevcut içeriği günceller. Değişiklik taslak/onay bekleyen sürüm olarak değerlendirilir.
- İlgili onay yetkisine sahip kullanıcı içeriği inceler ve onaylar.
- Yetkili kullanıcı yayın işlemini başlatır.
- Sistem onaylı içeriklerin yayın anlık görüntüsünü hazırlar, Docusaurus build'ini staging dizininde üretir ve çıktıyı doğrular.
- Başarılı build, canlı
build/dizinine terfi ettirilir; başarısız build canlı sitenin yerini almaz. - Yayınlanmış sürümlerin hash, zaman ve işlemi yapan kullanıcı bilgisi kayıt altına alınır; taslaklar uygun şekilde temizlenir veya korunur.
İçerik hash'i kullanılması önemlidir: dosya adı aynı kalsa bile içerik değiştiğinde yeni sürüm oluşur. Böylece onay yalnızca belirli bir dosya adına değil, incelenmiş içerik sürümüne bağlıdır. Arşivleme ise içerik dosyasını geri döndürülemez biçimde silmek yerine yayın görünürlüğünden çıkarma yaklaşımıyla ele alınır.
Backend, kimlik doğrulama ve yetkiler
Yönetim API'si server/ altında Node.js ve Express 5 ile çalışır. Servis varsayılan olarak yalnızca yerel adres üzerinde dinler; geliştirmede Docusaurus sunucusu ilgili /api/ isteklerini API servisine yönlendirir. IIS yayınında aynı yönlendirme URL Rewrite ve ARR ile yapılabilir.
API'nin katmanları route, controller, service, middleware ve database yapısıyla ayrılmıştır. Route katmanı HTTP yolunu ve gerekli izni tanımlar; controller isteği karşılar; service katmanı dosya, workflow ve iş kurallarını uygular. Bu yapı, içerik türlerinin aynı güvenlik ve yayın ilkeleriyle yönetilmesini kolaylaştırır.
Kullanıcı, rol, izin, oturum, denetim kaydı, geri bildirim, görüntüleme, arama ve AI asistanı geri bildirimleri SQLite veritabanında tutulur. Varsayılan veritabanı konumu server/data/docsdb/docsdb.sqlite'dır. Veritabanı WAL kipinde çalıştığından yedekleme veya taşıma sırasında ana .sqlite dosyasıyla birlikte -wal ve -shm dosyaları da dikkate alınmalıdır. Şema değişiklikleri sıralı migration dosyalarıyla uygulanır.
Parolalar düz metin saklanmaz; scrypt ile türetilmiş özet kullanılır. Oturum belirteci tarayıcıya HTTP-only ve SameSite korumalı çerez olarak verilir; veritabanında ham belirteç yerine SHA-256 özeti tutulur. Yönetim uç noktaları önce oturum doğrulamasından, ardından işlem bazlı izin denetiminden geçer. Roller; çözüm, sözlük, mevzuat, API, rehber, Hub, kullanıcı, rol ve onay alanları için ayrı okuma, oluşturma, güncelleme, onaylama veya arşivleme izinleri taşıyabilir.
Eski bazı içeriklerde bulunan parola kontrolü, istemci taraflı kolaylık kontrolüdür. Statik dosya yayımlandığı için bu mekanizma gizli dokümanlar için gerçek yetkilendirme sayılmaz. Gerçek erişim kısıtı gerektiğinde içerik, API ve sunucu katmanında uygulanmalıdır.
Geri bildirim, analitik ve kalite döngüsü
Doküman sayfalarının altında, uygun sayfalarda yararlılık oylaması ve geri bildirim formu bulunur. Kullanıcı oturum açtıysa bir doküman için “Evet/Hayır” değerlendirmesi yapabilir; soru, yorum veya kontrol listesi destek talebi gönderebilir. Yönetim tarafında bu veriler incelenebilir.
Ziyaretçi izni bulunan istemcilerde doküman görüntüleme, site ziyareti ve arama olayları API'ye iletilir. Yönetim istatistikleri bu veriler üzerinden hangi dokümanların kullanıldığını, hangi aramaların sonuç ürettiğini ve hangi konularda iyileştirme gerektiğini görünür kılmayı hedefler. Analitik çağrıları, dokümanın görüntülenmesini engellemeyecek şekilde ikincil davranış olarak tasarlanmıştır.
Bu döngü şu soruların yanıtlanmasına yardım eder:
- Kullanıcılar hangi içeriklere en sık erişiyor?
- Hangi aramalar sonuçsuz kalıyor veya tekrar ediliyor?
- Hangi dokümanlar yararlı bulunmuyor?
- Hangi sorular geri bildirim yoluyla tekrar tekrar geliyor?
Bu bilgiler; yeni SSS, rehber, sözlük terimi veya içerik revizyonu için somut girdi oluşturur.
AI Doküman Asistanı
AI Doküman Asistanı, sayfa üzerinde açılıp kapanabilen ve genişliği ayarlanabilen bir panel olarak çalışır. Asistanın amacı genel amaçlı sohbet etmek değil, Mobildev dokümanları hakkında destek sağlamaktır. Sayfa bağlamı ve kullanıcının sorusundaki Türkçe terimler dikkate alınarak ilgili kaynaklar seçilir; yanıtın kaynak dışına çıkmaması istenir.
Build öncesinde sözlük, SSS, rehber ve mevzuat kaynaklarından chatbot indeksleri oluşturulur. Bu indeksler başlık, kısaltılmış içerik, etiket, bağlam ve bağlantı bilgisini içerir. İstemci tarafındaki seçim mekanizması; soru terimlerini, tanım sorularını ve açık olan sayfanın ürün/grup bağlamını puanlayarak sınırlı sayıda ilgili dokümanı modele gönderir. Asistan yanıtında kullanıcıya ilgili sayfalara bağlantı sunabilir.
Asistan iki sağlayıcı yolunu destekleyecek şekilde hazırlanmıştır:
- geliştirme ortamında yerel sohbet sağlayıcısına yönlendirme,
- backend üzerinden OpenRouter uyumlu sohbet tamamlama servisi.
Backend, sağlayıcı anahtarını yalnızca sunucudaki ortam değişkeninden okur; anahtar tarayıcı koduna gönderilmez. İsteklerde mesaj sayısı, rol, içerik boyutu ve üretim token sınırı denetlenir. Akış destekleyen sağlayıcılardan gelen SSE çıktısı istemciye iletilebilir. Dokümanda yeterli bilgi yoksa asistanın tahmin etmek yerine bunu açıkça belirtmesi beklenir.
Mevcut yaklaşım, anahtar kelime ve bağlam puanlamasına dayalı hafif bir retrieval düzenidir. Uzun vadede embedding, vektör veritabanı ve kullanıcı yetkilerini dikkate alan RAG katmanı eklenebilir. Bu geçişte kritik ilke değişmez: model, kullanıcının erişmeye yetkili olduğu kaynaklardan seçilen içerik üzerinden cevap üretmelidir.
Yayın, dağıtım ve işletim
Normal geliştirme akışı npm start ile başlar. Bu komuttan önce gerekli içerik senkronizasyonları çalışır. Üretim çıktısı npm run build ile alınır ve Docusaurus statik siteyi build/ dizininde üretir. IIS ile yayın senaryosunda yayın kökü doğrudan bu build klasörüdür; web.config yayın çıktısına kopyalanır ve API yönlendirmesi yerel Express servisine yapılır.
Yönetim panelinden yapılan yayın ise kesintiyi azaltmak için farklı ilerler. Build önce staging klasöründe üretilir. index.html doğrulandıktan sonra mevcut canlı build önceki sürüm olarak saklanır ve staging çıktısı canlı konuma taşınır. Geçişte sorun yaşanırsa önceki çıktı geri yüklenir. Bu nedenle yönetim panelindeki yayın işlemi, doğrudan canlı build klasöründe derleme yapmaktan daha güvenli bir işletim yoludur.
Sunucuya ait kalıcı veri klasörleri — özellikle veritabanı, workflow kayıtları ve yayın durumu — kaynak kod deposundan ayrı korunmalıdır. Ortam değişkenleri ile API anahtarları, çerez güvenlik ayarları ve servis adresleri yapılandırılır; bu değerler kaynak koda veya istemci paketine eklenmez.
Geliştirme ilkeleri
Mobildev Docs geliştirilirken aşağıdaki ilkeler korunur:
- Varsayılan geliştirme dili JavaScript'tir; yeni uygulama kodunda gereksiz TypeScript kullanımı tercih edilmez.
- İçerik mümkün olduğunca Markdown ve MDX'te, uygulama mantığı React/Node.js katmanlarında tutulur.
- Türkçe arama ve sıralamada Türkçe locale kuralları kullanılır.
- Mevcut URL'ler ve doküman bağlantıları korunur; slug değişiklikleri kırık bağlantı riski değerlendirilerek yapılır.
- Yeni paket yalnızca mevcut yapı yetersizse eklenir.
- API anahtarı, parola, gizli anahtar ve benzeri hassas bilgiler kaynak koduna yazılmaz.
- Yetki denetimi yalnızca menü gizleme ile yapılmaz; backend uç noktalarında da uygulanır.
- Doküman deneyimi; mobil uyumluluk, klavye kullanımı, semantik HTML, kontrast ve odak görünürlüğü gözetilerek geliştirilir.
Gelecek yönü
Platformun doğal gelişim yönü, Docusaurus merkezli yayın gücünü korurken yönetim ve kişiselleştirme kabiliyetlerini artırmaktır. Hedef mimari; daha ayrıntılı rol tabanlı doküman görünürlüğü, PostgreSQL'e taşınabilir veri modeli, zengin arama, gelişmiş denetim kaydı, içerik kalitesi raporları, vektör tabanlı RAG ve MCP entegrasyonu gibi yetenekleri destekleyecek biçimde tasarlanmalıdır.
Bu nedenle Mobildev Docs'a yapılan her geliştirme iki soruya cevap vermelidir: Ziyaretçinin doğru bilgiye daha kolay ulaşmasını sağlıyor mu? Ve bu geliştirme, güvenli ve yönetilebilir kurumsal bilgi platformu hedefiyle uyumlu mu?
Bu doküman size yardımcı oldu mu?
Değerlendirmeniz, dokümanı geliştirmemize yardımcı olur.
Değerlendirme yapmak için giriş yapmalısınız.
Destek soruları ve yorumlar
Bu dokümanla ilgili soru sorabilir veya deneyiminizi paylaşabilirsiniz.