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ış
• Dizin Yapısı
• Frontend Mimarisi
• Backend Mimarisi
• Veri Akışı
• 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:

// 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:

// 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

// 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.