Mimari Öz

Müşteri, görev ve sayaç takibi için yerinde çalışan, tek sayfa takip uygulaması.

Demo CRM, küçük ekiplerin müşterilerini, onlara ait görevleri ve kısa sayaçlarını tek bir sade arayüzden yönetmesini sağlar. Mimari, bağımsız çalışan üç modül (Musteriler, Gorevler, Sayac) ile bunları taşıyan ortak bir teknoloji tabanına dayanır. Veriler yerinde tutulur; uygulamanın kendisi dışında dış servis bağımlılığı yoktur.

Yayında olan sürüm cfceea7, görev açılır penceresindeki (popup) müşteri alanının panelde seçili müşteri filtresiyle dolu açılmasını içerir: filtre "Tümü" ise alan boş açılır; mevcut görevi düzenleme akışı değişmez. Değişiklik yalnızca arayüz katmanındadır; veri ve API sözleşmeleri aynen korunur. Arayüz, Fira yerel font yığınını ve mavi paleti esas alan tasarım sistemiyle (MASTER.md) uyumludur. Bu doküman, güncel mimari ve tasarım kararlarını tek yerden sunar.

Ön yüzVanilla JS (tek sayfa)

Arka yüzFastAPI

ORMSQLAlchemy 2.0 (sync)

VeritabanıSQLite (WAL)

DoğrulamaPydantic v2

Modüller3 + ortak temel

OrtamProd (port 8204)

Yayın sürümücfceea7

DurumYayında · kontrol tamam

Temel mimari kararlar

Her modül kendi bağımsız akışında çalışır; modüller arası bağımlılık yalnızca ortak ORM ve Pydantic sözleşmesiyle kurulur.
Yerinde (local-first) çalışma: tek dosya SQLite, dış CDN ve harici font bağımlılığı yoktur.
REST API, modül bazında /api/musteriler, /api/gorevler ve /api/sayac kökleriyle ayrılır.
Arayüz, tasarım sistemi MASTER.md'deki Fira yerel font yığını ve mavi paletiyle düz (flat) bir görünüme yenilenmiştir.
Arayüz, sol müşteri adres defteri + sağ çalışma panelini birleştiren master-detail düzenine ve not düzenleme penceresine (1a6cc84) taşınmıştır.

02

Modüler Yapı

Ürün üç iş modülü ve onları taşıyan bir ortak temel katmanından oluşur.

Musteriler

Müşteri kayıtlarının oluşturulması, listelenmesi, filtrelenmesi ve güncellenmesi.

CRUD uçları + Pydantic doğrulama
ORM: musteriler tablosu
İletişim alanları + not (2000 karakter)

Gorevler

Müşterilere bağlı takipli görevler; vade ve durum takibi.

CRUD + durum güncelleme (PATCH)
ORM: takip_gorevleri tablosu
durum: acik · tamamlandi (vars. acik)

Sayac

Kısa özet sayaçları; her istekte kaynaktan taze hesaplanır.

Yalnız GET uç noktası
Önbellek yok — değerler DB'den türetilir
toplam_musteri · gecikmis_gorev · bu_ay_eklenen

Ortak temel ve veri akışı

Katman	Görev	Teknoloji
Uç nokta	HTTP isteğini karşılar, doğrular, ORM'e yönlendirir	FastAPI router'ları
Doğrulama	Giriş/çıktı şemalarını kontrol eder	Pydantic v2
ORM / model	Veri tabanı şeması ve sorguları	SQLAlchemy 2.0 (sync)
Depolama	Yerinde kalıcı veri	SQLite (WAL)
Arayüz	Müşteri + görev çalışma alanını master-detail tek sayfada sunar	Vanilla JS (tek sayfa)

Veri akışı: Arayüz → REST uç noktası → Pydantic doğrulama → ORM → SQLite → aynı zincirle geri. Modüller birbirine doğrudan referans vermez; bağlantı yalnızca musteri_id dış anahtarı ve ortak şemalar üzerinden kurulur.

03

