Fintwin

Kişisel finans öncelikli, ayrı bir KOBİ / AI CFO modülü bulunan yapay zeka destekli Finansal Dijital İkiz platformu.

Hackathon 2026 / Jüri Hızlı İnceleme

Fintwin, BTK Akademi, Google ve Girişimcilik Vakfı iş birliğiyle düzenlenen Hackathon 2026 için hazırlanmıştır. 2026 etkinliği çevrim içi bir yazılım ve yapay zeka ürün yarışmasıdır; kamuya açık duyurularda geliştirme süreci 06-19 Mayıs 2026, ön jüri değerlendirmesi 20-30 Mayıs 2026, jüri sunumu ise 05 Haziran 2026 olarak geçmektedir. Bu repoda Gemini; finansal agent, Spending DNA yorumları, hedef koçu, fiş OCR, ekstre ayrıştırma, konuşmayı yazıya çevirme ve metni sese çevirme akışlarında ana yapay zeka katmanıdır.

Ürün, 2026 değerlendirme başlıklarıyla şu şekilde eşleşir:

• Teknik yeterlilik: tip güvenli monorepo, Prisma migration'ları, CI, production env doğrulaması, rate limiting ve deterministik finans motorları.
• Problem çözme: gerçek nakit akışı, harcama, borç ve hedef kararları için kişisel finans dijital ikizi ve KOBİ / AI CFO iş akışları.
• Yapay zeka kullanımı: Gemini yalnızca yardımcı bir sohbet kutusu değil, ürünün ana akışlarında kullanılır.
• Yenilikçilik: Spending DNA, Emotional Delay, hedefe duyarlı koçluk, fiş/ekstre agent'ları ve token dostu agent context'i.
• Gerçek dünya uygulanabilirliği: sessiz demo fallback yoktur; kullanıcılar gerçek profil, bütçe, hedef, yatırım ve KOBİ nakit akışı kayıtları oluşturur.

Önerilen 7 dakikalık inceleme rotası:

1. Giriş yapın veya yeni bir kişisel hesap oluşturun.
2. Finansal Profil bölümünde gelir, maaş günü, hesaplar, kategori limitleri ve hedefleri ekleyin.
3. Deterministik finans hesapları ve Gemini açıklamalarını görmek için Dashboard, Spending DNA, What-if ve Emotional Delay ekranlarını inceleyin.
4. Hedefler ekranında aylık/yıllık birikim hedefleri ve kategori limitleri belirleyin; agent balonu hedeflere göre Gemini tavsiyesi üretir.
5. GEMINI_API_KEY tanımlıysa gerçek bir belgeyle Fiş / Ekstre akışlarını deneyin.
6. Agent ekranında doğal dille bir finans sorusu sorun; cevaplar ham veritabanı dökümü yerine token dostu finans bağlamı kullanır.
7. KOBİ bölümüne geçerek AI CFO Lite, nakit akışı projeksiyonu, tahsilat skoru ve kurumsal karar simülasyonunu inceleyin.

Repo hijyeni:

• Gerçek .env dosyaları ignore edilir ve commitlenmemelidir.
• npm run check:no-env, tracked ve staged dosyalarda yanlışlıkla eklenmiş env dosyalarını veya anahtar benzeri secret kalıplarını tarar.
• Demo fallback'ler kapalıdır; API, veritabanı veya AI yapılandırması eksikse uygulama sessizce sonuç uydurmak yerine görünür şekilde hata verir.
• Production ortamında Gemini, Twelve Data, JWT, veritabanı ve OAuth env değerleri doğrulanır.
• CI, main dalına her push/PR için env taraması, Prisma generate, typecheck ve testleri çalıştırır.

Teknoloji Yığını

• Web: Next.js
• Mobil: React Native CLI, iOS öncelikli ve Android uyumlu
• Backend: NestJS
• DB: Prisma schema ile PostgreSQL
• AI: OpenAI uyumlu endpoint üzerinden Gemini API, LangChain ve LangGraph
• OCR: Gemini multimodal structured JSON output
• Auth: JWT ve web tarafında Google Identity Services ile Google girişi
• Bildirimler: uygulama içi aksiyon hatırlatmaları; FCM token alma akışı hazırdır, push gönderimi ayrı bir production kararıdır
• Grafikler: web tarafında Recharts

