Taskflow API

Enterprise-grade, multi-tenant project and task management REST API.

Tech Stack

NestJS · TypeScript · Prisma 6 · PostgreSQL + pgvector · Redis · RabbitMQ · WebSocket · JWT · Docker · AWS · Grafana Cloud + Loki · Claude API

Architecture

Client
  ↓
AWS VPC
  ↓
NestJS API (EC2)
  ↓       ↓           ↓
RDS    ElastiCache  RabbitMQ (EC2)
PG     Redis            ↓
+pgv   Cache +      Mail Service
(RAG)  Rate Limit       ↓
                    Claude API
                        ↓
                    Grafana Cloud

Multi-tenancy: Shared DB, Shared Schema — her tabloda workspaceId. TenantGuard her request'te workspace üyeliğini kontrol eder, request.workspaceMember'a yazar. Controller'lar @CurrentMember() ile okur.

Data Model

User
  └── WorkspaceMember → Workspace
                          ├── ProjectStatus (custom + sistem)
                          ├── TaskStatus    (custom + sistem)
                          ├── Project
                          │     └── Board
                          │           └── Task
                          │                 ├── Comment       → mention'lar Notification'a düşer
                          │                 ├── TaskLabel
                          │                 └── ActivityLog   → status/priority/assignee/comment geçmişi
                          ├── WorkspaceInvite
                          └── AuditLog

Task
  ├── searchVector  (tsvector — full-text search)
  └── embedding     (vector(1536) — RAG/pgvector)

Workspace Rolleri: OWNER · ADMIN · MANAGER · MEMBER

Status Sistemi: Enum yerine tablo — her workspace kendi project ve task status setini özelleştirebilir. isSystem=true olanlar silinemez.

Yorum & Mention Sistemi: Yorumlar @[isim](userId) formatında gömülü mention içerebilir (Slack/Notion tarzı). mention-parser.ts bunları ayrıştırır; sadece workspace'e gerçekten üye olan (ve yorumu yazan kişinin kendisi olmayan) kullanıcılara Notification kaydı oluşturulur — sahte/geçersiz userId'ler veya kendine mention sessizce yok sayılır.

Aktivite Akışı: TasksService.update() çağrısı, statusId/priority/assigneeId değişikliklerini otomatik olarak ActivityLog'a {from, to} metadata'sıyla kaydeder. Yorum eklenince de ayrı bir comment_added aktivitesi düşer. GET /workspaces/:wId/tasks/:tId/activity ile tarih sırasına göre (en yeni üstte) listelenir.

Project Structure

src/
  common/
    decorators/     → @CurrentUser, @CurrentMember, @Public, @Roles
    exceptions/     → BaseException, ErrorCode enum
    filters/        → GlobalExceptionFilter
    guards/         → JwtAuthGuard, TenantGuard
    interceptors/   → LoggingInterceptor, AuditInterceptor
    logger/         → Winston (console + file + daily rotate)
    types/          → TaskflowRequest, AuthenticatedUser
  modules/
    auth/           → JWT, refresh token, httpOnly cookie, 2FA
    users/          → profil, şifre değiştir, hesap sil
    workspaces/     → CRUD, davet sistemi, üye yönetimi, roller, üye arama (mention/assignee autocomplete için)
    projects/       → CRUD + custom status yönetimi
    boards/         → CRUD, sıralama, reorder
    tasks/          → CRUD, atama, öncelik, deadline, sub-task, move, reorder + custom status + aktivite akışı
    labels/         → CRUD, task'a etiket ekle/kaldır
    comments/       → CRUD, mention parsing + bildirim (mention-parser.ts)
    notifications/  → in-app + WebSocket real-time
    ai/             → Claude API, RAG, task asistanı
    analytics/      → big data pipeline, sprint istatistikleri
  prisma/
    prisma.service.ts
    prisma.module.ts
  app.module.ts
  main.ts

