Tenantly — Multi-Tenant Mini Project Management

Mini Asana/Trello untuk banyak perusahaan dalam satu instance. Setiap tenant punya project, task, dan user sendiri, dan tidak pernah bisa melihat data tenant lain.

Stack: NestJS (API) · Next.js (web) · PostgreSQL + Prisma · BullMQ/Redis (async job).

Kenapa: NestJS memberi satu tempat eksplisit (module/guard/interceptor) untuk aturan tenant dan RBAC, alih-alih tersebar di controller. Prisma memberi skema tunggal yang terbaca sebagai dokumentasi sekaligus migration yang ter-version. BullMQ karena Redis sudah lazim ada di stack SaaS.

Daftar Isi

1. Cara Menjalankan
2. Akun Seed
3. Skema Database & ERD
4. Strategi Multi-Tenancy
5. API
6. RBAC
7. Background Job
8. Concurrency & Race Condition
9. Testing
10. Keputusan Keamanan
11. Yang Di-skip & Rencana Berikutnya
12. Keputusan yang Masih Saya Ragukan
13. Peta Requirement

1. Cara Menjalankan

Opsi A — Docker (satu perintah, tidak butuh Postgres/Redis lokal)

docker compose -f docker-compose.dev.yml up --build

Stack ini berisi Postgres + Redis + API + Web, dan otomatis menjalankan prisma migrate deploy lalu seed sebelum API start.

• Web: http://localhost:3000
• API: http://localhost:3001
• Swagger: http://localhost:3001/api/docs

docker-compose.yml (tanpa -f) adalah file production — memakai Postgres eksternal, nginx gateway, dan image dari Docker Hub. File itu tidak akan jalan di mesin bersih; pakai docker-compose.dev.yml untuk mencoba.

Opsi B — Manual (mode development)

Prasyarat: PostgreSQL dan Redis berjalan lokal.

cd backend
cp .env.example .env        # WAJIB isi JWT_SECRET — app menolak start tanpa itu
npm install
npx prisma migrate deploy   # `migrate dev` kalau skema berubah
npm run seed
npm run start:dev

cd frontend
npm install
npm run dev

Migration

Migration ter-commit di backend/prisma/migrations/.

npx prisma migrate dev --name <nama>   # buat migration baru
npx prisma migrate deploy              # terapkan di CI/production

Setiap migration punya down.sql (dari prisma migrate diff --to-empty) karena Prisma tidak punya migrate down. Rollback: jalankan down.sql, lalu prisma migrate resolve --rolled-back <migration>.

schema.sql dan seed.sql di root adalah salinan flat untuk di-paste manual ke psql saat deploy — bukan sumber kebenaran, dan tidak dipakai oleh kedua opsi di atas.

2. Akun Seed

Login dua tenant berbeda di dua browser profile untuk melihat isolasinya. Halaman login menyediakan tombol satu klik untuk tiap akun.

3. Skema Database & ERD

