main

mds/deploy.md

@@ -1,76 +1,81 @@
-🏗️ Backend Altyapı Kurulum Rehberi (Database & Redis)
+🚀 Raspberry Pi Proje Dağıtım Rehberi (Checklist)
-Bu doküman, Raspberry Pi üzerinde yeni bir Backend projesi için gerekli olan kalıcı veritabanı ve Redis servislerinin nasıl kurulacağını anlatır.
+Bu rehber, mevcut merkezi altyapıyı (Gitea, Runner, Central Database, Nginx) kullanarak yeni NestJS (Backend) ve Next.js (Frontend) projelerini nasıl ayağa kaldıracağını adım adım açıklar.
-
+🏗 1. Altyapı Hazırlığı (Infrastructure)
-⚠️ Mantık: Bu servisler deploy sürecine dahil EDİLMEZ. Sunucuda bir kere kurulur, verileri kalıcı olarak saklar ve Backend projesi buraya bağlanır.
+A. Veritabanı Oluşturma
-
+Her yeni proje için merkezi PostgreSQL konteynerinde yeni bir veritabanı açılmalıdır.
-1. Hazırlık: Docker Ağı Kontrolü
+code
-Tüm servislerin (Gitea, App, DB, Redis) birbirini görebilmesi için ortak bir ağda olmaları gerekir.
-
 Bash
-# Ağ var mı kontrol et (Listede 'gitea' yazmalı)
+# PROJE_ADI kısmını küçük harf ve boşluksuz yaz (örn: e_ticaret_db)
-docker network ls
+docker exec -it backend_db createdb -U 'Rub1c0N-UseR.!' PROJE_ADI_db
-
+B. DNS Ayarları
-# Yoksa oluştur:
+Domain panelinden (Cloudflare vb.) yeni subdomain'leri Raspberry Pi'nin dış IP'sine yönlendir:
-docker network create gitea
+api-proje.bilgich.com -> Raspberry Pi IP
-2. PostgreSQL Veritabanı Kurulumu (Kalıcı)
+ui-proje.bilgich.com -> Raspberry Pi IP
-Her yeni proje için port çakışması yaşamamak adına konteyner ismini ve volume ismini projeye özel değiştir.
+🔐 2. Gitea Secret Ayarları
-
+Gitea reponuzda Settings > Actions > Secrets yolunu izleyerek aşağıdaki anahtarları tanımlayın.
-Değiştirilecek Yerler: proje-db-ismi, DB_KULLANICI, DB_SIFRE, DB_ADI
+Backend İçin:
-
+Key	Value Örneği
+DATABASE_URL	postgresql://Rub1c0N-UseR.%21:SIFRE%3D@backend_db:5432/PROJE_ADI_db?schema=public
+JWT_SECRET	en_az_32_karakterli_rastgele_string
+Frontend İçin:
+Key	Value Örneği
+NEXT_PUBLIC_API_URL	http://api-proje.bilgich.com/api
+NEXTAUTH_URL	http://ui-proje.bilgich.com
+NEXTAUTH_SECRET	openssl_rand_base64_32_cikti
+Not: DATABASE_URL içinde özel karakter varsa: ! -> %21, = -> %3D kullanmayı unutma.
+🛠 3. Backend (NestJS) Proje Ayarları
+main.ts: Global prefix ve Swagger yollarını kontrol et.
+Dockerfile: Mevcut çalışan NestJS Dockerfile'ı kullan.
+deploy.yml Değişiklikleri:
+--name backend-PROJE-container (Unique isim)
+-p 150X:3000 (Sıradaki boş port: 1502, 1503...)
+--network gitea-server_gitea (Doğru network adı)
+🎨 4. Frontend (Next.js) Proje Ayarları
+next.config.js: output: 'standalone' satırını ekle.
+Dockerfile: ARG ve ENV satırlarına NEXT_PUBLIC_ değişkenlerini ekle.
+deploy-ui.yml Değişiklikleri:
+--build-arg ile tüm Gitea secret'larını build aşamasına geç.
+--name ui-PROJE-container (Unique isim)
+-p 180X:3000 (Sıradaki boş port: 1801, 1802...)
+-e NEXTAUTH_URL ve NEXTAUTH_SECRET runtime değişkenlerini ekle.
+🚦 5. Nginx Yönlendirmesi
+Her servis için yeni bir Nginx konfigürasyonu oluşturulmalıdır.
+Dosya Oluştur:
+code
 Bash
-docker run -d \
+sudo nano /etc/nginx/sites-available/proje-api  # Backend için
-  --name proje-adi-postgres \
+sudo nano /etc/nginx/sites-available/proje-ui   # Frontend için
-  --restart always \
+Config İçeriği (Örnek):
-  --network gitea \
+code
-  -e POSTGRES_USER=db_kullanici \
+Nginx
-  -e POSTGRES_PASSWORD=cok_guclu_sifre \
+server {
-  -e POSTGRES_DB=proje_db_adi \
+    listen 80;
-  -v proje_adi_db_data:/var/lib/postgresql/data \
+    server_name api-proje.bilgich.com;
-  postgres:16-alpine
+    location / {
-Not: -p (Port) parametresi eklemedik. Çünkü dış dünyaya kapalı olsun, sadece bizim uygulamamız (aynı ağdaki) erişebilsin istiyoruz. Güvenlik için en iyisi budur.
+        proxy_pass http://127.0.0.1:150X; # Uygulamanın dış portu
-
+        include proxy_params; # Veya standart proxy headerları
-3. Redis Kurulumu (Kalıcı)
+    }
-Redis için de projeye özel bir isim veriyoruz.
+}
-
+Aktif Et ve Reload:
+code
 Bash
-docker run -d \
+sudo ln -s /etc/nginx/sites-available/proje-api /etc/nginx/sites-enabled/
-  --name proje-adi-redis \
+sudo nginx -t && sudo systemctl reload nginx
-  --restart always \
+💡 "Senior" İpuçları & Bakım
-  --network gitea \
+Port Yönetimi: Kullandığın portları bir yere not et:
-  -v proje_adi_redis_data:/data \
+1501: Test BE, 1502: Proje2 BE...
-  redis:7-alpine
+1800: Test UI, 1801: Proje2 UI...
-4. Gitea Secrets Ayarları (Bağlantı)
+Disk Temizliği: Raspberry Pi diski dolmaması için haftalık temizlik yap:
-Veritabanlarını kurduktan sonra Gitea'da Ayarlar -> Actions -> Secrets kısmına gidip aşağıdaki bilgileri ekle.
+code
-
-🔑 Secret 1: DATABASE_URL
-Uygulamanın veritabanını bulması için gerekli bağlantı cümlesi.
-
-Format: postgresql://KULLANICI:SIFRE@KONTEYNER_ADI:5432/DB_ADI?schema=public
-
-Örnek (Yukarıdaki kuruluma göre): postgresql://db_kullanici:cok_guclu_sifre@proje-adi-postgres:5432/proje_db_adi?schema=public
-
-Dikkat: localhost veya IP yerine direkt kurduğun konteyner ismini (proje-adi-postgres) yazıyoruz. Docker isimden tanır.
-
-🔑 Secret 2: REDIS_HOST
-Uygulamanın Redis'i bulması için.
-
-Değer: proje-adi-redis
-
-
-5. Sorun Giderme (Debug)
-Eğer bağlantı hatası alırsan şu komutlarla kontrol et:
-
-Veritabanı ayakta mı?
-
 Bash
-docker ps | grep postgres
+docker system prune -f
-Veritabanı loglarını incele:
+Performans İzleme: RAM ve CPU durumunu kontrol et:
-
+code
 Bash
-docker logs --tail 50 proje-adi-postgres
+htop
-Veritabanını sıfırlamak (Silip baştan kurmak) istersen:
+docker stats
-
+Log Takibi: Bir sorun olduğunda ilk buraya bak:
+code
 Bash
-# DİKKAT: TÜM VERİ SİLİNİR!
+docker logs -f KONTEYNER_ADI
-docker rm -f proje-adi-postgres
+Bu sistem, Raspberry Pi'nin kaynaklarını en verimli şekilde kullanacak şekilde tasarlanmıştır. 🚀
-docker volume rm proje_adi_db_data

