# Genel Bakış

> Tecof geliştirici platformuna genel bakış — tema, uygulama, CLI, API ve AI yüzeyleri, hangi yoldan başlanacağı, kimlik doğrulama katmanları ve ortam değişkenleri.
>
> Kaynak: https://tecof-app-dev.vercel.app/getting-started · Bölüm: Başlangıç · Son güncelleme: 2018-10-20

Tecof’ta iki tür şey geliştirirsiniz: mağazanın ziyaretçiye görünen **teması** (Next.js + Tecof Studio) ve mağaza panelinde çalışan **uygulamalar** (partner uygulamaları). İkisi de `@tecof/cli` ile terminalden geliştirilir, numaralı sürümlerle yayınlanır ve anında geri alınabilir. Bu doküman sitesi bu işlerin tamamının tek kaynağıdır; içerik kaynak koda göre yazılır ve her sayfa AI araçları için Markdown olarak da sunulur.

## Nereden başlamalı

| Yapmak istediğiniz | Başlangıç | Sonra |
| :--- | :--- | :--- |
| Mağazanın temasını kodla değiştirmek | [Tema hızlı başlangıç](/theme-quickstart) | [Tema mimarisi](/storefronts), [Tecof Studio](/theme-editor) |
| Temaya Studio’da düzenlenebilir bileşen eklemek | [Bileşen yapılandırması](/editor-components) | [Alanlar](/editor-fields), [Slotlar](/editor-slots), [Stil editörü](/editor-styles) |
| Mağazalara kurulan bir uygulama yazmak | [Uygulama hızlı başlangıç](/app-quickstart) | [Tasarım kimliği](/app-ui), [Webhook’lar](/app-webhooks), [App Bridge](/app-bridge) |
| Vitrin verisini kendi önyüzünüzde kullanmak | [Public API](/public-apis) | [Headless CMS](/headless-cms) |
| Bir AI ajanını Tecof’a bağlamak | [Tecof MCP](/mcp) | [Dokümanı AI ile kullanın](/ai-docs), [Alışveriş ajanları](/agents) |
| CI’dan yayın yapmak | [Güvenlik ve CI](/dev-security) | [CLI başvurusu](/cli-reference) |
| Paket sürümlerini görmek | [Paketler](/packages) | — |

## Platform yüzeyleri

### Tema ve vitrin

Temalar Next.js App Router projeleridir. Sayfa verisini, CMS içeriğini, mağaza ayarlarını ve e-ticaret verisini backend’in `/api/store/*` katmanından vitrin anahtarıyla (`x-secret-key`) okur; sayfaları `@tecof/theme-editor`’ün `TecofRender`’ı ile çizer. Panel aynı sayfaları temanın editör rotasında **Tecof Studio** ile düzenletir. Özel temanın kodu bir **Space**’te yaşar: `tecof theme push` yalnız değişen dosyaları yükleyip staged bir sürüm açar, `tecof theme promote` onu yeniden derlemeden canlıya alır ([Spaces](/spaces)).

### Partner uygulamaları

Uygulamalar mağazaya kurulur; istemci kimliği + sırrıyla alınan kurulum token’ı (`tcfi_…`) ile `/api/v1`’i kullanır, imzalı webhook’lar ve panel aksiyonları alır, panelde iframe içinde `@tecof/app-ui` ile Tecof görünümünde çalışır, ayarlarını Vault ve metafield’larda tutar ve ücretli planlar sunabilir ([Uygulama geliştirme](/app-development)).

### Vitrin ve CMS API’leri

Canlı mağazanın güvenli API yüzeyi `/api/store/*` altındadır: ürün listesi, sepet doğrulama, checkout, müşteri hesabı, CMS okuma, bülten ve tema render verisi ([Public API](/public-apis)). Panel (yönetim) uçları `/api/merchant/*` altında JWT ile korunur ve panel içindir; üçüncü taraflar `/api/v1` kullanır.

### AI ve MCP

Tecof’un uzak MCP sunucusu (`https://api.tecof.com/mcp`) mağaza verisini, sayfaları, CMS’i, ürünleri ve tema kodunu kapsamlı yetkilerle ajanlara açar; `@tecof/mcp` aynı araçları tema reposunun içinden sunar ([Tecof MCP](/mcp)). Mağazalar ayrıca AI arama motorları için `llms.txt` ve `/ai/*.json` dosyaları yayınlar ([GEO: AI Storefront](/ai-storefront)).

## Kimlik doğrulama modeli

| Katman | Kullanım | Kimlik doğrulama |
| :--- | :--- | :--- |
| Vitrin (okuma ve güvenli yazma) | Canlı tema, ürün, CMS, checkout | `x-secret-key` |
| Müşteri hesabı | Profil, adres, siparişler, yorum/favori | `x-secret-key` + müşteri `Authorization` |
| Tema editörü yazma | Sayfa kaydetme, yükleme, ortak bileşen | `x-secret-key` + mağaza/ekip JWT’si |
| Panel (yönetim) | Satıcı paneli ve yönetim API’leri | JWT, rol/ekip yetkisi |
| Analytics toplama | Vitrin olayları | Public `merchantId` |
| Partner uygulaması (sunucu) | Kurulu uygulamanın `/api/v1` çağrıları | `Authorization: Bearer tcfi_…` (kurulum token’ı) |
| Partner uygulaması (iframe) | Panel içindeki uygulama arayüzü → uygulama sunucusu | 60 sn’lik oturum JWT’si (App Bridge) |
| CLI ve CI | Spaces, push, promote, rollback | Cihaz akışı token’ı (`tcfd_…`) ya da kapsamlı CI token’ı (`TECOF_TOKEN`) |
| MCP | Ajanların mağaza araçları | OAuth 2.1 ya da kişisel erişim anahtarı (`tcf_…`) |

`NEXT_PUBLIC_MERCHANT_SECRET_KEY` temanın public bundle’ında bulunur. Bu yüzden backend, yazma yetkisi gerektiren editör işlemlerinde ayrıca JWT ister; taslak önizleme de imzalı `previewToken` ister.

## Ortam değişkenleri

Tema projelerinin temel değişkenleri (`tecof theme dev` bunları `.env.local` dosyasına yazar):

```dotenv title=".env.local"
NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id
```

`tecof-theme-core` bu değerlerle `/api/store/render`, `/api/store/merchant-info`, `/api/store/pages` ve `/api/store/ecommerce/*` uçlarını çağırır. Uygulama projelerinin değişkenleri (`TECOF_CLIENT_ID`, `TECOF_CLIENT_SECRET`, `TECOF_API_URL`) [uygulama hızlı başlangıçta](/app-quickstart#ortam-degiskenleri).

## Doğruluk notu

Bu belgeler kaynak koda göre yazılır: `tecof-app-backend` (API sözleşmeleri), `tecof-theme-core` (tema runtime’ı), `tecof-theme-editor` (Studio ve renderer), `tecof-app-sdk` (CLI, uygulama paketleri) ve `tecof-mcp`. Mevcut kodda doğrulanan yol REST tabanlı `/api/store/*`, `/api/v1` ve MCP sözleşmeleridir; GraphQL ya da ayrı bir storefront SDK’sı birincil yol değildir. Henüz kodda olmayan özellikler “plan” olarak belirtilir. Bir çelişki görürseniz paketlerin gerçek tip tanımları ve API yanıtları son doğruluk kaynağıdır.