Yerel Kurulum

npm install
cp .env.example .env
docker compose up -d
npm run db:migrate:deploy
npm run dev:local
npm run dev:mobile

PowerShell'de cp .env.example .env yerine Copy-Item .env.example .env kullanın.

AI akışlarını değerlendirmeden önce .env içine en az DATABASE_URL, DIRECT_URL, JWT_SECRET ve GEMINI_API_KEY değerlerini girin. Gerçek portföy fiyatları için TWELVE_DATA_API_KEY gereklidir; bu anahtar yoksa portföy satırları açık şekilde fiyatlanmamış olarak işaretlenir.

npm run dev:local, API'yi http://localhost:4000, web uygulamasını http://localhost:3000 üzerinde başlatır. Başlangıçta 3000/4000 portlarındaki eski Fintwin dev process'lerini temizler ve iki servis için readiness satırları basar. Zaten çalışan dev process'lerini özellikle korumak istiyorsanız npm run dev:local -- --no-clean kullanın.

.env dosyalarını asla commit'lemeyin. Git'e yalnızca .env.example dosyaları girmelidir.

Demo fallback'ler kapalıdır. Web ve mobil uygulamalar API'yi çağırmak zorundadır; API de PostgreSQL'e DATABASE_URL / DIRECT_URL üzerinden bağlanmalıdır. Eksik env değerleri local demo veri göstermek yerine startup/build aşamasında görünür hata üretmelidir.

Demo için login ekranından yerel bir hesap oluşturun. Production incelemesi için yeniden kullanılabilir demo kullanıcı bilgisi gerekmez.

Doğrulama Komutları

npm run check:no-env
npm run typecheck --workspaces --if-present
npm run test --workspaces --if-present
npm run verify

Production web build'leri bilerek local olmayan bir API URL'i ister. Bir API deploy etmeden CI benzeri build kontrolü yapmak için geçici bir production origin set edin:

NEXT_PUBLIC_API_URL="https://api.example.com" npm run build -w @fintwin/web

PowerShell'de:

$env:NEXT_PUBLIC_API_URL="https://api.example.com"; npm run build -w @fintwin/web

Audit notu: npm audit şu anda Next'in kendi içinde sabitlediği postcss@8.4.31 üzerinden moderate seviyede bir PostCSS uyarısı raporlamaktadır. npm audit fix --force, Next'i güvenli olmayan şekilde eski bir major sürüme düşürmeye çalıştığı için bu durum geçersiz override ile saklanmamış, upstream framework bağımlılığı olarak not edilmiştir.

Production Env

Deployment kontrol listesi için .env.production.example dosyasını kullanın. API tarafında NODE_ENV=production iken şu değerler zorunludur:

• DATABASE_URL: çalışan API'nin kullandığı Supabase transaction pooler URI.
• DIRECT_URL: Prisma migration'larının kullandığı Supabase direct/session-pooler URI.
• JWT_SECRET: en az 32 karakterli rastgele secret.
• API_CORS_ORIGINS: API'yi çağırmasına izin verilen web origin'leri, virgülle ayrılmış şekilde.
• GEMINI_API_KEY: production AI, OCR, speech-to-text ve text-to-speech akışları için zorunludur.
• TWELVE_DATA_API_KEY: production portföy piyasa verisi için zorunludur.
• GOOGLE_OAUTH_CLIENT_ID: API'nin web id_token değerlerini doğrulamak için kullandığı Google OAuth Web Client ID.

Web uygulaması için NEXT_PUBLIC_API_URL ve NEXT_PUBLIC_GOOGLE_CLIENT_ID değerlerini set edin. NEXT_PUBLIC_GOOGLE_CLIENT_ID, API tarafındaki GOOGLE_OAUTH_CLIENT_ID ile aynı Google OAuth Web Client ID olmalıdır.

Google OAuth web client, local geliştirme için JavaScript origin olarak http://localhost:3000, redirect URI olarak http://localhost:3000/login/google değerlerine izin vermelidir. Production'da deploy edilen web origin'i ve <web-origin>/login/google eklenmelidir; OAuth consent screen app adı/domain'i deploy edilen ürünle uyumlu kalmalıdır.

Local web auth için en sağlıklı başlangıç npm run dev:local komutudur. apps/web/next.config.mjs, sadece npm run dev:web çalıştırıldığında da NEXT_PUBLIC_GOOGLE_CLIENT_ID görülebilsin diye repo root .env dosyasını yükler.

Web uygulaması oturum JWT'sini /api/auth/* route'ları üzerinden HttpOnly fintwin_token cookie'sinde saklar. Browser tarafı API çağrıları /api/backend/* üzerinden gider; bu route token'ı localStorage üzerinden okumak yerine cookie'yi server-side ekler.

Hızlı hackathon demoları için admin kısayolu admin@local.dev hesabına gider; bu hesap database'de seed edilmişse production'da da çalışır.

JWT secret üretmek için:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Deploy öncesi Prisma Client üretin ve commitlenmiş Prisma migration'larını uygulayın:

npm run db:generate
npm run db:migrate:deploy

apps/api/prisma/schema.prisma değiştirirken localde npm run db:migrate:dev -- --name <change-name> kullanın. Production için prisma db push kullanmayın.

Frontend deployment'ları yalnızca public API URL'e ihtiyaç duyar:

• Web: NEXT_PUBLIC_API_URL="https://your-api-domain.com" ve NEXT_PUBLIC_GOOGLE_CLIENT_ID="<your-google-oauth-web-client-id>"
• Mobil build env: EXPO_PUBLIC_API_URL="https://your-api-domain.com"

Gemini varsayılanları:

• Birincil text model: gemini-3-flash-preview
• Birincil vision model: gemini-3-flash-preview
• İkincil model: gemini-2.5-flash
• STT model: gemini-2.5-flash
• TTS model: gemini-3.1-flash-tts-preview
• OpenAI uyumlu base URL: https://generativelanguage.googleapis.com/v1beta/openai
• Anahtar env adı: GEMINI_API_KEY

Piyasa verisi varsayılanları:

• Sağlayıcı: Twelve Data
• Anahtar env adı: TWELVE_DATA_API_KEY
• Portföy API'leri: GET /investments/portfolio, GET /investments/symbols?query=THYAO, POST /investments/holdings
• Quote cache: yalnızca başarılı provider cevapları için 24 saat. Provider veya anahtar yoksa portföy pozisyonları açık şekilde fiyatlanmamış olarak işaretlenir; uygulama statik fallback fiyatlardan kar/zarar hesaplamaz.

Entegrasyon smoke kontrolleri:

npm run smoke:integrations
npm run smoke:integrations -- --only gemini,twelve

Ürün Odağı

Ana ürün kişisel bir AI Finansal Dijital İkizdir: Spending DNA, kampanya hazırlığı, what-if simülasyonları, Emotional Delay, aksiyon merkezi, fiş okutma, abonelik sızıntısı tespiti ve açıklanabilir agent cevapları.

KOBİ özellikleri ayrı business modülünde yer alır: AI CFO Lite, nakit akışı projeksiyonu, tahsilat skoru ve kurumsal karar simülasyonu.

Belge Agent'ları

• Receipt Agent: POST /documents/receipt-agent/import bir fiş görselini okur; satıcı, tutar, vergi, tarih, ödeme yöntemi ve kategoriyi tespit eder; ardından tek bir gider işlemi ekler.
• Statement Agent: POST /documents/statement-agent/preview ay sonu ekstresi PDF/görsel/metin dosyasını okur ve gözden geçirme için kategorize edilmiş harcama satırları döndürür; POST /documents/statement-agent/confirm seçilen satırları gider işlemi olarak ekler.
• Abonelik hatırlatmaları: POST /actions/subscription-reminder, ekstre analizinde tespit edilen tekrarlayan aboneliklerden tarihli pending action oluşturur.

Belge agent'ları GEMINI_API_KEY gerektirir; anahtar veya girdi belge eksikken artık demo fiş ya da ekstre sonucu döndürmez.