XTech Nexus CRM, birden fazla ülkede ofisi olan bir organizasyon için geliştirilmiş kurumsal bir CRM/ERP sistemi. Ön muhasebe, envanter ve personel yönetimi tek bir uygulamada birleşiyor. Proje özel bir müşteri çalışması olduğu için şirket adı ve ekran görüntüleri paylaşılmıyor. Bu sayfada sorunu, mimariyi ve verilen mühendislik kararlarını anlatıyorum.
İşin başlangıç noktası bir yazılım ihtiyacından çok bir görünürlük sorunuydu. Organizasyonda çok sayıda elektronik ekipman vardı ama hangi cihazın kimde olduğu bilinmiyordu. İki ülkede üç ofise dağılmış bir yapı bu takibi iyice zorlaştırıyordu. Bir cihaz kaybolduğunda ya da hasar gördüğünde ne kaybedildiği, kimin sorumluluğunda olduğu ve maliyetinin ne olduğu belirsiz kalıyordu.
Ürün Kapsamı
Sistem, birbirinden kopuk duran dört alanı tek bir veri modelinde topluyor:
- Ofisler ve organizasyon yapısı: Her ofis ayrı bir birim olarak tanımlı. Departmanlar, pozisyonlar ve hiyerarşi bu ofislerin altında yer alıyor.
- Envanter ve zimmet: Bütün ekipman merkez ofise bağlı ve dağıtımı merkez yapıyor. Cihazların ve lisansların seri numarası, satın alma tarihi ve fiyatı tek tek kayıtlı. Bir ekipmana bir şey olduğunda zararın tutarı belli.
- Ön muhasebe: Her ofisin kasası ayrı. Muhasebe işlemleri ofis bazında tutulduğu için her ofisin finansal durumu ayrı ayrı görülebiliyor.
- İnsan kaynakları: Departmanlar, departman yetkileri ve hiyerarşik yapıyla profesyonel bir İK yazılımı gibi çalışıyor. Maaş, izin, giriş-çıkış kaydı, onay zincirine bağlı avans/masraf talepleri ve puantaj sistemi bu bölümde.
Kullanıcıların en çok işine yarayan özellik personel puantaj sistemi oldu. Prim ve ceza bir puan sistemine göre işliyor ve personel kendi aldığı her prim ya da cezanın ayrıntısını görebiliyor.
Teknik Mimari
Backend: Go ve hexagonal mimari
Backend Go ve Gin ile yazıldı. Veri katmanında GORM ve PostgreSQL, kimlik doğrulamada JWT kullanılıyor. Kod hexagonal (Ports & Adapters) mimariye göre düzenlendi:
core/domain: Varlıklar ve iş kuralları. HTTP'den ve veritabanından habersiz.core/ports: Domain'in dış dünyadan beklediği arayüzler (repository ve servis sözleşmeleri).core/services: İş akışları, örneğin onay zinciri ilerletme, zimmet verme ya da puantaj işleme.adapters/handler: Gin HTTP handler'ları. İsteği alıp servis katmanına iletiyor.adapters/repository: GORM/PostgreSQL implementasyonları.
Bu ayrımın bir ERP'de somut bir faydası var. Muhasebe ve İK kuralları zamanla en çok değişen kısımlar ve bu kurallar web katmanına ya da ORM'e bağlı değil. Onay zinciri veya prim hesaplama mantığı değiştiğinde dokunulan yer domain ve servis katmanı oluyor. Handler'lar ile repository'ler aynı kalıyor.
Frontend: React 19 ve Mantine
Yönetim arayüzü React 19 ve Mantine UI ile, Vite üzerinde geliştirildi. Görevler kütüphanelere net biçimde dağıtıldı:
- TanStack React Query: Sunucu verisinin çekilmesi ve önbelleğe alınması.
- Zustand: İstemci tarafı state.
- React Hook Form + Zod: Form yönetimi ve şema tabanlı doğrulama. ERP'de form sayısı fazla, alanlar da kritik (seri numarası, tutar, para birimi). Doğrulama kurallarının şemalarda tanımlanması hatalı veri girişini kaynağında engelliyor.
Çok ofisli organizasyon modeli
İki ülke ve üç ofis veri modelinde ayrı bir istisna olarak ele alınmadı, hiyerarşinin parçası olarak modellendi:
Company (tüzel kişilik) → Branch (fiziksel ofis) → Department → Position
Tüzel kişilik ile fiziksel ofisin ayrı varlıklar olması, farklı ülkelerdeki yapıların aynı modelle temsil edilmesini sağlıyor. "Bu ofiste kim çalışıyor, kasasında ne var, kimin üzerinde hangi cihaz var" soruları aynı modelden yanıtlanıyor.
Davet tabanlı onboarding
Yeni personel sisteme token tabanlı bir davetle katılıyor. Davet bağlantısı 48 saat geçerli, süresi dolan bağlantı artık kullanılamıyor.
Mühendislik Kararı 1: Ürün Tanımı ile Fiziksel Varlığı Ayırmak
Sorun. "Kimde ne var" sorusunun yanıtı, envanterin nasıl modellendiğine bağlı. Envanter "MacBook Pro, adet: 50" şeklinde tutulursa elli cihazın her biri ayrı izlenemez. Hangisinin kimde olduğu, hangisinin ne zaman ve kaça alındığı, hangisinin kaybolduğu kayıtlarda görünmez. Sorunun kendisi de buydu.
Karar. Envanter iki ayrı varlık olarak modellendi:
ProductDefinition, ürünün tipini tanımlıyor: kategori (DEVICE,SIM_CARD,LICENSE,VEHICLE,FURNITURE), marka ve model.Asset, tekil fiziksel varlığı tutuyor: seri numarası (SIM kartlar için ICCID), barkod, satın alma tarihi, satın alma fiyatı ve para birimi. Durumu da kayıtlı:AVAILABLE,ASSIGNED,MAINTENANCE,SCRAPPED,LOST.
Zimmet de ayrı bir kayıt olarak tutuluyor. AssetAssignment, bir varlığın kime ve ne zaman verildiğini, ne zaman iade edildiğini ve zimmeti kimin yaptığını saklıyor. Varlığın üzerinde yalnızca "şu an kimde" bilgisi değil, bütün zimmet geçmişi duruyor.
Sonuç. Aynı modelden elli MacBook olsa bile her biri kendi seri numarası, alış tarihi ve fiyatıyla ayrı bir kayıt. Bir cihaz kaybolduğunda ya da hasar gördüğünde hangi cihaz olduğu, son kimde olduğu, kimin zimmetlediği ve satın alma maliyeti kayıtlardan okunuyor. Zarar tahminle değil, kayıtla belirleniyor. Lisanslar ve SIM kartlar da aynı modelle izlendiği için yazılım lisansları ve hatlar da envanterin parçası.
Mühendislik Kararı 2: Para Tutarlarını int64 Kuruş Olarak Saklamak
Sorun. Sistem birden fazla ülkede ve birden fazla para birimiyle çalışıyor. Her kasa (Account) nakit (CASH) ya da banka (BANK) tipinde ve kendi para biriminde (EUR, USD, TRY). Para tutarlarını kayan noktalı sayılarla saklamak bilinen bir hata kaynağı. 0.1 + 0.2 gibi işlemler tam sonuç vermez ve çok sayıda işlem toplandığında bakiye birkaç kuruş sapabilir. Muhasebede birkaç kuruşluk fark da açıklanması gereken bir tutarsızlıktır.
Karar. Bütün Transaction tutarları int64 olarak en küçük para biriminde (kuruş/cent) saklanıyor. Örneğin 125,50 EUR veritabanında 12550 olarak duruyor. Hesaplar tam sayı aritmetiğiyle yapılıyor, ondalık gösterim sadece görüntüleme aşamasında üretiliyor.
Sonuç. Yuvarlama hatası dikkatli kod yazılarak önlenmiyor, veri tipi buna izin vermiyor. Her kasa kendi para birimini taşıdığı için farklı para birimindeki tutarlar da sessizce birbirine karışmıyor. Ofis bazlı finansal tablonun güvenilir olmasının temeli bu.
Mühendislik Kararı 3: Onay Zincirini Durum Makinesi Olarak Modellemek
Sorun. Avans veya masraf talebi hiyerarşi boyunca ilerliyor. Personel talebi oluşturuyor. Ekip lideri onaylarsa talep departman müdürüne gidiyor, müdür onaylarsa finansa geçiyor, finans onaylarsa sonuç zincir boyunca geri dönüyor. Bu akış dağınık boolean alanlarla (isApprovedByManager, isApprovedByFinance gibi) kurulursa tutarsız durumlar oluşabilir. Örneğin müdür onayı olmadan finans onayı görünen bir talep ortaya çıkabilir.
Karar. ExpenseRequest açık bir durum makinesi olarak modellendi:
PENDING_DEPT → PENDING_COMPANY / PENDING_FINANCE → APPROVED → PAID
Talep herhangi bir aşamada REJECTED durumuna geçebiliyor. Geçiş kuralları domain katmanında tanımlı ve departman yetkileri ile hiyerarşik yapı bu noktada onay zincirine bağlanıyor.
Sonuç. Bir talep her an tek ve geçerli bir durumda. Aşama atlanamıyor ve "onaylandı" ile "ödendi" birbirinden ayrı durumlar. Zincirin kuralları hexagonal mimari sayesinde domain katmanında toplu durduğu için bir onay aşaması eklemek ya da sırayı değiştirmek tek bir yerde yapılan bir değişiklik.
Mühendislik Kararı 4: Puan ve Parasal Etkiyi Tek Kayıtta Tutmak
Sorun. Puantaj sisteminin amacı şeffaflıktı. Personelin aldığı primin ya da cezanın nedenini görebilmesi gerekiyordu. Puan bir tabloda, maaş kesintisi ya da prim başka bir tabloda tutulursa ikisi arasındaki bağ kopar ve "bu ay neden daha az aldım" sorusu cevapsız kalır.
Karar. Her performans olayı tek bir PerformanceRecord olarak tutuluyor. Kaydın tipi (REWARD, PENALTY, LEAVE, LATE, OVERTIME), puan etkisi (PointImpact, artı veya eksi) ve parasal etkisi (FinancialImpact, artı veya eksi) aynı satırda. Giriş-çıkış (TimeEntry, fazla mesai bayrağıyla birlikte), izin (LeaveRequest) ve maaş (EmployeeSalary) kayıtlarıyla birlikte puantajın veri temelini oluşturuyor.
Sonuç. Her prim ve ceza puan ve para karşılığıyla birlikte tek bir kayıtta, nedeniyle izlenebiliyor. Personel bir gecikmenin ya da fazla mesainin kendisine puan ve para olarak neye karşılık geldiğini görebiliyor. Projenin en çok işe yarayan özelliği olan şeffaflık bu kayıt yapısına dayanıyor.
Mühendislik Kararı 5: Docker'sız, Tek Binary ile Deploy
Sorun. Kurumsal bir iç sistemin altyapısı kolayca gereğinden ağır hale gelebiliyor: konteyner orkestrasyonu, registry, ek proxy katmanları. Bu sistemin kullanıcıları tek bir organizasyonun personeli. Fazladan her altyapı katmanı bakım yükü ve olası arıza noktası demek.
Karar. Docker kullanılmadı. Go'nun çapraz derleme desteğiyle uygulama Linux için tek bir binary olarak derleniyor, VPS'e kopyalanıyor ve bir systemd servisi olarak çalışıyor.
Sonuç. Deploy, bir dosyanın kopyalanıp servisin yeniden başlatılmasından ibaret. Sunucuda Go çalışma ortamı, konteyner runtime'ı ya da image registry gerekmiyor. Altyapı bilinçli olarak projenin ölçeğine göre seçildi. Ölçek ileride değişirse tek binary her zaman bir konteynere konabilir. Bugün ihtiyaç olmayan karmaşıklığı baştan kurmak ise bakım maliyetini peşin ödemek olurdu.
Kapanış
XTech Nexus CRM, "kimde ne var" sorusuyla başlayıp ofisleri, kasaları, personeli ve ekipmanı aynı veri modelinde birleştiren bir sisteme dönüştü. Projenin değeri şu kararlarda:
- Doğru veri modeli: Ürün tanımı ile fiziksel varlığın ayrılması ve zimmet geçmişinin ayrı tutulması. Görünürlük sorunu bu sayede çözüldü.
- Tip düzeyinde finansal doğruluk: Tutarların int64 kuruş olarak saklanması ve kasaların kendi para birimiyle tutulması.
- Kuralı kodda açık tutmak: Onay zincirinin bir durum makinesi olarak, iş kurallarının da adaptörlerden ayrı domain katmanında tanımlanması.
- Şeffaflığı veri yapısıyla sağlamak: Puan ve parasal etkinin aynı kayıtta tutulması.
- Ölçeğe uygun altyapı: Tek binary ve systemd ile sade bir deploy.
Çok ofisli bir yapı için envanter/zimmet takibi, ön muhasebe ya da İK süreçlerini tek sistemde toplamak istiyorsanız veya Go tabanlı bir kurumsal backend arıyorsanız, proje teklifleri için iletişime geçebilirsiniz.