Mergen AI, PDF ve benzeri dijital belgelerinizi yapay zeka desteğiyle analiz eden, içlerindeki tablo ve metin verilerini otonom bir şekilde çıkaran kapsamlı bir mikroservis platformudur. Gelişmiş yapay zeka modelleri kullanarak karmaşık dokümanları bile yüksek doğrulukla ayrıştırır.
Proje, 3 ana servis ve destekleyici altyapı bileşenlerinden oluşur:
- Backend (
mergen-backend): Java 21 ve Spring Boot 4.0 kullanılarak geliştirilmiş ana REST API sunucusu. JWT kimlik doğrulama, veritabanı işlemleri, dosya yönetimi (MinIO) ve asenkron görev kuyruklarını (RabbitMQ, Redis) yönetir. - Yapay Zeka Servisi (
python-ai-service): Python 3.12 ile yazılmış, Hugging Face,DeepDoctection,DoclingveFastAPIkullanan asenkron görev işlemcisi. RabbitMQ üzerinden gelen analiz taleplerini alır, yapay zeka modelleriyle doküman üzerindeki karmaşık işlemleri gerçekleştirir. - Frontend (
mergen-frontend): React 19, TypeScript ve Vite altyapısıyla geliştirilmiş modern kullanıcı arayüzü. Radix UI ve Tailwind CSS ile şık ve erişilebilir bir deneyim sunar. Sayfa bazlı durum yönetimi için Zustand araçlarını kullanır. - Altyapı Bileşenleri:
- PostgreSQL 16: Ana ilişkisel veritabanı.
- Redis 7: Önbellekleme (Cache) işlemleri.
- RabbitMQ: Backend ve AI servisi arasında asenkron, mesaj kuyruğu yönetimi.
- MinIO: AWS S3 uyumlu obje depolama platformu.
Projede kimlik doğrulama, JWT (JSON Web Token) tabanlıdır.
-
Kullanıcı giriş yapar: Frontend, backend’deki giriş yap uç noktasına kullanıcı bilgilerini gönderir.
-
Backend JWT üretir: Kimlik doğrulama başarılıysa backend bir JWT access token üretip frontend’e döner.
-
Frontend token ile istek atar: Token, sonraki tüm korumalı isteklerde HTTP header olarak gönderilir:
Authorization: Bearer <token> -
Backend token’ı doğrular: Backend, token’ın imzasını/son kullanma tarihini kontrol eder ve geçerliyse isteği “kimliği doğrulanmış” kabul eder.
-
Korumalı endpoint’ler: Belge listeleme/yükleme, analiz tetikleme gibi işlemler JWT olmadan çağrılamaz.
mergen-ai/
├── mergen-backend/ # Spring Boot ana backend uygulamasının kaynak kodları
├── mergen-frontend/ # Vite + React ile kurgulanmış web arayüzü dosyaları
├── python-ai-service/ # AI analizcileri, HuggingFace modelleri ve asenkron workerlar
├── .github/workflows/ # CI/CD (Sürekli Entegrasyon) GitHub Actions senaryoları
├── docker-compose.yml # Tüm sistemi tek tıkla ayağa kaldırmak için orchestration
└── .env # Tüm uygulamaların ortak kullandığı ortam değişkenleri
Projeyi kendi bilgisayarınızda çalıştırmak oldukça basittir. Uygulamalar Docker konteyner mimarisi ile tasarlandığı için kendi bilgisayarınıza Java, Node.js veya Python kurmanıza gerek kalmadan tüm kod bloğunu kolayca ayağa kaldırabilirsiniz.
Sadece aşağıdaki yazılımların bilgisayarınızda kurulu ve Docker servisinin açık olması yeterlidir:
Terminal veya komut satırınızı açıp projeyi bilgisayarınıza indirin:
git clone https://github.com/Serkan0YLDZ/pdf2table.git
cd pdf2tableProjenin ana dizinindeki .env dosyası geliştirme ortamının çalışması için minimum ayarları barındırır. Hazır olarak geldiği için ekstra bir işlem yapmanıza gerek yoktur, ancak port veya şifreleri isterseniz değiştirebilirsiniz:
# Varsayılan .env yapılandırması
POSTGRES_USER=mergen_user
POSTGRES_PASSWORD=mergen_password
MINIO_ROOT_USER=minioadmin
# ...(Not: Canlı ortama (Production) alırken buradaki şifreleri ve JWT secret'ı daha güvenli ifadelerle değiştirmeyi unutmayın!)
Docker Compose komutunu kullanarak veritabanı, sistem kuyrukları, lokal S3 depolamanız, backend, frontend ve AI servisinin hepsini tek bir komutla başlatabilirsiniz:
docker compose up -d --build(İlk çalıştırmada Docker imajlarının çekilmesi ve projelerin indirilmesi sistem özelliklerinize/internet hızınıza bağlı olarak birkaç dakika sürebilir.)
Tüm log kayıtlarını (hata veya çalışma) terminal ekranından canlı izlemek isterseniz:
docker compose logs -fKomut başarı ile tamamlandıktan ve servisler ayağa kalktıktan sonra platforma direkt tarayıcı üzerinden ulaşabilirsiniz:
| Modül / Servis | Erişilebilir Adres (URL) | Açıklama |
|---|---|---|
| İnternet Sitesi (Frontend) | http://localhost | Kullanıcının etkileşime girdiği arayüz sayfası. |
| Backend API | http://localhost:8080 |
Java Spring Boot REST API Endpoint'leri |
| Swagger (API Dokümantasyonu) | http://localhost:8080/swagger-ui.html |
Backend projelerinin test ve doküman arayüzü |
| MinIO Yönetici Paneli | http://localhost:9001 | S3 depolama birimi yöneticisi (Giriş: minioadmin / minioadmin) |
| RabbitMQ Arayüzü | http://localhost:15672 | Mesaj ve görev takip sistemi (Giriş: guest / guest) |
docker compose down(Eğer veritabanındaki kayıtları da silip tamamen temiz bir sayfa açmak isterseniz docker compose down -v komutunu uygulayın.)
Projede kod kalitesini ve her geliştirmeyi otomatikleştirmek üzere GitHub Actions kullandım (.github/workflows/main-ci.yml). main dalına (branch) her yeni kod eklendiğinde aşağıdaki akış otomatik tetiklenir:
- Backend Birim Testleri: Bağımlılıklar indirilir ve sisteme yüklenmiş olası veritabanı ya da Controller senaryoları uçtan uca test edilir (
mvn test). - Frontend Build & Lint: React kodları üzerinde yazım hatası ve standart analizi yapılır (
eslint), ardından üretim sürümü başarıyla derleniyor mu derlenmiyor mu kontrol testlerine tabi tutulur. - Python AI Testleri: Yapay zeka servisindeki fonksiyon mantığı
pytestmodülüyle asenkron test edilir. - Uçtan Uca (E2E) UI Test: Gerçek bir tarayıcı ortamını simüle etmek amaçlı, tüm sistem arkaplanda konteynerler ile kaldırılır ve Playwright otonom testi sayesinde site akşında butonların ve görsel düzenin sorunsuz çalışıp çalışmadığı son kontrol niteliğinde testte tabi tutulur.