prisma/
  _config.prisma
  _enums.prisma       → TaskPriority
  user.prisma         → User, RefreshToken
  workspace.prisma    → Workspace, WorkspaceMember, WorkspaceInvite
  project.prisma      → Project, ProjectStatus
  board.prisma        → Board
  task.prisma         → Task, TaskLabel, TaskStatus
  label.prisma        → Label
  comment.prisma      → Comment
  activity.prisma     → ActivityLog
  notification.prisma → Notification
  audit.prisma        → AuditLog
  migrations/

test/
  app.e2e-spec.ts
  workspace.e2e-spec.ts    → CRUD + cascade delete testi (proje/board/task dolu workspace)
  project.e2e-spec.ts
  board.e2e-spec.ts
  task.e2e-spec.ts
  label.e2e-spec.ts
  comment.e2e-spec.ts      → yorum CRUD, mention bildirimi (2 kullanıcılı senaryo), aktivite akışı, yetki kontrolleri

.husky/
  pre-commit    → npm run lint
  pre-push      → npm test

API Endpoints

Auth

Method	Endpoint	Açıklama
POST	/auth/register	Kayıt
POST	/auth/login	Giriş
POST	/auth/login/2fa	2FA ile giriş
POST	/auth/logout	Çıkış
POST	/auth/refresh	Token yenile
GET	/auth/me	Mevcut kullanıcı
POST	/auth/2fa/enable	2FA aktifleştir
POST	/auth/2fa/verify	2FA doğrula

Users

Method	Endpoint	Açıklama
GET	/users/me	Profil bilgisi
PATCH	/users/me	Profil güncelle
PATCH	/users/me/password	Şifre değiştir
DELETE	/users/me	Hesabı sil

Workspaces

Method	Endpoint	Açıklama
POST	/workspaces	Workspace oluştur
GET	/workspaces	Üye olduğum workspace'ler
GET	/workspaces/:id	Workspace detayı
PATCH	/workspaces/:id	Güncelle
DELETE	/workspaces/:id	Sil (OWNER) — ilişkili tüm veri cascade silinir
POST	/workspaces/:id/invite	Üye davet et
POST	/workspaces/invite/accept/:token	Daveti kabul et
DELETE	/workspaces/:id/members/:userId	Üyeyi çıkar
PATCH	/workspaces/:id/members/:userId/role	Rol değiştir
GET	/workspaces/:id/members/search	Üye ara (mention/assignee autocomplete için)

Projects

Method	Endpoint	Açıklama
POST	/workspaces/:wId/projects	Proje oluştur
GET	/workspaces/:wId/projects	Projeleri listele
GET	/workspaces/:wId/projects/:id	Proje detayı
PATCH	/workspaces/:wId/projects/:id	Güncelle
DELETE	/workspaces/:wId/projects/:id	Sil
GET	/workspaces/:wId/projects/statuses	Status listele
POST	/workspaces/:wId/projects/statuses	Status ekle
PATCH	/workspaces/:wId/projects/statuses/:id	Status güncelle
DELETE	/workspaces/:wId/projects/statuses/:id	Status sil

Boards

Method	Endpoint	Açıklama
POST	/workspaces/:wId/projects/:pId/boards	Board oluştur
GET	/workspaces/:wId/projects/:pId/boards	Board listele
PATCH	/workspaces/:wId/projects/:pId/boards/:id	Güncelle
PATCH	/workspaces/:wId/projects/:pId/boards/reorder	Sırala
DELETE	/workspaces/:wId/projects/:pId/boards/:id	Sil

Tasks

Method	Endpoint	Açıklama
POST	/workspaces/:wId/boards/:bId/tasks	Task oluştur
GET	/workspaces/:wId/boards/:bId/tasks	Task listele
GET	/workspaces/:wId/tasks/:id	Task detayı
GET	/workspaces/:wId/tasks/search?q=	Full-text search
PATCH	/workspaces/:wId/tasks/:id	Güncelle
PATCH	/workspaces/:wId/tasks/:id/move	Board'a taşı
PATCH	/workspaces/:wId/boards/:bId/tasks/reorder	Sırala
DELETE	/workspaces/:wId/tasks/:id	Sil
GET	/workspaces/:wId/tasks/statuses	Status listele
POST	/workspaces/:wId/tasks/statuses	Status ekle
PATCH	/workspaces/:wId/tasks/statuses/:id	Status güncelle
DELETE	/workspaces/:wId/tasks/statuses/:id	Status sil
GET	/workspaces/:wId/tasks/:id/activity	Task aktivite akışı (status/priority/assignee/comment geçmişi)