Veri Modeli

İki tablo; ilişkiler, bütünlük ve doğrulama kuralları.

Tablolar ve alanlar

Tablo	Alan	Tip	Açıklama
musteriler	id	INTEGER	PK, otomatik artan
	ad	VARCHAR(200)	Gerekli
	firma	VARCHAR(200)	İsteğe bağlı
	telefon	VARCHAR(30)	İsteğe bağlı
	eposta	VARCHAR(200)	İsteğe bağlı (pratik biçim: doluysa `@`)
	not	TEXT	İsteğe bağlı (en fazla 2000 karakter)
	created_at	DATETIME	UTC; sayaçların (bu_ay_eklenen) tek kaynağı
takip_gorevleri	id	INTEGER	PK, otomatik artan
	baslik	VARCHAR(200)	Gerekli
	vade	DATE	Gerekli (YYYY-MM-DD, gün çözünürlüğü)
	durum	ENUM	acik · tamamlandi (varsayılan: acik)
	musteri_id	INTEGER	FK → musteriler.id, ON DELETE CASCADE (gerekli)
	created_at	DATETIME	UTC; görev sıralama eşitliği için

not alanı sözleşmede not olarak kalır (Python'da anahtar kelime olduğundan ORM içinde notu olarak tutulur; JSON'da not). gecikmis kayıtlı bir alan değil, türetilmiş bir durumdur: durum = acik ve vade bugünden önce ise.

İlişkiler ve bütünlük

Bir müşteri (musteriler) birden çok görev (takip_gorevleri) içerebilir — 1'e N.
Görev, musteri_id dış anahtarıyla müşteriye bağlanır.
Müşteri silinince bağlı görevler de silinir (FK ON DELETE CASCADE).

Doğrulama (Pydantic v2)

Giriş ve çıktı her iki uçta Pydantic şemalarıyla doğrulanır.
Görev durum alanı enum sınırlamasına tabidir (acik / tamamlandi).
eposta doluysa pratik biçim (@) kontrolünden, zorunlu metinler boş kontrolünden geçirilir.

04

API Sözleşmesi

REST uç noktaları, yöntemler ve dönen durum kodları.

Uç noktalar

Yöntem	Yol	Gövde / parametre	Dönüş
POST	/api/musteriler	ad, firma, telefon, eposta, not	201 · müşteri
GET	/api/musteriler	`?arama=` · `?firma=` (AND)	200 · müşteri listesi (sıra: ad)
PATCH	/api/musteriler/{id}	gönderilen alanlar	200 · güncellenmiş müşteri
DELETE	/api/musteriler/{id}	—	204 · bağlı görevler de silinir
POST	/api/gorevler	baslik, vade, durum, musteri_id	201 · görev
GET	/api/gorevler	`?musteri_id=` · `?gecikmis=` (AND)	200 · görev listesi (sıra: vade)
PATCH	/api/gorevler/{id}	gönderilen alanlar	200 · güncellenmiş görev
DELETE	/api/gorevler/{id}	—	204
GET	/api/sayac	—	200 · `{toplam_musteri, gecikmis_gorev, bu_ay_eklenen}`
GET	/api/health	—	200 · `{status, env, app}`

Güncelleme işlemleri PATCH (kısmi güncelleme) kullanır; tam gövde beklenmez (PUT yok). Gönderilmeyen alan değişmez, null "boş yaz" anlamındadır (zorunlu alanda null → 422). Filtreler: arama (ad/firma/telefon/eposta, duyarlı değil), firma (tam eşleşme), gecikmis (durum=acik ve vade bugünden önce). Liste uçları en fazla 100 kayıt döndürür. Hata kodları: 404 bulunamadı, 422 doğrulama.

05

ADR Kararları

Architecture Decision Record — mimari belgedeki altı kabul edilen karar.

ADR-1

Tek süreç: FastAPI + SQLAlchemy 2.0 + SQLite WAL

KararTek süreç (uvicorn), tek DB dosyası/ortam, SQLAlchemy 2.0 ORM ve SQLite WAL ile çalışma.

