Apa Itu Clean Architecture?

  • Teknis dan Maintenance
  • 12 November 2026
  • 39 dilihat

Apa Itu Clean Architecture? Pengertian, Prinsip, dan Studi Kasus Implementasi

Dalam pengembangan aplikasi perusahaan, struktur kode yang rapi saja terkadang belum cukup. Ketika aplikasi semakin besar, developer juga perlu memikirkan bagaimana setiap bagian sistem saling berhubungan.

Bayangkan sebuah perusahaan memiliki aplikasi Inventory Management untuk mengelola produk, stok gudang, transaksi barang masuk, dan barang keluar.

Pada awal pengembangan, aplikasi mungkin hanya memiliki beberapa endpoint sederhana. Namun, seiring waktu, perusahaan membutuhkan fitur tambahan seperti multiwarehouse, stock opname, approval transaksi, hingga integrasi dengan sistem purchasing.

Jika seluruh business logic, query database, dan proses HTTP berada dalam satu bagian aplikasi, perubahan teknologi atau penambahan fitur bisa menjadi semakin rumit.

Salah satu pendekatan untuk mengatasi masalah tersebut adalah Clean Architecture.

Clean Architecture membantu developer menyusun aplikasi berdasarkan tanggung jawab setiap komponen dan menjaga agar business logic tidak terlalu bergantung pada teknologi yang digunakan.

Lalu, apa itu Clean Architecture, bagaimana cara kerjanya, dan bagaimana implementasinya menggunakan Node.js?

Apa Itu Clean Architecture?

Clean Architecture adalah pendekatan desain software yang memisahkan business logic dari detail implementasi teknis seperti database, framework, API, dan infrastruktur.

Konsep ini dipopulerkan oleh Robert C. Martin atau Uncle Bob.

Gagasan utamanya adalah business logic aplikasi harus menjadi bagian yang paling independen. Artinya, aturan bisnis tidak seharusnya bergantung langsung pada framework atau teknologi database tertentu.

Sebagai contoh, perusahaan memiliki aturan bahwa stok produk tidak boleh menjadi negatif.

Aturan tersebut merupakan kebutuhan bisnis. Aturan ini seharusnya tetap berlaku meskipun aplikasi menggunakan MySQL, PostgreSQL, MongoDB, Express.js, atau framework lainnya.

Dengan Clean Architecture, aturan bisnis dapat ditempatkan pada bagian inti aplikasi sehingga tidak terikat langsung dengan teknologi yang digunakan.

Mengapa Clean Architecture Penting untuk Aplikasi Perusahaan?

Clean Architecture sangat relevan untuk aplikasi yang memiliki proses bisnis kompleks dan akan dikembangkan dalam jangka panjang.

Berikut beberapa manfaatnya.

1. Business Logic Tidak Bergantung pada Framework

Framework seperti Express.js membantu menangani HTTP request dan response.

Namun, aturan bisnis perusahaan sebaiknya tidak bergantung langsung pada Express.js.

Dengan pemisahan yang tepat, business logic tetap dapat digunakan meskipun framework backend diganti.

2. Lebih Mudah Mengganti Database

Misalnya, aplikasi inventory awalnya menggunakan MongoDB. Setelah kebutuhan perusahaan berkembang, tim memutuskan menggunakan PostgreSQL.

Jika seluruh query database tersebar di dalam business logic, proses migrasi akan menjadi lebih rumit.

Clean Architecture membantu memisahkan aturan bisnis dari implementasi database sehingga pergantian teknologi dapat dilakukan dengan lebih terarah.

3. Lebih Mudah Melakukan Testing

Business logic yang tidak bergantung langsung pada database atau framework akan lebih mudah diuji.

Developer dapat menggunakan mock repository untuk menguji proses bisnis tanpa harus selalu menjalankan database sungguhan.

4. Mempermudah Pengembangan Fitur Baru

Ketika aplikasi bertambah besar, setiap fitur dapat dikembangkan berdasarkan tanggung jawab masing-masing komponen.

Misalnya, penambahan fitur stock opname tidak harus mengubah seluruh mekanisme pengelolaan produk.

5. Mempermudah Kolaborasi Tim Developer

Pemisahan komponen membuat tanggung jawab setiap bagian lebih jelas.

Developer dapat mengembangkan use case, repository, atau API tanpa harus selalu mengubah seluruh struktur aplikasi.

Prinsip Utama Clean Architecture

Clean Architecture umumnya digambarkan dalam beberapa lapisan atau layers.

Setiap lapisan memiliki tanggung jawab berbeda dan memiliki aturan ketergantungan yang harus dijaga.