Labels

Method	Endpoint	Açıklama
POST	/workspaces/:wId/projects/:pId/labels	Label oluştur
GET	/workspaces/:wId/projects/:pId/labels	Label listele
PATCH	/workspaces/:wId/projects/:pId/labels/:id	Güncelle
DELETE	/workspaces/:wId/projects/:pId/labels/:id	Sil
POST	/workspaces/:wId/tasks/:tId/labels/:lId	Task'a ekle
DELETE	/workspaces/:wId/tasks/:tId/labels/:lId	Task'tan kaldır

Comments

Method	Endpoint	Açıklama
POST	/workspaces/:wId/tasks/:tId/comments	Yorum ekle (mention destekli: `@[isim](userId)`)
GET	/workspaces/:wId/tasks/:tId/comments	Yorumları listele
PATCH	/workspaces/:wId/comments/:id	Yorumu düzenle (sadece sahibi)
DELETE	/workspaces/:wId/comments/:id	Yorumu sil (sahibi veya OWNER/ADMIN moderasyon)

Error Response Format

{
  "statusCode": 409,
  "errorCode": "AUTH_002",
  "message": "Email address is already in use",
  "path": "/api/v1/auth/register",
  "method": "POST",
  "timestamp": "2026-07-28T..."
}

Error Codes

Code	Constant	Açıklama
AUTH_001	AUTH_INVALID_CREDENTIALS	Hatalı email/şifre
AUTH_002	AUTH_EMAIL_ALREADY_EXISTS	Email zaten kayıtlı
AUTH_003	AUTH_TOKEN_EXPIRED	JWT süresi dolmuş
AUTH_004	AUTH_TOKEN_INVALID	Geçersiz token
AUTH_005	AUTH_NO_REFRESH_TOKEN	Refresh token yok
AUTH_006	AUTH_2FA_REQUIRED	2FA kodu gerekli
AUTH_007	AUTH_2FA_INVALID_CODE	Hatalı 2FA kodu
WS_001	WORKSPACE_NOT_FOUND	Workspace bulunamadı
WS_002	WORKSPACE_FORBIDDEN	Yetkisiz erişim
WS_003	WORKSPACE_SLUG_TAKEN	Slug kullanımda
WS_004	WORKSPACE_INVITE_INVALID	Geçersiz davet
WS_005	WORKSPACE_INVITE_EXPIRED	Süresi dolmuş davet
PRJ_001	PROJECT_NOT_FOUND	Proje bulunamadı
PRJ_002	PROJECT_FORBIDDEN	Yetkisiz erişim
BOARD_001	BOARD_NOT_FOUND	Board bulunamadı
BOARD_002	BOARD_FORBIDDEN	Yetkisiz erişim
TASK_001	TASK_NOT_FOUND	Task bulunamadı
TASK_002	TASK_FORBIDDEN	Yetkisiz erişim
LBL_001	LABEL_NOT_FOUND	Label bulunamadı
LBL_002	LABEL_FORBIDDEN	Yetkisiz erişim
CMT_001	COMMENT_NOT_FOUND	Yorum bulunamadı
CMT_002	COMMENT_FORBIDDEN	Yetkisiz erişim (sahiplik)
USER_001	USER_NOT_FOUND	Kullanıcı bulunamadı
RATE_001	RATE_LIMIT_EXCEEDED	Çok fazla istek

Environment Variables

# App
NODE_ENV=development
PORT=8000

# Database
DATABASE_URL=postgresql://taskflow:taskflow_pass@localhost:5432/taskflow_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# RabbitMQ
RABBITMQ_URL=amqp://taskflow:taskflow_pass@localhost:5672