erDiagram
    Company ||--o{ User    : "punya"
    Company ||--o{ Project : "punya"
    Company ||--o{ Task    : "punya (denormalisasi)"
    Project ||--o{ Task    : "punya"
    User    ||--o{ Task    : "di-assign"

    Company {
        uuid   id PK
        string name
    }
    User {
        uuid   id PK
        string email UK
        string password
        enum   role "ADMIN | MEMBER"
        uuid   companyId FK "indexed"
    }
    Project {
        uuid   id PK
        string name
        uuid   companyId FK "indexed"
    }
    Task {
        uuid   id PK
        string title
        enum   status "TODO | IN_PROGRESS | DONE"
        uuid   companyId  FK "indexed"
        uuid   projectId  FK "indexed"
        uuid   assigneeId FK "nullable"
    }

Sumber: backend/prisma/schema.prisma · migration: backend/prisma/migrations/

Keputusan modeling:

4. Strategi Multi-Tenancy

Row-level scoping (shared database, shared schema): setiap tabel milik tenant membawa kolom companyId yang ter-index.

Kenapa: untuk jumlah tenant menengah ini yang paling murah dioperasikan — satu connection pool, satu migration, satu proses backup. Schema-per-tenant memaksa menjalankan ulang setiap migration sebanyak jumlah tenant; database-per-tenant menambah pooling dinamis dan orkestrasi yang tidak sebanding dengan ukuran produk ini.

Aturan yang membuatnya aman: tenant di-resolve hanya dari sesi yang login (req.user.companyId), tidak pernah dari parameter URL atau body. Menebak ID resource milik tenant lain menghasilkan 404.

Trade-off: disiplin ada di level aplikasi. Satu query yang lupa where: { companyId } langsung membocorkan data lintas tenant — database tidak akan menghentikannya. Mitigasi sekarang: semua akses lewat service yang menerima companyId sebagai argumen wajib, plus e2e test yang menembak ID tenant lain secara langsung. Mitigasi sebenarnya adalah PostgreSQL RLS (lihat bagian 11).

Kenapa 404, bukan 403: 403 secara implisit mengonfirmasi bahwa ID tersebut ada, dan itu cukup untuk memetakan isi tenant lain lewat tebakan. Dengan 404, resource tenant lain benar-benar tidak ada dari sudut pandang pemanggil.

5. API

Semua endpoint ber-prefix /api/v1, dengan envelope seragam dari satu interceptor global:

{ "success": true, "statusCode": 200, "message": "...", "data": {} }

PATCH task menerima field opsional expectedUpdatedAt — nilai updatedAt task saat klien terakhir membacanya. Kalau task sudah berubah sejak itu, request ditolak 409 alih-alih menimpa diam-diam: lihat §8.

Swagger lengkap: http://localhost:3001/api/docs Swagger production: https://tenantly.daffathan-labs.my.id/api/docs

6. RBAC

Ditegakkan oleh RolesGuard (dekorator @Roles) untuk aturan per-endpoint, dan cek kepemilikan assignee di TasksService.update untuk aturan per-baris.

7. Background Job

Assign task → job masuk antrian BullMQ (attempts: 3, exponential backoff), diproses worker di luar request cycle; pengiriman email di-mock ke log.

Kalau Redis mati, service jatuh ke log inline supaya request tetap berhasil — pilihan sadar, dengan catatan bahwa itu menyembunyikan Redis yang sedang down.

8. Concurrency & Race Condition

Operasi yang dijaga: PATCH /projects/:id/tasks/:taskId — memindahkan task di papan Kanban.

Masalahnya. Dua orang menyeret task yang sama hampir bersamaan. Keduanya membaca task dalam status TODO, keduanya mengirim PATCH. Tanpa penjagaan, tulisan kedua menang dan tulisan pertama hilang tanpa jejak — tidak ada error, tidak ada log. Orang pertama mengira task-nya sudah pindah, dan papannya menampilkan sesuatu yang tidak lagi benar sampai dia me-reload.

Solusinya: optimistic locking. Klien mengirim balik updatedAt yang dia lihat sebagai expectedUpdatedAt. Server tidak melakukan update langsung, melainkan updateMany yang syaratnya ikut mencocokkan timestamp itu:

const { count } = await this.prisma.task.updateMany({
  where: {
    id: taskId,
    companyId: user.companyId,
    ...(expectedUpdatedAt && { updatedAt: expectedUpdatedAt }),
  },
  data: changes,
});

if (count === 0) {
  throw new ConflictException('Task sudah diubah orang lain sejak terakhir Anda memuatnya...');
}

Cek dan tulis terjadi dalam satu statement SQL, jadi tidak ada celah antara "membaca" dan "menulis". Yang commit duluan menaikkan updatedAt; syarat milik penulis kedua tidak lagi cocok, count jadi 0, dan dia menerima 409 — bukan menimpa. Ini pola If-Match/ETag, dipindah ke body.

Implementasi: TasksService.update · Test: tenant-isolation.e2e-spec.ts grup 5.

Kenapa bukan transaksi atau SELECT FOR UPDATE. Lock pesimistik menahan baris — dan satu koneksi pool — selama request berjalan, demi konflik yang pada beban nyata jarang terjadi, sambil membuka pintu deadlock kalau nanti ada operasi yang mengunci beberapa baris dengan urutan berbeda. Optimistic locking membuat jalur normal berjalan tanpa biaya tambahan dan hanya membayar saat benar-benar bentrok. Catatan jujurnya: kalau nanti ada operasi yang harus mengubah beberapa baris secara atomik, $transaction tetap dibutuhkan — ini bukan pengganti transaksi.

Kenapa updatedAt, bukan kolom version baru. updatedAt sudah ada di semua model, sudah otomatis naik lewat @updatedAt, dan disimpan sebagai TIMESTAMP(3) — presisi milidetik, aman round-trip lewat JSON ISO string. Kolom version berarti migration baru untuk informasi yang sudah dimiliki tabel. Batasnya saya sebut terbuka: kalau satu baris yang sama pernah di-update lebih dari sekali dalam satu milidetik, dua penulis bisa membawa token yang sama dan keduanya lolos. Di titik itu, version Int @default(0) adalah jawabannya — catatannya sudah ditempel di kode.

Kenapa fieldnya opsional. Klien non-browser (curl, Swagger, script) tetap bisa PATCH tanpa token; frontend selalu mengirimnya. Konsekuensinya diakui: proteksinya opt-in, jadi klien yang tidak mengirim token tetap bisa menimpa — lihat §12.

Yang dilihat user. Tab yang kalah tidak sekadar ter-rollback tanpa penjelasan: papannya otomatis di-refresh ke keadaan terbaru dan muncul toast "Someone else moved this task — board refreshed". Respons yang berhasil juga dipakai untuk mengganti task di state, supaya updatedAt tidak basi dan drag berikutnya tidak kena 409 palsu.

9. Testing

cd backend
npm test           # 2 unit test — tidak butuh database, jalan di CI
npm run test:e2e   # 15 test — butuh PostgreSQL + Redis; suite ini MENGHAPUS isi database

test:e2e (backend/test/tenant-isolation.e2e-spec.ts):

CI (.github/workflows/) menjalankan lint, unit test, Trivy scan, dan build image.

10. Keputusan Keamanan

11. Yang Di-skip & Rencana Berikutnya

Urutannya sengaja: 1 dan 5 adalah lubang keamanan, sisanya kualitas operasional.

12. Keputusan yang Masih Saya Ragukan

Cookie httpOnly vs token di header. Cookie menutup pencurian token lewat XSS, tapi menukarnya dengan permukaan CSRF dan membuat konsumen non-browser (mobile, service-to-service) lebih repot — mereka harus ikut mengelola cookie jar. Untuk produk yang hari ini hanya punya satu frontend web, saya menilai XSS lebih nyata daripada CSRF yang sudah tertutup SameSite=Lax. Kalau nanti ada klien mobile, saya cenderung menambah alur bearer token terpisah untuk API non-browser, bukan mengembalikan token ke localStorage.

Keraguan kedua: 404 untuk resource tenant lain. Ini menyembunyikan informasi dengan baik, tapi membuat debugging produksi lebih sulit — "tidak ada" dan "bukan milikmu" jadi tidak terbedakan dari log akses. Kompromi yang saya ambil: response tetap 404, kejadiannya dicatat di log server.

Keraguan ketiga: expectedUpdatedAt dibuat opsional, bukan wajib. Versi ketat mewajibkannya untuk semua klien dan menutup celah sepenuhnya, tapi memaksa setiap konsumen API melakukan read-before-write — termasuk script satu baris yang cuma ingin menandai satu task selesai. Untuk sekarang saya memilih opsional dan frontend selalu mengirimnya, dengan konsekuensi yang saya sadari: klien yang tidak mengirim token tetap bisa menimpa. Kalau nanti ada klien kedua yang menulis task (mobile, integrasi), saya cenderung mewajibkannya dan menerima biayanya.

13. Peta Requirement

Frontend Next.js tidak diminta soal (backend-only), tapi disertakan supaya isolasi tenant bisa dilihat langsung di browser dengan dua akun berbeda.