Berikut empat lapisan yang sering digunakan dalam implementasinya.

1. Entities

Entities merupakan bagian inti yang merepresentasikan aturan bisnis paling mendasar.

Contohnya, dalam aplikasi Inventory Management terdapat entitas Product yang memiliki informasi seperti nama produk, harga, dan jumlah stok.

Contoh implementasi:

class Product {
  constructor({
    id,
    name,
    price,
    stock
  }) {
    if (!name) {
      throw new Error("Product name is required");
    }

    if (price <= 0) {
      throw new Error("Product price must be greater than zero");
    }

    if (!Number.isInteger(stock) || stock < 0) {
      throw new Error("Invalid product stock");
    }

    this.id = id;
    this.name = name;
    this.price = price;
    this.stock = stock;
  }

  reduceStock(quantity) {
    if (!Number.isInteger(quantity) || quantity <= 0) {
      throw new Error("Quantity must be greater than zero");
    }

    if (this.stock < quantity) {
      throw new Error("Insufficient stock");
    }

    this.stock -= quantity;
  }
}

module.exports = Product;

Pada contoh tersebut, Product memiliki aturan dasar mengenai validitas data dan pengurangan stok.

Aturan tersebut tidak membutuhkan Express.js maupun database untuk dijalankan.

2. Use Cases

Use Cases merupakan lapisan yang mengatur bagaimana business logic dijalankan untuk memenuhi kebutuhan tertentu.

Misalnya:

  • Membuat produk baru.

  • Mengurangi stok produk.

  • Melihat detail produk.

  • Melakukan stock opname.

Contoh implementasi use case untuk mengurangi stok:

class ReduceStockUseCase {
  constructor(productRepository) {
    this.productRepository = productRepository;
  }

  async execute({
    productId,
    quantity
  }) {
    const product = await this.productRepository.findById(
      productId
    );

    if (!product) {
      throw new Error("Product not found");
    }

    product.reduceStock(quantity);

    await this.productRepository.save(product);

    return product;
  }
}

module.exports = ReduceStockUseCase;

Use case tersebut menjalankan alur bisnis pengurangan stok.

Perhatikan bahwa use case tidak mengetahui apakah data disimpan menggunakan MySQL, PostgreSQL, atau MongoDB.

Use case hanya membutuhkan repository yang menyediakan operasi yang diperlukan.

3. Interface Adapters

Lapisan Interface Adapters bertugas menjadi penghubung antara use case dan teknologi eksternal.

Contohnya meliputi:

  • Controller untuk menangani HTTP request.

  • Presenter untuk mengubah hasil use case menjadi format response.

  • Repository implementation untuk menghubungkan use case dengan database.

Pada implementasi Node.js, kita dapat menempatkan controller dan repository database pada lapisan ini.

Contoh controller:

class ProductController {
  constructor(reduceStockUseCase) {
    this.reduceStockUseCase = reduceStockUseCase;
  }

  async reduceStock(req, res, next) {
    try {
      const product = await this.reduceStockUseCase.execute({
        productId: req.params.id,
        quantity: req.body.quantity
      });

      return res.status(200).json({
        message: "Stock reduced successfully",
        data: {
          id: product.id,
          name: product.name,
          stock: product.stock
        }
      });
    } catch (error) {
      next(error);
    }
  }
}

module.exports = ProductController;

Controller hanya bertugas menerima request, memanggil use case, dan mengirim response.

Aturan pengurangan stok tetap berada di bagian inti aplikasi.

4. Frameworks and Drivers

Ini merupakan lapisan terluar yang berisi detail teknologi yang digunakan aplikasi.

Contohnya:

  • Express.js.

  • Database seperti PostgreSQL atau MongoDB.

  • Database driver.

  • External API.

  • Message broker.

Teknologi tersebut berfungsi sebagai alat untuk menjalankan aplikasi.

Clean Architecture menjaga agar detail teknis ini tidak mengendalikan aturan bisnis utama.

Studi Kasus Clean Architecture Menggunakan Node.js dan Express.js

Sekarang kita implementasikan konsep tersebut dalam aplikasi Inventory Management.

Studi kasusnya adalah fitur pengurangan stok produk.

Ketika karyawan gudang mencatat barang keluar, aplikasi harus:

  1. Menerima permintaan pengurangan stok.

  2. Memeriksa apakah produk tersedia.

  3. Memastikan jumlah stok mencukupi.

  4. Mengurangi jumlah stok.

  5. Menyimpan perubahan ke database.

  6. Mengembalikan hasil transaksi kepada pengguna.

Kita akan menggunakan Node.js, Express.js, dan PostgreSQL sebagai contoh teknologi.

