Pathify - Visual Roadmap & Progress Tracker

Temel Kavramlar

Pathify Teknik Mimarisi

Pathify, öğrenme basamaklarını ve kişisel gelişim hedeflerini yönlü çizge (DAG) ağları üzerinden görselleştiren ve adım adım takip etmeyi sağlayan modern bir full-stack platformdur.

Next.js 14 + React Flow

Etkileşimli tuval, dokunmatik jestler ve reaktif düğüm kartları.

Golang + Clean Architecture

Gin web motoru, yüksek performanslı ve önkoşul korumalı servis katmanı.

i18n & Mobile PWA

Dinamik TR/EN dil seçimi, iOS safe-area ve ana ekrana yüklenebilir PWA.

Proje Dizin Yapısı & Veri Akışı

Backend katmanı Clean Architecture standartlarına göre ayrılmıştır: HTTP Handler gelen istekleri karşılar, Service katmanı önkoşul ve harita kurallarını işletir, Repository ise veriyi soyutlar.

pathify/
├── backend/                  # Golang Clean Architecture API
│   ├── cmd/api/main.go       # HTTP Sunucu & Seed Loader
│   ├── internal/
│   │   ├── domain/           # Roadmap, Node, Edge & User Structs
│   │   ├── handler/http/     # Gin REST Endpoints
│   │   ├── service/          # Prerequisite Validation Engine
│   │   └── repository/       # Data Access Layer
│   └── seeds/                # Seed JSON Roadmaps (Frontend, Golang vb.)
│
├── frontend/                 # Next.js 14 App Router
│   ├── app/                  # layout.tsx, page.tsx, globals.css, docs/
│   ├── components/
│   │   ├── roadmap/          # RoadmapCanvas, RoadmapNode, NodeDetailDrawer
│   │   ├── auth/             # AuthModal
│   │   └── ui/               # LanguageSwitcher, CustomSelect
│   └── lib/
│       ├── api.ts            # Fetch HTTP Client
│       └── i18n/             # Translations & LanguageContext
│
└── docker-compose.yml        # Multi-Container Orchestration

Önkoşul (Prerequisite) Doğrulama Motoru

Bir düğümün IN_PROGRESS veya COMPLETED durumuna geçebilmesi için, ona bağlanan zorunlu (is_requirement=true) önceki düğümlerin COMPLETED olması gerekir. Aksi halde servis işlemi engelleyerek kullanıcıya adım sırasını korumasını bildirir.

💡 Kural: Hedef düğüm, kendisine bağlı olan tüm zorunlu önceki adımlar tamamlanmadan başlatılamaz.

REST API Referansı (/api/v1)

GET/api/v1/health

Sistem durumunu denetleyen servis sağlık kontrol noktası.

{ "status": "ok", "time": "2026-09-20T19:00:00Z" }

GET/api/v1/roadmaps

Sistemdeki tüm şablon ve kullanıcı haritalarını listeler.

GET/api/v1/roadmaps/:idOrSlug

Haritaya ait tüm düğümleri, koordinatları, kontrol listelerini ve kullanıcı ilerlemesini döner.

PUT/api/v1/roadmaps/:idOrSlug/nodes/:nodeId/progress

Belirli bir adımın durumunu (COMPLETED/IN_PROGRESS), hedeflerini ve notlarını günceller.

// Request Payload
{
  "status": "COMPLETED",
  "completed_checklists": ["chk-1", "chk-2"],
  "notes": "Konu özetleri ve pratik uygulamalar tamamlandı."
}

POST/api/v1/auth/register & /api/v1/auth/login

Kullanıcı kaydı ve girişi uç noktaları. Başarılı işlem sonucunda JWT Bearer Token döner. Ayrıca web uygulamasındaki Profil menünüzden otomasyonlarınız için kalıcı API anahtarları oluşturabilir ve silebilirsiniz.

// 1. POST /api/v1/auth/login
{
  "email": "demo@pathify.dev",
  "password": "demo123"
}

// Response (200 OK)
{
  "message": "Giriş başarılı",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": { "id": "00000000-0000-0000-0000-000000000001", "email": "demo@pathify.dev" }
  }
}

POST/api/v1/roadmapsAuth Required

Düğümler ve bağlantılar içeren yeni bir yol haritası oluşturur. Authorization: Bearer <TOKEN> başlığı gereklidir.

// Headers
// Authorization: Bearer <JWT_TOKEN>
// Content-Type: application/json

// Request Body
{
  "title": "Rust ve WebAssembly Uzmanlığı",
  "category": "Yazılım Geliştirme",
  "description": "Sıfırdan ileri seviyeye modern sistem ve Wasm programlama",
  "nodes": [
    {
      "id": "node-1",
      "title": "1. Rust Temelleri ve Bellek Güvenliği",
      "description": "Ownership, Borrowing ve Lifetimes kavramları",
      "position": { "x": 280, "y": 50 },
      "type": "customRoadmapNode",
      "metadata": {
        "estimated_hours": 15,
        "checklists": [
          { "id": "chk-1", "text": "Rust Toolchain (rustup, cargo) kurulumu" },
          { "id": "chk-2", "text": "Ownership ve Borrow Checker kurallarını öğren" }
        ],
        "resources": [
          { "title": "The Rust Book", "url": "https://doc.rust-lang.org/book/", "type": "doc" }
        ]
      }
    },
    {
      "id": "node-2",
      "title": "2. WebAssembly ve wasm-bindgen",
      "description": "Rust kodunu tarayıcı ortamında yüksek performansla çalıştırma",
      "position": { "x": 280, "y": 220 },
      "type": "customRoadmapNode",
      "metadata": {
        "estimated_hours": 20,
        "checklists": [
          { "id": "chk-3", "text": "wasm-pack ve Node/Browser bağlayıcıları" }
        ]
      }
    }
  ],
  "edges": [
    {
      "id": "e-node-1-node-2",
      "source": "node-1",
      "target": "node-2",
      "type": "smoothstep",
      "is_requirement": true
    }
  ]
}

Mobil & iOS / Android PWA Standartları

Uygulama dinamik ekran yüksekliği (100dvh) ve CSS safe-area değişkenleri sayesinde iPhone Dynamic Island, çentik ve Android ekranlarında tarayıcı adres çubuğu hareketlerinden etkilenmeden tam ekran çalışır.

Docker ile Tek Komutta Çalıştırma

docker compose up --build