Wisecolt-CI/docs/PROJE_DOKUMANTASYONU.md

# Wisecolt-CI Proje Dökümantasyonu

## 📋 İçindekiler
- [Proje Genel Bakış](#-proje-genel-bakış)
- [Backend Dökümantasyonu](#-backend-dökümantasyonu)
- [Frontend Dökümantasyonu](#-frontend-dökümantasyonu)
- [API Referansı](#-api-referansı)
- [Kurulum](#-kurulum)
- [Kullanım](#-kullanım)
- [Geliştirme](#-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
```typescript
// 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ı
```typescript
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
```typescript
// 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
```bash
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
```typescript
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
```typescript
<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:**
```json
{
  "username": "admin",
  "password": "supersecret"
}
```

**Response:**
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}
```

#### GET /auth/me
Token doğrulama ve kullanıcı bilgileri.

**Headers:**
```
Authorization: Bearer <token>
```

**Response:**
```json
{
  "username": "admin"
}
```

### Jobs API

#### GET /jobs
Tüm job'ları listeler.

**Response:**
```json
[
  {
    "_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:**
```json
{
  "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:**
```json
{
  "success": true
}
```

#### POST /jobs/:id/run
Job'ı manuel olarak çalıştırır.

**Response:**
```json
{
  "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:**
```bash
git clone https://github.com/your-repo/wisecolt-ci.git
cd wisecolt-ci
```

2. **Ortam dosyalarını yapılandır:**
```bash
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
```

3. **Admin bilgilerini gir:**
```bash
# 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:**
```bash
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
```typescript
// 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
```typescript
// src/index.ts
import yeniRoute from "./routes/yeniRoute.js";

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

### Frontend Geliştirme

#### Yeni Sayfa Ekleme
```typescript
// src/pages/YeniSayfa.tsx
import React from "react";

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

#### Rotalama Ekleme
```typescript
// src/App.tsx
import { YeniSayfa } from "./pages/YeniSayfa";

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

#### API İsteği Ekleme
```typescript
// src/api/client.ts
export async function yeniEndpoint() {
  const { data } = await apiClient.get("/yeni");
  return data;
}
```

### 🐳 Docker Yapılandırması

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

#### Frontend Dockerfile
```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.*