Untuk mempermudah pemahaman, implementasi repository menggunakan contoh query database dengan pg.

1. Membuat Struktur Folder

Langkah pertama adalah menyusun struktur folder berdasarkan lapisan arsitektur.

inventory-app/
│
├── src/
│   ├── domain/
│   │   └── entities/
│   │       └── Product.js
│   │
│   ├── application/
│   │   └── use-cases/
│   │       └── ReduceStockUseCase.js
│   │
│   ├── interfaces/
│   │   ├── controllers/
│   │   │   └── ProductController.js
│   │   │
│   │   └── repositories/
│   │       └── PostgresProductRepository.js
│   │
│   ├── infrastructure/
│   │   └── database/
│   │       └── postgres.js
│   │
│   ├── routes/
│   │   └── product.routes.js
│   │
│   └── app.js
│
└── server.js

Struktur tersebut membagi aplikasi menjadi beberapa bagian:

FolderTanggung jawab
domainEntitas dan aturan bisnis inti
applicationUse case atau alur bisnis aplikasi
interfacesController dan implementasi adapter
infrastructureKoneksi dan detail teknologi
routesDefinisi endpoint API

Struktur ini merupakan salah satu contoh implementasi Clean Architecture. Nama dan jumlah folder dapat berbeda tergantung kebutuhan proyek.

2. Membuat Database Connection

Buat file postgres.js untuk mengatur koneksi database.

const { Pool } = require("pg");

const pool = new Pool({
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME
});

module.exports = pool;

Database connection ditempatkan di infrastructure karena merupakan detail implementasi teknologi.

3. Membuat Repository untuk PostgreSQL

Repository menjadi penghubung antara use case dan database.

Buat file PostgresProductRepository.js.

const Product = require("../../domain/entities/Product");

class PostgresProductRepository {
  constructor(database) {
    this.database = database;
  }

  async findById(productId) {
    const result = await this.database.query(
      `SELECT id, name, price, stock
       FROM products
       WHERE id = $1`,
      [productId]
    );

    if (result.rows.length === 0) {
      return null;
    }

    return new Product(result.rows[0]);
  }

  async save(product) {
    await this.database.query(
      `UPDATE products
       SET stock = $1
       WHERE id = $2`,
      [product.stock, product.id]
    );

    return product;
  }
}

module.exports = PostgresProductRepository;

Repository bertugas menerjemahkan kebutuhan aplikasi menjadi operasi database.

Use case tidak perlu mengetahui sintaks SQL yang digunakan.

4. Membuat Use Case Pengurangan Stok

Buat file ReduceStockUseCase.js.

class ReduceStockUseCase {
  constructor(productRepository) {
    this.productRepository = productRepository;
  }

  async execute({ productId, quantity }) {
    if (!Number.isInteger(quantity) || quantity <= 0) {
      throw new Error("Invalid quantity");
    }

    const product = await this.productRepository.findById(
      productId
    );

    if (!product) {
      throw new Error("Product not found");
    }

    product.reduceStock(quantity);

    await this.productRepository.save(product);

    return product;
  }
}

module.exports = ReduceStockUseCase;

Inilah bagian penting dari Clean Architecture.

Use case tidak bergantung langsung pada Express.js maupun PostgreSQL.

Ia hanya membutuhkan repository dengan operasi findById dan save.

5. Membuat Controller

Selanjutnya, buat file ProductController.js.

class ProductController {
  constructor(reduceStockUseCase) {
    this.reduceStockUseCase = reduceStockUseCase;
  }

  reduceStock = async (req, res, next) => {
    try {
      const product = await this.reduceStockUseCase.execute({
        productId: Number(req.params.id),
        quantity: req.body.quantity
      });

      return res.status(200).json({
        message: "Stock reduced successfully",
        data: {
          id: product.id,
          name: product.name,
          stock: product.stock
        }
      });
    } catch (error) {
      next(error);
    }
  };
}

module.exports = ProductController;

Controller tidak melakukan query database dan tidak menghitung pengurangan stok sendiri.

Semua proses bisnis diserahkan kepada use case.

6. Menghubungkan Semua Komponen

Sekarang kita perlu menghubungkan seluruh komponen aplikasi.

Buat file product.routes.js.

const express = require("express");

function createProductRoutes(productController) {
  const router = express.Router();

  router.post(
    "/:id/reduce-stock",
    productController.reduceStock
  );

  return router;
}

module.exports = createProductRoutes;

Kemudian buat app.js sebagai tempat melakukan dependency injection dan konfigurasi aplikasi.

const express = require("express");

const pool = require("./infrastructure/database/postgres");