GerekçeTek kullanıcılı yerel kapsamda ham SQL veya çoklu süreç gereksiz karmaşıklık yaratırdı; NFR-1 stack birebir uygulanır.

AlternatiflerHam SQL (soyutlama az), çok süreç (yerel ölçekte gereksiz).

DurumKabul edildi

ADR-2

`not` alanı: Python `notu` / SQL `"not"` / JSON `not`

KararSözleşme adı not korunur; Python anahtar kelimesi çakışması iç isimle (notu) çözülür.

GerekçeAPI yüzeyi SRS'teki not adından sapmaz; yalnızca iç Python adı ayrıdır.

AlternatiflerJSON alanını notu yapmak (SRS sözleşmesinden sapma).

DurumKabul edildi

ADR-3

Giriş noktası: `server.py` modülü + kök shim

KararKod src/minimax_clean/server.py içinde DevOps ile aynı bayrak sözleşmesini (--env/--root/--host/--port) taşır; python -m minimax_clean.server ile çalışır.

GerekçeKartın izinli yolları docs/architecture + src ile sınırlıdır; kök dosya eklenmez. DevOps APP_CMD uyumu (kök shim ya da python -m) DevOps/PM'de hizalanır.

DurumKabul edildi (şartlı)

ADR-4

PATCH: `exclude_unset` + `null` = "boş yaz"

KararPATCH üç hâli — gönderilmedi, null, boş metin — tek kodda ayrıştırılır; zorunlu alanda null 422 döner.

GerekçeKısmi güncelleme SRS'in üçlü davranışını karşılar; tam gövde (PUT) gerekmez.