# JWT
JWT_SECRET=...
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_SECRET=...
REFRESH_TOKEN_EXPIRES_IN=7d

# Frontend
FRONTEND_URL=http://localhost:3000

# Anthropic
ANTHROPIC_API_KEY=...
ANTHROPIC_MODEL=claude-sonnet-4-6

Development

# Docker servislerini başlat
docker compose up -d

# Migrate
npx prisma migrate dev

# Dev server
npm run start:dev

# Swagger
http://localhost:8000/api/docs

# Unit testler
npm test

# E2E testler (izole test DB)
npm run test:e2e

Test Environment Setup

# Test DB oluştur
docker exec -it taskflow_postgres psql -U taskflow -d taskflow_db -c "CREATE DATABASE taskflow_test_db;"

# Test DB'ye migrate et
DATABASE_URL=postgresql://taskflow:taskflow_pass@localhost:5432/taskflow_test_db npx prisma migrate deploy

# .env.test oluştur
echo "NODE_ENV=test" > .env.test
echo "DATABASE_URL=postgresql://taskflow:taskflow_pass@localhost:5432/taskflow_test_db" >> .env.test

Git Hooks (Husky)

pre-commit → npm run lint — lint hatası varsa commit engellenir
pre-push → npm test — unit testler geçmezse push engellenir
E2E testler hook'lara dahil değil (uzun sürdüğü için), CI/CD'de çalıştırılır

Workspace Oluşturulunca Otomatik Eklenenler

Project Statuses:

Active #22C55E
Completed #6366F1
Archived #6B7280

Task Statuses:

Todo #6B7280
In Progress #3B82F6
In Review #F59E0B
Done #22C55E

Notlar

Workspace Silme — Cascade Sırası

WorkspacesService.remove() workspace'i silerken ilişkili tüm veriyi manuel ve belirli bir sırada siler (Prisma'nın otomatik cascade'ine güvenilmez, çünkü Task.status → TaskStatus ve Project.status → ProjectStatus ilişkilerinde cascade tanımlı değildir — kasıtlı, çünkü tek bir status silinince altındaki task/proje'lerin silinmesi istenmez).

Silme sırası:

ActivityLog → Comment → TaskLabel → Task → Label → Board
  → Project → TaskStatus → ProjectStatus
  → AuditLog → WorkspaceInvite → WorkspaceMember → Workspace

Bu sıra workspace.e2e-spec.ts içindeki "proje/board/task içeren workspace tam olarak silinmeli" testiyle regresyona karşı korunur.

Rate Limiting