const PostgresProductRepository = require(
  "./interfaces/repositories/PostgresProductRepository"
);

const ReduceStockUseCase = require(
  "./application/use-cases/ReduceStockUseCase"
);

const ProductController = require(
  "./interfaces/controllers/ProductController"
);

const createProductRoutes = require("./routes/product.routes");

const app = express();

app.use(express.json());

const productRepository = new PostgresProductRepository(pool);

const reduceStockUseCase = new ReduceStockUseCase(
  productRepository
);

const productController = new ProductController(
  reduceStockUseCase
);

app.use(
  "/api/products",
  createProductRoutes(productController)
);

app.use((error, req, res, next) => {
  if (res.headersSent) {
    return next(error);
  }

  const statusCode =
    error.message === "Product not found" ? 404 :
    error.message === "Insufficient stock" ? 409 :
    error.message === "Invalid quantity" ||
    error.message === "Quantity must be greater than zero" ? 400 :
    500;

  return res.status(statusCode).json({
    message: statusCode === 500
      ? "Internal server error"
      : error.message
  });
});

module.exports = app;

Terakhir, buat server.js.

require("dotenv").config();

const app = require("./src/app");

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Pada implementasi produksi, penanganan error sebaiknya menggunakan custom error class, validasi input yang konsisten, serta transaksi database untuk menjaga konsistensi perubahan stok.

7. Menguji Endpoint Pengurangan Stok

Setelah aplikasi berjalan, kita dapat menguji endpoint menggunakan Postman.

Endpoint:

POST /api/products/10/reduce-stock

Request Body:

{
  "quantity": 5
}

Misalnya, produk dengan ID 10 memiliki stok awal 20 unit.

Setelah request berhasil, stok produk menjadi 15 unit.

Contoh response:

{
  "message": "Stock reduced successfully",
  "data": {
    "id": 10,
    "name": "Laptop Dell",
    "stock": 15
  }
}

Jika jumlah stok tidak mencukupi, aplikasi akan mengembalikan error dan tidak melanjutkan proses pengurangan stok.

Bagaimana Alur Kerja Clean Architecture?

Dari implementasi sebelumnya, alur request dapat digambarkan sebagai berikut:

User / Client
      |
      v
Express.js Route
      |
      v
Product Controller
      |
      v
ReduceStockUseCase
      |
      v
Product Entity
      |
      v
Product Repository
      |
      v
PostgreSQL Database

Alur tersebut menggambarkan proses utama secara sederhana.

Perlu dipahami bahwa arah ketergantungan kode tidak sama dengan urutan perjalanan request.

Dalam Clean Architecture, lapisan luar dapat memanggil lapisan dalam, tetapi lapisan dalam tidak boleh bergantung pada implementasi lapisan luar.

Sebagai contoh, ReduceStockUseCase mengetahui kontrak repository yang dibutuhkannya, tetapi tidak perlu mengetahui bahwa implementasinya menggunakan PostgreSQL.

Apa Perbedaan Clean Architecture dan Clean Code?

Clean Architecture dan Clean Code sering dibahas bersamaan, tetapi keduanya memiliki fokus yang berbeda.

AspekClean CodeClean Architecture
FokusKualitas penulisan kodeStruktur dan desain sistem
TujuanKode mudah dibaca dan dipeliharaBusiness logic tidak terikat detail teknis
CakupanFungsi, variabel, penamaan, kompleksitasLayers, use case, entities, dependencies
ContohFungsi dengan nama yang jelasMemisahkan use case dari database
ManfaatMempermudah pemahaman kodeMempermudah perubahan teknologi dan pengembangan sistem

Clean Code membantu developer menulis kode yang baik, sedangkan Clean Architecture membantu developer menyusun keseluruhan aplikasi dengan struktur ketergantungan yang lebih terarah.

Keduanya dapat diterapkan secara bersamaan.

Apa Perbedaan Clean Architecture dan SOLID Principle?

SOLID Principle merupakan kumpulan lima prinsip desain software, sedangkan Clean Architecture merupakan pendekatan untuk menyusun struktur aplikasi.

Keduanya saling mendukung.

Sebagai contoh, Dependency Inversion Principle (DIP) dari SOLID sejalan dengan gagasan Clean Architecture bahwa business logic tidak boleh bergantung langsung pada detail implementasi teknis.

Dalam studi kasus sebelumnya, ReduceStockUseCase bergantung pada repository melalui kontrak yang dibutuhkan, bukan langsung pada PostgreSQL.

Kapan Sebaiknya Menggunakan Clean Architecture?

Clean Architecture sangat berguna ketika aplikasi memiliki kompleksitas dan kebutuhan pengembangan jangka panjang.

Contohnya:

  • Enterprise Resource Planning (ERP).

  • Inventory Management System.

  • Warehouse Management System (WMS).

  • Human Resource Information System (HRIS).

  • Purchasing Management System.

  • Manufacturing Management System.

  • Custom Business Application.

Aplikasi-aplikasi tersebut umumnya memiliki banyak aturan bisnis, integrasi, dan kebutuhan pengembangan yang dapat berubah.

Namun, Clean Architecture tidak harus diterapkan secara berlebihan.

Untuk website sederhana atau aplikasi CRUD kecil, struktur yang terlalu kompleks justru dapat menambah pekerjaan tanpa memberikan manfaat yang sebanding.

Pilih tingkat pemisahan komponen berdasarkan kebutuhan dan kompleksitas aplikasi.

Kesalahan yang Perlu Dihindari Saat Menerapkan Clean Architecture

1. Terlalu Banyak Layer Tanpa Kebutuhan

Membuat banyak folder dan class tidak otomatis membuat aplikasi memiliki arsitektur yang baik.

Setiap layer harus memiliki tanggung jawab yang jelas.

2. Business Logic Masih Berada di Controller

Controller sebaiknya tidak menjadi tempat seluruh aturan bisnis dijalankan.

Pindahkan proses bisnis ke use case agar lebih mudah diuji dan dipelihara.

3. Use Case Bergantung Langsung pada Database

Jika use case langsung menggunakan query PostgreSQL atau memanggil model ORM tertentu, business logic akan terikat pada detail implementasi database.

Gunakan kontrak repository agar ketergantungan lebih terkontrol.

4. Menganggap Clean Architecture Menjamin Performa Tinggi

Clean Architecture bukan teknik optimasi performa.

Aplikasi tetap membutuhkan query database yang efisien, pengelolaan cache, monitoring, dan optimasi infrastruktur.

5. Tidak Memperhatikan Konsistensi Data

Dalam sistem inventory, proses pengurangan stok harus memperhatikan kemungkinan dua transaksi berjalan bersamaan.

Pada aplikasi produksi, operasi pengurangan stok sebaiknya menggunakan transaksi database dan mekanisme concurrency control yang sesuai agar stok tidak menjadi tidak konsisten.

Kesimpulan

Clean Architecture merupakan pendekatan desain software yang membantu memisahkan business logic dari detail implementasi teknis.

Dengan membagi aplikasi menjadi beberapa lapisan seperti Entities, Use Cases, Interface Adapters, serta Frameworks and Drivers, developer dapat membangun sistem yang lebih terstruktur dan mudah dikembangkan.

Dalam studi kasus Inventory Management menggunakan Node.js dan Express.js, kita melihat bagaimana proses pengurangan stok dapat dipisahkan menjadi entity, use case, controller, dan repository.

Pendekatan ini sangat bermanfaat untuk pengembangan aplikasi perusahaan yang memiliki banyak fitur dan kebutuhan bisnis yang terus berkembang.

Bagi perusahaan yang ingin membangun aplikasi custom, arsitektur software perlu dipertimbangkan sejak awal agar sistem tidak hanya memenuhi kebutuhan operasional saat ini, tetapi juga memiliki fondasi yang mendukung pengembangan di masa depan.

Jika perusahaan Anda membutuhkan website atau aplikasi bisnis yang dirancang sesuai proses operasional, tangerangwebsite.id dapat menjadi partner untuk mendiskusikan kebutuhan dan perencanaan pengembangan sistem tersebut.


FAQ Seputar Clean Architecture

1. Apa itu Clean Architecture dalam Node.js?

Clean Architecture dalam Node.js adalah pendekatan penyusunan aplikasi dengan memisahkan business logic dari framework, database, dan teknologi eksternal lainnya.

2. Apakah Clean Architecture harus menggunakan Express.js?

Tidak. Clean Architecture dapat diterapkan menggunakan Express.js, Fastify, NestJS, atau framework Node.js lainnya.

3. Apa fungsi Use Case dalam Clean Architecture?

Use Case bertugas menjalankan proses bisnis tertentu, seperti membuat produk, mengurangi stok, atau melakukan transaksi barang masuk.

4. Apakah Clean Architecture cocok untuk aplikasi ERP?

Ya. Clean Architecture dapat membantu mengelola kompleksitas aplikasi ERP yang memiliki banyak modul dan aturan bisnis.

5. Apakah Clean Architecture wajib digunakan untuk semua aplikasi?

Tidak. Penerapannya perlu disesuaikan dengan skala, kompleksitas, dan kebutuhan pengembangan aplikasi.