ytp/docs/STRUCTURE.md

# Proje Yapısı Dokümantasyonu

Yakıt Takip Sistemi proje dosya yapısı, organizasyon ve mimari desenleri hakkında detaylı bilgi.

## 📋 İçerik

- [Genel Bakış](#genel-bakış)
- [Dizin Yapısı](#dizin-yapısı)
- [Frontend Mimarisi](#frontend-mimarisi)
- [Backend Mimarisi](#backend-mimarisi)
- [Veri Akışı](#veri-akışı)
- [Kurallar ve Standartlar](#kurallar-ve-standartlar)

## 🎯 Genel Bakış

### Proje Türü
- **Tip**: Full-stack Web Uygulaması
- **Mimari**: Client-Server
- **Deployment**: Monolitik
- **Database**: SQLite (file-based)

### Teknoloji Stack
- **Frontend**: Svelte + Vite
- **Backend**: Node.js + Express
- **Real-time**: Socket.IO
- **Database**: SQLite3
- **Styling**: CSS3 (no framework)
- **Build**: Vite

### Geliştirme Yaklaşımı
- **Component-based**: Bileşen tabanlı geliştirme
- **API-first**: API odaklı tasarım
- **Role-based**: Rol bazlı yetkilendirme
- **Responsive**: Mobil uyumlu tasarım

## 📁 Dizin Yapısı

```
ytp/
├── 📂 client/                    # Frontend uygulaması
│   ├── 📂 src/
│   │   ├── 📂 components/        # Svelte bileşenleri
│   │   │   ├── 📄 LoginView.svelte
│   │   │   ├── 📄 AdminPanel.svelte
│   │   │   ├── 📄 FuelManagerPanel.svelte
│   │   │   ├── 📄 InventoryManagerPanel.svelte
│   │   │   └── 📄 RoleWelcome.svelte
│   │   ├── 📂 lib/               # Yardımcı kütüphaneler
│   │   │   └── 📄 numberToWordsTr.js
│   │   ├── 📄 api.js             # API istemcisi
│   │   ├── 📄 app.css            # Ana stil dosyası
│   │   ├── 📄 main.js            # Uygulama giriş noktası
│   │   └── 📄 App.svelte         # Ana uygulama bileşeni
│   ├── 📄 index.html             # HTML template
│   ├── 📄 package.json           # Frontend bağımlılıkları
│   ├── 📄 vite.config.js         # Vite yapılandırması
│   └── 📄 svelte.config.js       # Svelte yapılandırması
├── 📂 server/                    # Backend uygulaması
│   ├── 📄 index.js               # Express sunucusu
│   ├── 📄 db.js                  # Veritabanı işlemleri
│   └── 📄 db-init.js             # Veritabanı başlangıç
├── 📂 data/                      # Veritabanı dosyaları
│   └── 📄 app.db                 # SQLite veritabanı
├── 📂 docs/                      # Dokümantasyon
│   ├── 📄 README.md
│   ├── 📄 API.md
│   ├── 📄 DATABASE.md
│   ├── 📄 STRUCTURE.md
│   └── 📄 DEPLOYMENT.md
├── 📄 package.json               # Proje bağımlılıkları
└── 📄 README.md                  # Proje açıklaması
```

## 🎨 Frontend Mimarisi

### Component Hiyerarşisi
```
App.svelte (Ana uygulama)
├── LoginView.svelte (Giriş)
├── RoleWelcome.svelte (Karşılama)
├── AdminPanel.svelte (Admin paneli)
├── FuelManagerPanel.svelte (Yakıt sorumlusu)
└── InventoryManagerPanel.svelte (Mal sorumlusu)
```

### Dosya Açıklamaları

#### App.svelte
- **Amaç**: Ana uygulama bileşeni ve routing
- **Sorumluluklar**:
  - Oturum yönetimi
  - Routing mantığı
  - Global durum yönetimi
  - Temel layout

#### components/LoginView.svelte
- **Amaç**: Kullanıcı giriş arayüzü
- **Features**:
  - Form validasyonu
  - Hata yönetimi
  - Başarılı giriş olayı
  - Responsive tasarım

#### components/AdminPanel.svelte
- **Amaç**: Admin yönetim paneli
- **Features**:
  - CRUD operasyonları
  - Tablo gösterimi
  - Form yönetimi
  - Modal dialoglar

#### components/FuelManagerPanel.svelte
- **Amaç**: Yakıt sorumlusu paneli
- **Features**:
  - Fiş oluşturma
  - Kaynak yönetimi
  - Socket.IO entegrasyonu
  - PDF indirme

#### components/InventoryManagerPanel.svelte
- **Amaç**: Mal sorumlusu paneli
- **Features**:
  - Fiş onay/reddetme
  - Atanan fiş listesi
  - Socket.IO bildirimleri
  - Durum yönetimi

#### lib/numberToWordsTr.js
- **Amaç**: Sayıları Türkçe metne çevirme
- **Kullanım**: PDF fişlerde rakam→yazı dönüşümü

#### api.js
- **Amaç**: API istemcisi
- **Features**:
  - HTTP istekleri
  - Error handling
  - Token yönetimi
  - Base URL konfigürasyonu

### State Management
- **Local State**: Svelte reaktif değişkenleri
- **Session Storage**: Token ve oturum bilgileri
- **Prop Drilling**: Component veri akışı
- **Custom Events**: Component haberleşmesi

### Styling Architecture
- **CSS3**: Modern CSS özellikleri
- **CSS Variables**: Tema ve renk yönetimi
- **Flexbox/Grid**: Responsive layout
- **Mobile-first**: Responsive tasarım yaklaşımı

## ⚙️ Backend Mimarisi

### Server Structure
```
server/
├── index.js           # Ana Express sunucusu
├── db.js              # Veritabanı katmanı
└── db-init.js         # Veritabanı başlangıç
```

### index.js - Express Sunucusu
**Amaç**: Ana uygulama sunucusu

**Bileşenler**:
- **HTTP Server**: Express.js uygulaması
- **WebSocket Server**: Socket.IO sunucusu
- **Authentication**: Token bazlı kimlik doğrulama
- **Authorization**: Rol bazlı yetkilendirme
- **API Routes**: RESTful endpoint'ler
- **Middleware**: CORS, JSON parsing, logging

**Route Structure**:
```javascript
// Authentication
POST /api/auth/login
POST /api/auth/logout
GET /api/session

// Admin routes
CRUD /api/inventory-managers
CRUD /api/vehicles
CRUD /api/units
CRUD /api/fuel-personnel

// Fuel Manager routes
GET /api/fuel/resources
GET /api/fuel-slips
POST /api/fuel-slips
GET /api/fuel-slips/:id/pdf

// Inventory Manager routes
GET /api/fuel-slips/assigned
PATCH /api/fuel-slips/:id/status
```

### db.js - Veritabanı Katmanı
**Amaç**: Veritabanı işlemleri ve model yönetimi

**Features**:
- **Connection Management**: SQLite bağlantısı
- **Schema Management**: Tablo oluşturma ve migration
- **CRUD Operations**: Create, Read, Update, Delete
- **Data Validation**: Veri doğrulama ve constraint'ler
- **Error Handling**: Veritabanı hata yönetimi
- **Sample Data**: Başlangıç verileri

**Function Groups**:
```javascript
// User management
getUserByUsername()
createInventoryManager()
listInventoryManagers()
updateInventoryManager()
deleteInventoryManager()

// Vehicle management
createVehicle()
listVehicles()
updateVehicle()
deleteVehicle()
getVehicleById()

// Unit management
createUnit()
listUnits()
updateUnit()
deleteUnit()
getUnitById()

// Personnel management
createFuelPersonnel()
listFuelPersonnel()
updateFuelPersonnel()
deleteFuelPersonnel()
getFuelPersonnelById()

// Fuel slip management
createFuelSlip()
listFuelSlips()
listFuelSlipsByInventoryManager()
getFuelSlipById()
updateFuelSlipStatus()
```

### db-init.js - Veritabanı Başlangıç
**Amaç**: Veritabanı başlangıç ve örnek veriler

**Features**:
- **Schema Creation**: Tablo oluşturma script'i
- **Sample Data**: Test verileri
- **Migration**: Versiyon geçişleri
- **Data Seeding**: Başlangıç verileri

## 🔄 Veri Akışı

### Authentication Flow
```
1. Kullanıcı giriş formu doldurur
2. Client → POST /api/auth/login
3. Server validates credentials
4. Server creates session token
5. Server returns token + user data
6. Client stores token (localStorage)
7. Client includes token in headers
8. Server validates token (middleware)
```

### Real-time Communication Flow
```
1. Client connects with token
2. Server validates and authenticates
3. Server adds client to appropriate rooms
4. Server emits events to relevant clients
5. Client handles events and updates UI
```

### Fuel Slip Creation Flow
```
1. Fuel Manager fills form
2. Client validates form data
3. Client → POST /api/fuel-slips
4. Server validates data
5. Server creates fuel slip
6. Server generates slip number
7. Server saves to database
8. Server emits to Inventory Manager
9. Server emits confirmation to Fuel Manager
10. Client updates UI
```

### Approval Flow
```
1. Inventory Manager reviews slip
2. Client → PATCH /api/fuel-slips/:id/status
3. Server validates permissions
4. Server updates status
5. Server emits to Fuel Manager
6. Server emits confirmation to Inventory Manager
7. Client updates UI
```

## 📏 Kurallar ve Standartlar

### Kodlama Standartları

#### JavaScript/Node.js
- **ES6+**: Modern JavaScript özellikleri
- **CamelCase**: Değişken ve fonksiyon isimleri
- **PascalCase**: Class ve constructor isimleri
- **UPPER_SNAKE_CASE**: Constant'lar
- **Async/Await**: Asenkron operasyonlar
- **Error Handling**: Try-catch blokları

#### Svelte
- **Component-based**: Tek sorumluluk ilkesi
- **Props**: Veri akışı parent → child
- **Events**: Haberleşme child → parent
- **Reactive**: $: reaktif değişkenler
- **Lifecycle**: onMount, onDestroy

#### CSS
- **BEM-like**: Component bazlı naming
- **Mobile-first**: Responsive yaklaşım
- **Flexbox/Grid**: Modern layout
- **CSS Variables**: Tema yönetimi
- **Minification**: Prodüksiyon için

### Dosya Organizasyonu

#### Frontend
```
src/
├── components/     # Svelte components
│   ├── View*.svelte    # Page-level components
│   ├── *Panel.svelte   # Feature components
│   └── *.svelte        # Reusable components
├── lib/           # Utility libraries
├── api.js         # API client
├── main.js        # App entry point
└── App.svelte     # Root component
```

#### Backend
```
server/
├── index.js       # Main server
├── db.js          # Database layer
└── db-init.js     # Database initialization
```

### API Design Standartları

#### RESTful Conventions
- **GET**: Veri okuma
- **POST**: Veri oluşturma
- **PUT**: Tam veri güncelleme
- **PATCH**: Kısmi veri güncelleme
- **DELETE**: Veri silme

#### Response Format
```javascript
// Success
{
  "data": { ... },
  "message": "Operation successful"
}

// Error
{
  "error": "Error description",
  "message": "User-friendly message"
}
```

#### HTTP Status Codes
- **200**: Success
- **201**: Created
- **204**: No Content
- **400**: Bad Request
- **401**: Unauthorized
- **403**: Forbidden
- **404**: Not Found
- **409**: Conflict
- **500**: Server Error

### Security Standards

#### Authentication
- **JWT-like**: Token based authentication
- **Secure storage**: localStorage için güvenlik
- **Token rotation**: Session management
- **Logout**: Proper token cleanup

#### Authorization
- **Role-based**: Access control by role
- **Route-level**: Middleware protection
- **Resource-level**: Ownership validation
- **API-level**: Permission checks

#### Data Validation
- **Input validation**: All user inputs
- **SQL injection**: Parameterized queries
- **XSS prevention**: Output escaping
- **CSRF protection**: Token validation

### Performance Standards

#### Frontend
- **Lazy loading**: Component lazy loading
- **Code splitting**: Dynamic imports
- **Bundle optimization**: Vite optimization
- **Asset optimization**: Image compression

#### Backend
- **Connection pooling**: Database connections
- **Query optimization**: Efficient queries
- **Caching**: Response caching
- **Compression**: Gzip compression

#### Database
- **Indexing**: Proper indexes
- **Query optimization**: Efficient queries
- **Connection management**: Single connection
- **Backup strategy**: Regular backups

---

**Not**: Bu yapı geliştirme sürecinde evrilebilir. Değişiklikler için ekibin onayı gerekir.