@nest-lab/throttler-storage-redis ile Redis-backed rate limiting kullanılıyor — birden fazla instance (production'da ECS ile scale edilince) arasında sayaç tutarlılığı sağlanır. Test ortamında (NODE_ENV=test) throttler devre dışı bırakılır.

Audit Log

AuditInterceptor global olarak tüm POST/PATCH/DELETE isteklerini otomatik loglar — developer hiçbir ek kod yazmaz. before alanı UPDATE/DELETE işlemlerinde DB'den önceden çekilir, after alanı response body'sinden alınır.

Mention Sistemi

Yorumlarda mention, düz @isim metni olarak değil, gömülü @[isim](userId) formatında yazılır (bkz. src/modules/comments/mention-parser.ts). Bu format, kullanıcı adında boşluk/özel karakter olsa bile hangi userId'nin kastedildiğini kesin olarak taşır — regex ile "ismin sonu nerede bitiyor" tahmin etmeye gerek kalmaz. Frontend'de mention autocomplete kullanıcıya sadece @isim gösterir ama arkada bu gömülü formatı yazar (henüz frontend'de yapılmadı, bkz. Bilinen Eksikler).

handleMentions() üç güvenlik kontrolü yapar:

Mention edilen userId gerçekten bu workspace'in bir üyesi mi (sahte ID'lerle bildirim spam'i engellenir)
Yorumu yazan kişi kendini mention etmişse bildirim oluşturulmaz
Aynı kişi birden fazla kez mention edilirse tek bildirim gider (Set ile dedupe)

Bilinen Eksikler / Notlar

2FA devre dışı bırakma: Şu an sadece "aktifleştir" akışı (/auth/2fa/enable + /auth/2fa/verify) var. Kullanıcı authenticator'ı kaybederse veya 2FA'yı kapatmak isterse hiçbir yolu yok. DELETE /auth/2fa (ya da POST /auth/2fa/disable) endpoint'i eklenmesi gerekiyor — henüz yapılmadı, Faz 2'ye not edildi (2.15).
Mention frontend entegrasyonu: Backend @[isim](userId) formatını bekliyor/üretiyor ama frontend'de bunu otomatik yazan bir mention autocomplete (yorum kutusunda @ yazınca üye listesi açılıp seçilince bu formatı ekleyen) henüz yok. GET /workspaces/:id/members/search endpoint'i bu autocomplete için hazır durumda, sadece frontend UI'ı eksik.

Roadmap

Faz 1 — Core ✅

#	Özellik	Durum
1.1	Proje setup — NestJS + Prisma + Docker Compose	✅
1.2	Prisma multi-file schema — tüm modeller + migration	✅
1.3	GlobalExceptionFilter + ErrorCode enum	✅
1.4	LoggingInterceptor	✅
1.5	Custom decorators (@CurrentUser, @CurrentMember, @Public, @Roles)	✅
1.6	Auth — register, login, logout	✅
1.7	Auth — JWT + httpOnly cookie	✅
1.8	Auth — refresh token rotasyonu	✅
1.9	Auth — 2FA (TOTP / Google Authenticator)	✅
1.10	JwtAuthGuard — global guard	✅
1.11	TenantGuard — workspace izolasyonu	✅
1.12	Workspace CRUD	✅
1.13	Workspace davet sistemi (email token)	✅
1.14	Project CRUD + custom status	✅
1.15	Board CRUD + sıralama	✅
1.16	Task CRUD + atama + öncelik + deadline	✅
1.17	Task — sub-task desteği	✅
1.18	Label CRUD + task'a etiket ekleme	✅
1.19	Rate limiting — Redis ile (throttler)	✅
1.20	Audit log — before/after, global interceptor	✅
1.21	Full-text search — task (PostgreSQL tsvector + trigger)	✅
1.22	Winston logger + daily rotate	✅
1.23	Unit testler — Auth, Workspace, Tasks, Boards, Projects, Labels	✅
1.24	E2E testler — auth, workspaces (cascade delete dahil), projects, boards, tasks, labels — 46 test	✅
1.25	Users modülü — profil, şifre değiştir, hesap sil	✅
1.26	Husky — pre-commit lint, pre-push test	✅
1.27	Workspace silme — ilişkili veri cascade sırası düzeltmesi + regresyon testi	✅

Faz 2 — Collaboration 🚧

#	Özellik	Durum
2.1	Yorum sistemi — task'a yorum ekle/düzenle/sil (unit + E2E test edildi)	✅
2.2	Mention sistemi — `@[isim](userId)` parsing + Notification (unit + E2E test edildi)	✅
2.3	Aktivite akışı — task geçmişi (status/priority/assignee/comment otomatik loglama)	✅
2.4	RabbitMQ kurulum + exchange/queue yapısı	⬜
2.5	Email servisi — ayrı mikroservis (RabbitMQ consumer)	⬜
2.6	Email bildirimi — task atandığında	⬜
2.7	Email bildirimi — workspace daveti	⬜
2.8	WebSocket gateway — NestJS	⬜
2.9	Real-time bildirim — task atama, yorum, mention	⬜
2.10	In-app bildirim — okundu/okunmadı (Notification tablosu zaten dolduruluyor — mention'lardan — sadece read/list endpoint'i eksik)	⬜
2.11	Webhook sistemi — Slack entegrasyonu	⬜
2.12	Webhook sistemi — Teams entegrasyonu	⬜
2.13	Redis cache — workspace/project/task hot data	⬜
2.14	Cache invalidation stratejisi	⬜
2.15	2FA devre dışı bırakma endpoint'i (bkz. Bilinen Eksikler)	⬜

Faz 3 — AI + RAG + Big Data ⬜

#	Özellik	Durum
3.1	pgvector kurulum + embedding pipeline	⬜
3.2	RAG — döküman yükle + chunk + index	⬜
3.3	RAG — semantic search + bağlam alma	⬜
3.4	Claude API entegrasyonu	⬜
3.5	Task asistanı — başlık ver, AI açıklama + alt görev önersin	⬜
3.6	Sprint planlama asistanı — AI kapasite bazlı öneri	⬜
3.7	Otomatik önceliklendirme — AI task önceliği atasın	⬜
3.8	RabbitMQ + AI event pipeline — task oluşunca AI analiz	⬜
3.9	Faker.js seed script — 1 milyon activity log	⬜
3.10	Workspace Analytics Pipeline — gece cron job	⬜
3.11	Batch processing — 1000'erlik gruplar	⬜
3.12	Worker concurrency (concurrency: 10)	⬜
3.13	Dead letter queue — başarısız job'lar	⬜
3.14	Idempotency — aynı job 2x çalışırsa sorun olmasın	⬜
3.15	Cursor-based pagination — büyük veri setleri	⬜
3.16	Anomali tespiti — "Bu sprint %40 yavaş"	⬜
3.17	Sprint istatistikleri dashboard	⬜
3.18	PDF/CSV export	⬜

Faz 4 — AWS Deploy + Production ⬜

#	Özellik	Durum
4.1	AWS VPC kurulumu — private network	⬜
4.2	EC2 (t2.micro) — NestJS backend deploy	⬜
4.3	RDS (t3.micro) — PostgreSQL	⬜
4.4	ElastiCache — Redis	⬜
4.5	S3 — dosya ve avatar storage	⬜
4.6	ECS/ECR — Docker container yönetimi	⬜
4.7	RabbitMQ — EC2'da self-hosted	⬜
4.8	GitHub Actions CI/CD — AWS'ye otomatik deploy	⬜
4.9	Grafana Cloud + Loki — log monitoring	⬜
4.10	Production migration stratejisi	⬜
4.11	Health check endpoint	⬜
4.12	E2E test coverage artırma	⬜
4.13	Performans optimizasyonu + load testing	⬜

Bonus — npm Package ⬜

#	Özellik	Durum
B.1	Generic Repository Pattern — Taskflow'da implement et	⬜
B.2	`@fffset/nestjs-repository` — npm'e publish et	⬜

Name		Name	Last commit message	Last commit date
Latest commit History 170 Commits
.husky		.husky
prisma		prisma
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Taskflow API

Tech Stack

Architecture

Data Model

Project Structure

API Endpoints

Auth

Users

Workspaces

Projects

Boards

Tasks

Labels

Comments

Error Response Format

Error Codes

Environment Variables

Development

Test Environment Setup

Git Hooks (Husky)

Workspace Oluşturulunca Otomatik Eklenenler

Notlar

Workspace Silme — Cascade Sırası

Rate Limiting

Audit Log

Mention Sistemi

Bilinen Eksikler / Notlar

Roadmap

Faz 1 — Core ✅

Faz 2 — Collaboration 🚧

Faz 3 — AI + RAG + Big Data ⬜

Faz 4 — AWS Deploy + Production ⬜

Bonus — npm Package ⬜

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Taskflow API

Tech Stack

Architecture

Data Model

Project Structure

API Endpoints

Auth

Users

Workspaces

Projects

Boards

Tasks

Labels

Comments

Error Response Format

Error Codes

Environment Variables

Development

Test Environment Setup

Git Hooks (Husky)

Workspace Oluşturulunca Otomatik Eklenenler

Notlar

Workspace Silme — Cascade Sırası

Rate Limiting

Audit Log

Mention Sistemi

Bilinen Eksikler / Notlar

Roadmap

Faz 1 — Core ✅

Faz 2 — Collaboration 🚧

Faz 3 — AI + RAG + Big Data ⬜

Faz 4 — AWS Deploy + Production ⬜

Bonus — npm Package ⬜

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages