Wisecolt-CI/docs/PROJE_DOKUMANTASYONU.md

Wisecolt CI Proje Dökümantasyonu

📋 İçindekiler

• Proje Genel Bakış
• Backend Dökümantasyonu
• Frontend Dökümantasyonu
• API Referansı
• Kurulum
• Kullanım
• Geliştirme

🎯 Proje Genel Bakış

Wisecolt-CI, modern web teknolojileriyle geliştirilmiş tam teşekküllü bir CI/CD (Sürekli Entegrasyon/Sürekli Dağıtım) platformudur. Proje, repository otomasyonu ve test süreçlerini yönetmek için tasarlanmıştır.

✨ Temel Özellikler

• 🔐 Kimlik Doğrulama: JWT tabanlı güvenli kimlik yönetimi
• 📊 Job Yönetimi: Repository'lar için otomatik test süreçleri
• ⚡ Gerçek Zamanlı: Socket.io ile canlı durum güncellemeleri
• 🎨 Modern UI: React + shadcn/ui ile responsive arayüz
• 🌙 Tema Desteği: Dark/Light moda geçiş imkanı
• 🐳 Konteynerizasyon: Docker ile tam izole geliştirme ortamı

🛠 Teknoloji Yığını

Backend

• Node.js + TypeScript - Güçlü sunucu tarafı geliştirme
• Express.js - Minimal ve esnek web framework'ü
• MongoDB - NoSQL veritabanı
• Socket.io - Gerçek zamanlı çift yönlü iletişim
• JWT - Güvenli kimlik doğrulama
• Mongoose - MongoDB modelleme ve validasyon

Frontend

• React 18 - Modern bileşen tabanlı UI kütüphanesi
• TypeScript - Tip güvenli geliştirme
• Vite - Hızlı build tool ve geliştirme sunucusu
• Tailwind CSS - Utility-first CSS framework'ü
• shadcn/ui - Modern React UI bileşen kütüphanesi
• React Router - Client tarafı rotalama
• Axios - HTTP istemci kütüphanesi

DevOps

• Docker + Docker Compose - Konteyner orkestrasyon
• Hot Reload - Geliştirme anında canlı güncellemeler

📊 Backend Dökümantasyonu

🏗 Mimari

Backend, RESTful API prensiplerine göre tasarlanmış modüler bir yapıya sahiptir.

Ana Bileşenler

1. Express Sunucusu (src/index.ts)
2. Router'lar (src/routes/)
3. Middleware (src/middleware/)
4. Servisler (src/services/)
5. Modeller (src/models/)
6. Konfigürasyon (src/config/)

🔐 Authentication Sistemi

Endpoint'ler

• POST /auth/login - Kullanıcı girişi
• GET /auth/me - Token doğrulama ve kullanıcı bilgileri

Güvenlik Özellikleri

• JWT tabanlı kimlik doğrulama
• Bearer token authentication
• CORS yapılandırması
• .env tabanlı hassas bilgi yönetimi

Kullanım

// Giriş işlemi
const response = await fetch('/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username, password })
});

// Token ile korumalı istek
const response = await fetch('/protected-endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

📋 Job Yönetim Sistemi

Model Yapısı

interface JobDocument {
  name: string;           // Job adı
  repoUrl: string;        // Repository URL'si
  testCommand: string;    // Çalıştırılacak test komutu
  checkValue: number;      // Kontrol değeri (dakika/saat/gün)
  checkUnit: TimeUnit;    // Kontrol birimi
  status: JobStatus;     // Job durumu
  lastRunAt?: Date;      // Son çalışma zamanı
  lastDurationMs?: number; // Son çalışma süresi (ms)
  lastMessage?: string;   // Son mesaj
}

Endpoint'ler

• GET /jobs - Tüm job'ları listele
• GET /jobs/:id - Job detaylarını getir
• POST /jobs - Yeni job oluştur
• PUT /jobs/:id - Job güncelle
• DELETE /jobs/:id - Job sil
• POST /jobs/:id/run - Job'ı manuel çalıştır

Job Süreç Yönetimi

• Otomatik Çalıştırma: Belirlenen aralıklarla otomatik çalışma
• Git Operasyonları: Clone/pull işlemleri
• NPM Kurulum: Bağımlılıkların otomatik kurulumu
• Test Çalıştırma: Belirlenen komutların çalıştırılması
• Sonuç Kaydı: Test sonuçlarının veritabanına kaydedilmesi

⚡ Socket.io Real-time İletişim

Olaylar

• connection - Yeni bağlantı kurulduğunda
• hello - Bağlantı kurulduğunda hoş geldik mesajı
• ping/pong - Bağlantı kontrolü
• counter:update - Sayaç güncellemesi
• counter:start/stop - Sayaç başlatma/durdurma
• job:subscribe - Job durum takibi
• job:status - Job durum güncellemesi
• job:log - Job log akışı

Kullanım Örneği

// Client tarafı
socket.on('job:status', (data) => {
  console.log('Job durumu güncellendi:', data);
});

// Server tarafı
io.to(`job:${jobId}`).emit('job:status', {
  jobId,
  status: 'running',
  lastMessage: 'Test çalıştırılıyor...'
});

🔧 Konfigürasyon Yönetimi

Environment Değişkenleri

PORT=4000                          # Backend sunucu portu
MONGO_URI=mongodb://mongo:27017/wisecoltci  # MongoDB bağlantı adresi
ADMIN_USERNAME=admin                  # Admin kullanıcı adı
ADMIN_PASSWORD=supersecret           # Admin şifresi
JWT_SECRET=your-secret-key            # JWT imzalama anahtarı
CLIENT_ORIGIN=http://localhost:5173    # Frontend adresi (CORS için)

🎨 Frontend Dökümantasyonu

🏗 Mimari

Frontend, modern React prensiplerine göre tasarlanmış bileşen tabanlı bir yapıya sahiptir.

Ana Bileşenler

1. App Component - Ana rotalama ve yapılandırma
2. Pages - Sayfa bileşenleri (HomePage, JobsPage, vb.)
3. Components - Yeniden kullanılabilir UI bileşenleri
4. Providers - React Context Provider'lar
5. API Layer - Backend ile iletişim katmanı

🔐 Authentication Provider

AuthProvider Özellikleri

• Kullanıcı durum yönetimi
• Token saklama (localStorage)
• Otomatik kimlik doğrulama
• Login/logout işlemleri

Kullanım

const { user, token, login, logout, loading } = useAuth();

// Giriş yapma
await login('admin', 'password');

// Çıkış yapma
logout();

// Korumalı bileşen
if (!user) {
  return <Navigate to="/login" />;
}

📱 Sayfa Bileşenleri

HomePage

• Proje genel bakış ve istatistikler
• Hızlı erişim linkleri

JobsPage

• Job listesi
• Job oluşturma/düzenleme/silme işlemleri
• Real-time durum güncellemeleri

JobDetailPage

• Job detayları
• Manuel çalıştırma
• Log akışı izleme

🎨 UI Bileşen Kütüphanesi (shadcn/ui)

Temel Bileşenler

• Button - Özelleştirilebilir düğmeler
• Input - Form giriş alanları
• Select - Seçim kutuları
• Card - Kart bileşenleri
• Label - Etiket bileşenleri
• Switch - Toggle switch'ler
• Toaster - Bildirim sistemi

Stil Sistemi

• Tailwind CSS - Utility-first stil yaklaşımı
• Responsive Design - Mobil uyumlu tasarım
• Tema Desteği - Dark/Light moda geçiş

📱 Responsive Tasarım

Breakpoint'ler

• sm: - 640px ve üzeri
• md: - 768px ve üzeri
• lg: - 1024px ve üzeri
• xl: - 1280px ve üzeri

Örnek Kullanım

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Responsive grid layout */}
</div>

🔌 API Referansı

Authentication API

POST /auth/login

Kullanıcı girişi için endpoint.

Request Body:

{
  "username": "admin",
  "password": "supersecret"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

GET /auth/me

Token doğrulama ve kullanıcı bilgileri.

Headers:

Authorization: Bearer <token>

Response:

{
  "username": "admin"
}

Jobs API

GET /jobs

Tüm job'ları listeler.

Response:

[
  {
    "_id": "64a1b2c3d4e5f6789012345",
    "name": "Frontend Tests",
    "repoUrl": "https://github.com/user/frontend-repo",
    "testCommand": "npm test",
    "checkValue": 5,
    "checkUnit": "dakika",
    "status": "idle",
    "lastRunAt": "2023-07-01T10:30:00.000Z",
    "lastDurationMs": 45000,
    "lastMessage": "Başarılı",
    "createdAt": "2023-07-01T08:00:00.000Z",
    "updatedAt": "2023-07-01T10:30:00.000Z"
  }
]

POST /jobs

Yeni job oluşturur.

Request Body:

{
  "name": "Backend Tests",
  "repoUrl": "https://github.com/user/backend-repo",
  "testCommand": "npm run test",
  "checkValue": 10,
  "checkUnit": "dakika"
}

GET /jobs/:id

Belirtilen job'ın detaylarını getirir.

PUT /jobs/:id

Mevcut job'ı günceller.

Request Body: POST ile aynı formatta

DELETE /jobs/:id

Job'ı siler.

Response:

{
  "success": true
}

POST /jobs/:id/run

Job'ı manuel olarak çalıştırır.

Response:

{
  "queued": true
}

WebSocket Olayları

client → server

• ping - Bağlantı kontrolü
• job:subscribe - Job durum takibi
• job:unsubscribe - Job durum takibi bırakma

server → client

• hello - Bağlantı kurulduğunda
• pong - Ping yanıtı
• job:status - Job durumu güncellemesi
• job:log - Job log mesajı

🚀 Kurulum

Gereksinimler

• Docker ve Docker Compose
• Git

Adım Adım Kurulum

1. Repo'yu klonla:

git clone https://github.com/your-repo/wisecolt-ci.git
cd wisecolt-ci

2. Ortam dosyalarını yapılandır:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

3. Admin bilgilerini gir:

# backend/.env
ADMIN_USERNAME=your-admin-username
ADMIN_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret-key
CLIENT_ORIGIN=http://localhost:5173

# frontend/.env
VITE_API_URL=http://localhost:4000

4. Servisleri başlat:

docker compose up --build

5. Uygulamaya eriş:

• Frontend: http://localhost:5173
• Backend API: http://localhost:4000
• MongoDB: mongodb://localhost:27017

💻 Kullanım

Giriş İşlemi

1. Tarayıcıda http://localhost:5173 adresine gidin
2. Varsayılan giriş bilgileri:
   • Kullanıcı adı: admin
   • Şifre: supersecret
3. Giriş yap butonuna tıklayın

Job Oluşturma

1. Sol menüden "Jobs" sayfasına gidin
2. "Yeni Job" butonuna tıklayın
3. Job bilgilerini girin:
   • Job Adı: Test için anlaşılır bir ad
   • Repository URL: GitHub repository adresi
   • Test Komutu: Çalıştırılacak komut (örn: npm test)
   • Kontrol Değeri: Kaç dakikada/saat/günde bir çalışacağı
   • Kontrol Birimi: Zaman birimi seçimi
4. Kaydet butonuna tıklayın

Job İzleme

1. Jobs sayfasından oluşturduğunuz job'a tıklayın
2. Job detay sayfasında:
   • Durum: Job'un mevcut durumu (idle/running/success/failed)
   • Sonuçlar: Son çalıştırma sonuçları ve süreleri
   • Loglar: Gerçek zamanlı log akışı
   • Manuel Çalıştırma: Job'u anında çalıştırma

🛠 Geliştirme

Backend Geliştirme

Yeni Route Ekleme

// src/routes/yeniRoute.ts
import { Router } from "express";
import { authMiddleware } from "../middleware/authMiddleware.js";

const router = Router();
router.use(authMiddleware);

router.get("/", (req, res) => {
  res.json({ message: "Yeni endpoint çalışıyor" });
});

export default router;

Ana Dosyada Route Ekleme

// src/index.ts
import yeniRoute from "./routes/yeniRoute.js";

app.use("/yeni", yeniRoute);

Frontend Geliştirme

Yeni Sayfa Ekleme

// src/pages/YeniSayfa.tsx
import React from "react";

export const YeniSayfa = () => {
  return (
    <div>
      <h1>Yeni Sayfa</h1>
      {/* Sayfa içeriği */}
    </div>
  );
};

Rotalama Ekleme

// src/App.tsx
import { YeniSayfa } from "./pages/YeniSayfa";

<Route path="/yeni" element={<YeniSayfa />} />

API İsteği Ekleme

// src/api/client.ts
export async function yeniEndpoint() {
  const { data } = await apiClient.get("/yeni");
  return data;
}

🐳 Docker Yapılandırması

Backend Dockerfile

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 4000
CMD ["npm", "run", "start"]

Frontend Dockerfile

FROM node:18-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

🔄 Otomatik Test Süreci

JobService, belirlenen aralıklarla otomatik test çalıştırır:

1. Repository Clone: İlk çalıştırmada repo klonlanır
2. Bağımlılık Kurulum: npm install çalıştırılır
3. Test Çalıştırma: Belirlenen komut çalıştırılır
4. Sonuç Kayıt: Sonuçlar veritabanına kaydedilir
5. Real-time Güncelleme: Socket.io ile client bilgilendirilir

📝 Notlar

Güvenlik

• JWT token'ları güvenli saklayın
• Environment değişkenlerini .env dosyasında tutun
• Production ortamında varsayılan şifreleri değiştirin

Performans

• MongoDB index'leri kullanın
• Büyük repository'ler için caching stratejileri uygulayın
• Frontend build optimizasyonu yapın

İzleme

• MongoDB log'larını izleyin
• Docker container log'larını kontrol edin
• Application metriklerini toplayın

---

Bu dökümantasyon Wisecolt-CI projesinin tüm özelliklerini ve kullanımını kapsamaktadır. Geliştirme sürecinde güncel tutulmalıdır.