AlternatiflerTam gövde PUT (SRS'te tanımlı değil).

DurumKabul edildi

ADR-5

Bütünlük: FK `ON DELETE CASCADE` + ORM delete-orphan

KararMüşteri silinince görevlerin silinmesi iki katmanda sağlanır (DB FK + ORM); PRAGMA foreign_keys=ON bağlantı olayında.

GerekçeTek katman eksik bırakılsa bile diğer katman korur; kurallı davranış kodla tekrar tanımlanmaz.

AlternatiflerUygulama katmanında elle silme (bütünlük kuralını tekrar yazar).

DurumKabul edildi

ADR-6

Şema: `create_all` iskelet evresi

KararIskelet evresinde create_all yeterli (boş DB); ileride şema değişimi gerekirse DEV kartı göç stratejisini ayrı ADR ile devralır.

Gerekçeİskelette göç kütüphanesi kurmak kapsam darlığı gereği gereksizdir.

DurumKabul edildi

06

DevOps Girdisi

Tek süreç, tek komutla çalıştırma; ortam ve sağlık kontrolü.

Çalışma ve dağıtım girdileri

Girdi	Açıklama	Port
server.py	Giriş noktası; `--env/--root/--host/--port` bayrakları (DevOps APP_CMD sözleşmesi)	8204
minimax_clean.db	Tek SQLite dosyası (WAL); kök dizinde	—
static/index.html	Tek sayfa arayüz (Vanilla JS); sunucu tarafından servis edilir	—
/api/health	Sağlık kontrolü uç noktası (`{status, env, app}`)	—
.env	Ortam değişkenleri (`ENV=dev\|prod`, `ROOT_DIR`, `PORT`)	—

Kurulum ve çalıştırma

Yerinde geliştirme tek komutla başlar; aynı kod ENV=prod ile yayında çalışır. Konteyner zorunlu değildir — tek süreç ve tek DB dosyası yeterlidir.

# yerinde çalıştır (dev)
ENV=dev PORT=8204 ROOT_DIR=. \
  python -m minimax_clean.server

# paket giriş noktası (aynı bayraklar)
minimax-clean # → minimax_clean.server:main

Yayın durumu

OrtamProd (port 8204)

Yayın sürümücfceea7

Sağlık kontrolüstatus: ok

İzlemeKritik hata yok

07

Tasarım Sistemi

Yayındaki cfceea7 sürümünün görsel yönü — master-detail çalışma alanı, görev ve not düzenleme pencereleri, Fira yerel fontlar ve mavi palet.

Arayüz, tasarım sistemi design-system/minimax-clean-crm/MASTER.md kaynağıyla tanımlanır. Tasarım düz (flat) bir görünüme dayanır: kenarlık + hafif gölge, yumuşak köşe, tek vurgu rengi. Dış CDN ve emoji ikonu kullanılmaz; fontlar yerel yığınla yüklenir, ikonlar satır içi SVG'dir. Yayındaki düzen, master-detail çalışma alanıdır (örnek-4-focus referansı) ve not düzenleme penceresi (örnek-7 referansı) eklenmiştir.

Yerleşim (master-detail)

Çalışma alanı

Sol: müşteri adres defteri — listeleme, arama ve firma filtresiyle gezinme aracı.
Sağ: seçili müşterinin çalışma paneli — iletişim, not ve bağlı görevler + görev formu.
Müşteri seçilince sağ panel yüklenir; seçim listelemeden değil panelden yapılır.

Görev satırı ve not penceresi

Görev satırı: başlık, vade, durum rozeti (acik / tamamlandi / gecikmis), durum değiştirme ve silme.
Gecikme türetilir: durum = acik ve vade geçmiş ise satır "gecikmis" rozetiyle işaretlenir.
Not düzenleme, örnek-7 referansındaki düzenleme penceresi (popup) üzerinden yapılır.
Yeni görev penceresi, panelde seçili müşteri filtresiyle dolu açılır: filtre "Tümü" ise müşteri alanı boş açılır; düzenleme penceresi değişmez.

Duyarlı davranış: dar ekranlarda iki sütun dikeye iner; 375 / 768 / 1280 genişliklerinde taşma yoktur.

Renk paleti

Primary

#2563EB

Accent

#059669

Background

#F8FAFC

Foreground

#0F172A

Card

#FFFFFF

Border

#E4ECFC

Brand soft

#DBEAFE

Destructive

#DC2626

OK

#16A34A

Warn (gecikmis)

#D97706

Tipografi (yerel yığın)

Gövde: Fira Sans → system-ui → Segoe UI.
Başlık: Fira Code → ui-monospace → Consolas.
Harici (CDN) font yoktur; hepsi sistemden çözülür.

Bileşen dili

Kenarlık + hafif gölge, 10px köşe yuvarlaması, 160ms geçiş.
Ikonlar satır içi SVG; emoji kullanılmaz.
Duyarlı: 375 / 768 / 1280 genişliklerde taşma yok.

Mimari Öz

Temel mimari kararlar

Modüler Yapı

Musteriler

Gorevler

Sayac

Ortak temel ve veri akışı

Veri Modeli

Tablolar ve alanlar

İlişkiler ve bütünlük

Doğrulama (Pydantic v2)

API Sözleşmesi

Uç noktalar

ADR Kararları

Tek süreç: FastAPI + SQLAlchemy 2.0 + SQLite WAL

not alanı: Python notu / SQL "not" / JSON not

Giriş noktası: server.py modülü + kök shim

PATCH: exclude_unset + null = "boş yaz"

Bütünlük: FK ON DELETE CASCADE + ORM delete-orphan

Şema: create_all iskelet evresi

DevOps Girdisi

Çalışma ve dağıtım girdileri

Kurulum ve çalıştırma

Yayın durumu

Tasarım Sistemi

Yerleşim (master-detail)

Çalışma alanı

Görev satırı ve not penceresi

Renk paleti

Tipografi (yerel yığın)

Bileşen dili

`not` alanı: Python `notu` / SQL `"not"` / JSON `not`

Giriş noktası: `server.py` modülü + kök shim

PATCH: `exclude_unset` + `null` = "boş yaz"

Bütünlük: FK `ON DELETE CASCADE` + ORM delete-orphan

Şema: `create_all` iskelet evresi