mds/learned_protocols.md

@@ -0,0 +1,65 @@
+# Learned Protocols & Standards
+
+This document serves as the persistent memory of the protocols, standards, and personas learned from the `skript-be` and `skript-ui` repositories.
+
+## 1. Frontend Standards (skript-ui)
+
+### Design & Aesthetics (`frontend-design`)
+- **Anti-AI Slop:** Avoid generic, cookie-cutter "AI" aesthetics (e.g., standard purple gradients, predictable layouts).
+- **Boldness:** Commit to a specific aesthetic direction (Minimalist, Brutalist, Magazine, etc.).
+- **Typography:** Use distinctive fonts; avoid system defaults like Arial/Inter unless intentional.
+- **Micro-interactions:** Prioritize one or two high-impact animations over scattered noise.
+- **Creativity:** Use noise textures, gradient meshes, asymmetry, and overlapping elements.
+
+### Architecture (`senior-frontend` & `nextjs-architecture-expert`)
+- **Next.js App Router:** STRICT adherence to App Router patterns (layouts, error.tsx, loading.tsx).
+- **Server Components (RSC):** Default to Server Components. Use Client Components ('use client') only when interactivity is required.
+- **State Management:** component-first thinking; use Context/Zustand for global state, local state for UI.
+- **Performance:** Aim for sub-3s load times. Use `next/image`, code splitting, and lazy loading.
+- **Tailwind CSS:** Use correctly; avoid long string pollution where possible (use utils/cva).
+
+### Quality Assurance (`senior-qa`)
+- **E2E Testing:** Critical flows must be tested.
+- **Coverage:** High unit test coverage for utilities and complex logic.
+
+## 2. Backend Standards (skript-be)
+
+### Code Quality (`code-reviewer`)
+- **Review:** Verify BEFORE implementing.
+- **Simplicity:** No over-engineering.
+- **Security:** No secrets in code. Input validation is mandatory.
+- **YAGNI:** "You Aren't Gonna Need It" - don't build features "just in case".
+
+### Security (`security-engineer` & `api-security-audit`)
+- **Zero Trust:** Verify every request.
+- **OWASP:** Check against Top 10 (Injection, Broken Auth, etc.).
+- **Data:** Validate all inputs using libraries (e.g., Zod, Joi).
+- **Logging:** Sanitize logs (no PII/secrets).
+
+### Database (`database-optimizer`)
+- **N+1:** Watch out for N+1 queries in loops/ORMs.
+- **Indexing:** Index foreign keys and search columns.
+- **Explain:** Check execution plans for complex queries.
+
+### General Engineering
+- **TypeScript:** Strict mode enabled. No `any`. Use generics and utility types (`typescript-pro`).
+- **Feedback:** "Receive Code Review" protocol – technical correctness > polite agreement. Verify suggestions before applying.
+
+### TypeScript Expertise (`typescript-pro`)
+- **Seniority:** I write *Senior-level* code. This means focusing on maintainability, scalability, and robustness, not just "making it work".
+- **Modern Techniques:** I utilize the latest TypeScript features:
+    - **Advanced Types:** Conditional types, Template Literal Types, Mapped Types.
+    - **Utility Types:** `Pick`, `Omit`, `Partial`, `Readonly`, `ReturnType`, `Parameters`, etc.
+    - **Generics:** Proper constraints (`T extends ...`) and defaults.
+    - **Type Inference:** Leveraging inference where clean, explicit typing where necessary for clarity.
+- **Strictness:**
+    - `noImplicitAny` is law.
+    - Avoid `any` at all costs; use `unknown` with type narrowing/guards if dynamic typing is truly needed.
+    - Strict null checks always on.
+- **Architecture:** Value objects, opaque types, and branded types for domain safety.
+
+## 3. Operational Protocols
+
+- **Agent Persona:** I act as the specific specialist required for the task (e.g., if debugging, I am `debugger`; if designing, I am `frontend-developer`).
+- **Proactiveness:** I do not wait for permission to fix obvious bugs or improve clear performace bottlenecks if they are within scope.
+- **Persistence:** These rules apply to ALL future tasks in this session.