☕ Framework

Framework Java enterprise buatan sendiri — tanpa Spring, tanpa Jakarta EE, tanpa magic.

Daftar Isi

Tentang Project
Masalah yang Diselesaikan
Filosofi Desain
Arsitektur
Struktur Folder
Framework Components
Request Lifecycle
Dependency Injection
Routing
Authentication & Session
Data Layer / ORM
Membuat Module Baru
Membuat Entity Baru
Menjalankan Project
Menjalankan Test
Contoh Lengkap CRUD Module
Roadmap

Tentang Project

Helios adalah framework web Java yang dibangun dari awal sebagai proyek eksplorasi arsitektur. Tujuannya bukan untuk menggantikan Spring Boot, melainkan untuk memahami bagaimana sebuah framework enterprise sesungguhnya bekerja — dari HTTP server, routing, DI container, hingga ORM — dengan menulis setiap komponennya sendiri.

Project ini lahir dari satu pertanyaan sederhana:

"Jika kita tidak boleh pakai Spring, bagaimana caranya membangun aplikasi Java enterprise yang konsisten, maintainable, dan bisa scale?"

Jawabannya adalah framework ini.

Apa yang Bisa Dilakukan

Menerima dan merutekan HTTP request dengan pattern matching (/api/users/:id)
Menjalankan middleware chain (logging, CORS, autentikasi)
Memvalidasi request body secara deklaratif dengan annotation
Melakukan operasi CRUD ke database via JDBC tanpa ORM eksternal
Mengamankan endpoint dengan JWT yang disimpan di HttpOnly cookie
Men-generate laporan dalam format PDF, Excel, dan CSV
Mengelola dependency antar komponen tanpa classpath scanning

Stack Teknis

Kategori	Library	Alasan
HTTP Server	JDK `com.sun.net.httpserver`	Built-in Java 21, tidak butuh dependency
Concurrency	Java 21 Virtual Threads	Lightweight, satu thread per request
Connection Pool	HikariCP 5	Paling efisien, konfigurasi minimal
JSON	Jackson Databind	Standard de facto di ekosistem Java
JWT	JJWT 0.12	Library kecil, tidak membawa framework
Password	jBCrypt	Satu class, battle-tested
Excel	Apache POI	Standard untuk format Office
PDF	OpenPDF	Fork open-source iText 4
Database (dev)	H2 in-memory	Zero setup, langsung jalan
Database (prod)	PostgreSQL	Production-grade RDBMS

Masalah yang Diselesaikan

1. "Framework sebagai black box"

Spring Boot luar biasa produktif, tetapi sebagian besar developer tidak benar-benar tahu apa yang terjadi di baliknya. Ketika ada error aneh di BeanCreationException atau NoSuchBeanDefinitionException, banyak yang langsung copy-paste solusi dari Stack Overflow tanpa mengerti akarnya.

Framework ini memaksa kita untuk memahami setiap lapisan: bagaimana request masuk, bagaimana dependency di-resolve, bagaimana query SQL terbentuk.

2. "Annotation magic yang tidak transparan"

@Autowired, @Transactional, @EnableJpaAuditing — semua ini menyembunyikan logika yang sesungguhnya kompleks di balik satu baris kode. Di framework ini, semua wiring dilakukan secara eksplisit di App.java dan setiap Module. Tidak ada yang tersembunyi.

3. "Dependency bloat"

Proyek Spring Boot minimal sudah membawa puluhan MB dependency. Framework ini dirancang minimalis — hanya library untuk concern yang benar-benar tidak perlu dibangun ulang (connection pool, JWT, BCrypt).

4. "Boilerplate yang tidak terkontrol"

Dengan generator (generate-project.sh), seluruh skeleton ERP dengan 64 entity di 9 module bisa dibuat dalam hitungan detik, menghasilkan struktur yang 100% konsisten antar module.

Filosofi Desain

Eksplisit Lebih Baik dari Implisit

Tidak ada classpath scanning. Tidak ada auto-configuration. Setiap komponen didaftarkan secara manual. Ini terlihat seperti lebih banyak kode, tetapi hasilnya adalah kode yang mudah dibaca dari atas ke bawah — bahkan oleh developer yang baru bergabung.

Satu Layer, Satu Tanggung Jawab

Controller  →  menerima request, mengembalikan response
UseCase     →  mendefinisikan kontrak operasi (interface)
Service     →  implementasi alur bisnis
Repository  →  akses data, tidak tahu ada HTTP di atas

Setiap layer hanya boleh bergantung ke layer di bawahnya. Controller tidak boleh langsung akses DataSource. Repository tidak boleh tahu ada Response.

Library, Bukan Framework atas Framework

HikariCP, Jackson, JJWT, jBCrypt — ini adalah library murni yang melakukan satu hal dengan sangat baik. Framework ini hanya sebagai perekat (glue code) antar library tersebut, bukan layer abstraksi tambahan di atas layer abstraksi yang sudah ada.

Testability by Default

Setiap Service menerima Repository via constructor. Tidak ada static method, tidak ada singleton tersembunyi. Untuk test, cukup passing mock repository — tidak butuh Spring Test Context, tidak butuh @MockBean.

Arsitektur

Framework menggunakan Modular Monolith dengan Feature-based Packages. Setiap module bisnis (finance, hrm, inventory, dll.) berdiri sendiri, tetapi berjalan dalam satu JVM.

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT (Browser / API Client)            │
└──────────────────────────────┬──────────────────────────────────┘
                               │  HTTP Request
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  WebServer  (JDK HttpServer + Java 21 Virtual Threads)          │
│  Satu virtual thread per request — lightweight, non-blocking    │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  MiddlewareChain                                                 │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐  │
│  │LoggingMiddleware│→ │ CorsMiddleware │→ │ AuthMiddleware   │  │
│  │ (timing, log)  │  │ (CORS headers) │  │ (JWT cookie →    │  │
│  └────────────────┘  └────────────────┘  │  SecurityContext)│  │
│                                           └──────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Router                                                          │
│  Exact match dulu → lalu pattern match (:id)                    │
│  GET /api/finance/accounts/export/pdf  ✓ exact                  │
│  GET /api/finance/accounts/:id         ✓ pattern                │
└──────────────────────────────┬──────────────────────────────────┘
                               │  matched Handler
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Controller (per entity)                                         │
│  Membaca Request, memanggil UseCase, menulis Response            │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Service (implements UseCase)                                    │
│  Orchestration: validasi → repo → transform → return            │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  Repository (extends BaseRepository<T>)                          │
│  Reflection-based SQL via @Entity, @Table, @Column              │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│  DataSource (HikariCP connection pool)                           │
│  H2 (dev) / PostgreSQL (prod)                                   │
└─────────────────────────────────────────────────────────────────┘

Struktur Folder

src/
├── main/
│   ├── java/com/company/erp/
│   │   │
│   │   ├── App.java                        ← Bootstrap: wiring semua komponen
│   │   │
│   │   ├── framework/                      ← CORE FRAMEWORK (tidak disentuh developer)
│   │   │   ├── config/
│   │   │   │   └── AppConfig.java          ← Baca application.properties / env vars
│   │   │   ├── container/
│   │   │   │   └── Container.java          ← DI registry (Map<Class, instance>)
│   │   │   ├── data/
│   │   │   │   ├── annotation/             ← @Entity, @Table, @Id, @Column
│   │   │   │   ├── BaseRepository.java     ← Generic JDBC CRUD via reflection
│   │   │   │   ├── DataSource.java         ← HikariCP wrapper
│   │   │   │   ├── PageResult.java         ← Pagination container
│   │   │   │   ├── Repository.java         ← Interface kontrak data access
│   │   │   │   └── SchemaRunner.java       ← Eksekusi schema.sql saat startup
│   │   │   ├── exception/
│   │   │   │   ├── ExceptionHandler.java   ← Map Exception → HTTP response
│   │   │   │   ├── FrameworkException.java
│   │   │   │   ├── NotFoundException.java
│   │   │   │   ├── UnauthorizedException.java
│   │   │   │   └── ForbiddenException.java
│   │   │   ├── http/
│   │   │   │   ├── Handler.java            ← @FunctionalInterface: (req, res) → void
│   │   │   │   ├── HttpMethod.java         ← Enum: GET, POST, PUT, DELETE, ...
│   │   │   │   ├── Request.java            ← Wrapper HttpExchange: path, query, body, cookie
│   │   │   │   ├── Response.java           ← Builder: status, json, binary, cookie
│   │   │   │   ├── Router.java             ← Route table + pattern matching
│   │   │   │   └── WebServer.java          ← JDK HttpServer + virtual thread executor
│   │   │   ├── middleware/
│   │   │   │   ├── Middleware.java         ← Interface: execute(req, res, next)
│   │   │   │   ├── MiddlewareChain.java    ← Recursive chain-of-responsibility
│   │   │   │   ├── CorsMiddleware.java
│   │   │   │   └── LoggingMiddleware.java
│   │   │   ├── module/
│   │   │   │   ├── AppModule.java          ← Interface: register(container, router)
│   │   │   │   └── ModuleRegistry.java     ← Daftar dan boot semua module
│   │   │   ├── response/
│   │   │   │   ├── ApiResponse.java        ← {success, message, data}
│   │   │   │   └── PageResponse.java       ← {data, total, page, perPage, totalPages}
│   │   │   ├── security/
│   │   │   │   ├── AuthMiddleware.java     ← Baca cookie → parse JWT → set SecurityContext
│   │   │   │   ├── JwtUtil.java            ← Generate & parse JWT
│   │   │   │   ├── PasswordHasher.java     ← BCrypt wrapper
│   │   │   │   └── SecurityContext.java    ← ThreadLocal<Principal>
│   │   │   ├── util/
│   │   │   │   ├── ExportUtil.java         ← PDF / Excel / CSV → byte[]
│   │   │   │   └── JsonUtil.java           ← Jackson ObjectMapper wrapper
│   │   │   └── validation/
│   │   │       ├── annotation/             ← @NotBlank, @NotNull, @Size, @Email
│   │   │       ├── ValidationException.java
│   │   │       └── Validator.java          ← Reflect fields, check annotations
│   │   │
│   │   ├── shared/
│   │   │   └── entity/
│   │   │       └── BaseEntity.java         ← id, createdAt, updatedAt, deleted
│   │   │
│   │   └── modules/                        ← KODE APLIKASI (digenerate & dikembangkan)
│   │       ├── auth/                       ← Manual (tidak digenerate)
│   │       │   ├── AuthModule.java
│   │       │   ├── controller/AuthController.java
│   │       │   ├── dto/
│   │       │   ├── entity/{User, Role}.java
│   │       │   ├── repository/UserRepository.java
│   │       │   └── service/{AuthService, DataInitializer}.java
│   │       │
│   │       └── {module}/                   ← Digenerate per module
│   │           ├── {Module}Module.java      ← Wiring repo + service + controller + routes
│   │           └── {entity}/               ← Digenerate per entity
│   │               ├── {Entity}.java
│   │               ├── {Entity}UseCase.java
│   │               ├── {Entity}Service.java
│   │               ├── {Entity}Repository.java
│   │               ├── {Entity}Mapper.java
│   │               ├── {Entity}Controller.java
│   │               └── dto/
│   │                   ├── {Entity}Request.java
│   │                   └── {Entity}Response.java
│   │
│   └── resources/
│       ├── application.properties          ← Konfigurasi server, DB, JWT
│       └── schema.sql                      ← DDL, dieksekusi saat startup
│
└── test/
    └── java/com/company/erp/
        └── modules/
            ├── auth/AuthServiceTest.java
            └── {module}/{entity}/{Entity}ServiceTest.java

Framework Components

`WebServer`

WebServer adalah entry point HTTP. Ia membungkus com.sun.net.httpserver.HttpServer dari JDK — sebuah HTTP server sederhana yang sudah built-in di Java tanpa dependency tambahan.

Yang membuat implementasi ini menarik adalah penggunaan Java 21 Virtual Threads:

server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());

Setiap request yang masuk dijalankan di virtual thread yang terpisah. Virtual thread adalah lightweight thread yang dikelola JVM, bukan OS. Ribuan virtual thread bisa berjalan bersamaan tanpa overhead context-switching OS yang besar — mirip dengan pendekatan async/non-blocking, tetapi dengan model pemrograman synchronous yang jauh lebih mudah dibaca.

Setelah request selesai, WebServer selalu memanggil response.send() di blok finally — memastikan tidak ada request yang menggantung tanpa response.

`Router`

Router menyimpan tabel route sebagai List<Route>. Setiap Route menyimpan tiga hal: HTTP method, pattern URL, dan handler.

Cara matching: Router mencoba dua strategi secara berurutan:

Exact match — bandingkan path request dengan pattern secara literal
Pattern match — pattern seperti /api/finance/accounts/:id dicocokkan segment per segment

Urutan ini penting. Tanpa exact match di awal, request ke /api/finance/accounts/export/pdf bisa tertangkap oleh route /api/finance/accounts/:id karena export akan dianggap sebagai nilai :id. Dengan exact match diprioritaskan, route yang lebih spesifik selalu menang.

// Di FinanceModule — export didaftarkan SEBELUM :id
router.get("/api/finance/accounts/export/pdf",  ctrl::exportPdf);  // exact → menang
router.get("/api/finance/accounts/:id",          ctrl::getById);    // pattern

Path variable diekstrak secara otomatis dan bisa diakses via req.getPathVar("id").

`Request` dan `Response`

Request adalah wrapper tipis di atas HttpExchange dari JDK. Ia tidak melakukan parsing di constructor — parsing dilakukan lazy saat method dipanggil (body hanya dibaca sekali dan di-cache).

Cookie parsing dilakukan manual dengan split string:

Cookie: token=eyJhb...; session=abc123
         ──────────────────────────────
         split(";") → split("=", 2)

Response adalah builder pattern. Setiap method mengembalikan this sehingga bisa di-chain:

res.status(201)
   .setAuthCookie(token, maxAge)
   .json(ApiResponse.success("Created", data));

Penting: res.json(...) tidak langsung menulis ke socket. Ia hanya menyiapkan byte array di memory. Penulisan ke socket terjadi saat res.send() dipanggil — yang dilakukan oleh WebServer di blok finally, bukan oleh controller. Ini memastikan response selalu terkirim bahkan jika terjadi exception di tengah jalan.

`MiddlewareChain`

Middleware adalah pattern chain of responsibility. Setiap middleware memutuskan apakah akan meneruskan request ke middleware berikutnya atau menghentikannya.

public interface Middleware {
    void execute(Request req, Response res, Handler next) throws Exception;
}

MiddlewareChain menggunakan rekursi untuk menjalankan chain:

private void run(int idx, Request req, Response res, Handler final_) throws Exception {
    if (idx >= chain.size()) {
        final_.handle(req, res);  // semua middleware selesai → jalankan handler
        return;
    }
    // jalankan middleware ke-idx, berikan "next" yang akan memanggil run(idx+1, ...)
    chain.get(idx).execute(req, res, (r, rr) -> run(idx + 1, r, rr, final_));
}

Urutan eksekusi: LoggingMiddleware → CorsMiddleware → AuthMiddleware → Controller.

AuthMiddleware selalu membersihkan SecurityContext di blok finally, memastikan data user dari satu request tidak bocor ke request lain yang berjalan di thread yang sama (penting terutama jika thread pool di-reuse).

`Container`

Container adalah DI registry yang paling sederhana yang bisa dibayangkan: sebuah HashMap<Class<?>, Object>.

container.register(DataSource.class, dataSource);   // daftar
DataSource ds = container.get(DataSource.class);    // ambil

Tidak ada magic. Tidak ada reflection. Tidak ada classpath scanning. Seluruh wiring ditulis secara eksplisit di App.java dan setiap Module.

Kenapa pendekatan ini? Karena transparansi. Jika ada masalah dengan dependency, cukup lihat App.java — semua ada di sana, berurutan, tidak tersembunyi di balik annotation.

`Validator`

Validator menggunakan reflection untuk memeriksa annotation di setiap field:

for (Field f : obj.getClass().getDeclaredFields()) {
    if (f.isAnnotationPresent(NotBlank.class) && value.isBlank())
        errors.put(f.getName(), "must not be blank");
}

Annotation yang tersedia: @NotBlank, @NotNull, @Size(min, max), @Email.

Jika ada error, Validator.validate(obj) melempar ValidationException yang berisi Map<String, List<String>> — mapping nama field ke list pesan error. ExceptionHandler menangkap ini dan mengembalikan HTTP 422 dengan detail error per field.

`ExceptionHandler`

Menggunakan pattern matching for switch (Java 21) untuk memetakan exception ke HTTP status code:

if      (t instanceof NotFoundException nx)      res.status(404)...
else if (t instanceof UnauthorizedException ux)  res.status(401)...
else if (t instanceof ValidationException vx)    res.status(422)...
else                                              res.status(500)...

Ini adalah single point of failure handling — seluruh aplikasi hanya punya satu tempat yang menentukan bagaimana error ditampilkan ke client.

`AppModule`

AppModule adalah kontrak yang harus diimplementasikan setiap module bisnis:

public interface AppModule {
    void register(Container container, Router router);
}

Di dalam register(), sebuah module melakukan tiga hal:

Mengambil dependency dari container (misal: DataSource)
Membuat instance repository, service, controller
Mendaftarkan route ke router

Pendekatan ini memberikan setiap module otonomi penuh atas internal wiring-nya, sekaligus menjaga App.java tetap bersih.

Request Lifecycle

Berikut perjalanan lengkap sebuah GET /api/finance/accounts?page=0&keyword=kas:

1. JDK HttpServer menerima TCP connection
   └── Virtual thread baru dibuat untuk request ini

2. WebServer membuat Request dan Response wrapper

3. MiddlewareChain.execute() dipanggil:

   a. LoggingMiddleware
      └── Catat timestamp mulai, teruskan ke next

   b. CorsMiddleware
      └── Tambah Access-Control headers, teruskan ke next

   c. AuthMiddleware
      └── Baca cookie "token"
      └── Parse JWT → extract {id, email, role}
      └── Set SecurityContext.set(new Principal(...))
      └── Teruskan ke next

4. Router.match("GET", "/api/finance/accounts")
   └── Exact match → AccountController::list

5. AccountController.list()
   └── SecurityContext.requireAuthenticated() → OK
   └── Baca query params: page=0, keyword="kas"
   └── Panggil useCase.list(0, 10, "created_at", "desc", "kas")

6. AccountService.list()
   └── Panggil repository.search("kas", 0, 10, "created_at", "desc")

7. AccountRepository (extends BaseRepository)
   └── Build SQL: SELECT id,name,... FROM accounts
                  WHERE is_deleted=false
                  AND LOWER(name) LIKE LOWER('%kas%')
                  ORDER BY created_at DESC LIMIT 10 OFFSET 0
   └── Jalankan via HikariCP connection
   └── Map ResultSet → List<Account> via reflection
   └── Return PageResult<Account>

8. AccountService
   └── PageResult.map(mapper::toResponse)
   └── Return PageResult<AccountResponse>

9. AccountController
   └── res.json(ApiResponse.success(PageResponse.of(result)))
   └── Response body disiapkan sebagai byte[]

10. WebServer (finally block)
    └── res.send() → tulis byte[] ke socket

11. AuthMiddleware (finally block)
    └── SecurityContext.clear()

12. LoggingMiddleware (setelah next() selesai)
    └── Catat: "GET /api/finance/accounts → 200 (12ms)"

Dependency Injection

Framework ini tidak menggunakan DI container otomatis. Semua wiring dilakukan secara manual dan eksplisit.

Di `App.java`

// 1. Buat infrastructure objects
AppConfig  config     = AppConfig.load();
DataSource dataSource = DataSource.create(config);
JwtUtil    jwtUtil    = new JwtUtil(config.getJwtSecret(), config.getJwtExpirationMs());

// 2. Daftarkan ke container
Container container = new Container();
container.register(DataSource.class, dataSource);
container.register(JwtUtil.class, jwtUtil);

// 3. Boot semua module
ModuleRegistry modules = new ModuleRegistry();
modules.register(new FinanceModule());
modules.boot(container, router);

Di `FinanceModule`

public void register(Container container, Router router) {
    DataSource ds = container.get(DataSource.class);  // ambil dari container

    // buat instance secara manual — tidak ada @Autowired
    AccountRepository accountRepo = new AccountRepository(ds);
    AccountService    accountSvc  = new AccountService(accountRepo);
    AccountController accountCtrl = new AccountController(accountSvc);

    // daftarkan route
    router.get("/api/finance/accounts", accountCtrl::list);
    ...
}

Keuntungan pendekatan ini:

Mudah di-trace: ikuti saja kode dari App.java ke bawah
Mudah di-test: tidak perlu Spring Test Context
Compile-time safe: jika dependency tidak ada, langsung error saat kompilasi
Zero reflection overhead saat startup

Routing

Registrasi Route

Route didaftarkan di setiap {Module}Module.java:

// Urutan penting: exact routes dulu, baru pattern routes
router.get("/api/finance/accounts/export/pdf",   accountCtrl::exportPdf);   // exact
router.get("/api/finance/accounts/export/excel", accountCtrl::exportExcel); // exact
router.get("/api/finance/accounts/export/csv",   accountCtrl::exportCsv);   // exact
router.get("/api/finance/accounts/:id",          accountCtrl::getById);      // pattern
router.get("/api/finance/accounts",              accountCtrl::list);          // exact
router.post("/api/finance/accounts",             accountCtrl::create);        // exact
router.put("/api/finance/accounts/:id",          accountCtrl::update);        // pattern
router.delete("/api/finance/accounts/:id",       accountCtrl::delete);        // pattern

Endpoint Standar Per Entity

Method	Path	Handler
`GET`	`/api/{module}/{resource}`	`list` — paginasi + filter
`GET`	`/api/{module}/{resource}/:id`	`getById`
`POST`	`/api/{module}/{resource}`	`create`
`PUT`	`/api/{module}/{resource}/:id`	`update`
`DELETE`	`/api/{module}/{resource}/:id`	`delete` (soft)
`GET`	`/api/{module}/{resource}/export/pdf`	`exportPdf`
`GET`	`/api/{module}/{resource}/export/excel`	`exportExcel`
`GET`	`/api/{module}/{resource}/export/csv`	`exportCsv`

Query Parameters untuk `list`

GET /api/finance/accounts?page=0&perPage=10&sortBy=name&direction=asc&keyword=kas

Parameter	Default	Keterangan
`page`	`0`	Nomor halaman (0-based)
`perPage`	`10`	Jumlah item per halaman
`sortBy`	`created_at`	Kolom untuk sorting
`direction`	`desc`	`asc` atau `desc`
`keyword`	``	Filter nama (LIKE)

Authentication & Session

Mengapa HttpOnly Cookie, Bukan Bearer Token?

Penyimpanan JWT di localStorage atau sessionStorage rentan terhadap serangan XSS (Cross-Site Scripting). Script yang berhasil diinjeksikan ke halaman bisa membaca token dan mengirimnya ke server penyerang.

HttpOnly cookie tidak bisa diakses oleh JavaScript sama sekali. Browser mengirimkannya secara otomatis di setiap request, dan hanya server yang bisa membaca atau menghapusnya.

Set-Cookie: token=eyJhbGc...; HttpOnly; Path=/; SameSite=Strict; Max-Age=86400
                              ─────────── ──────── ────────────── ────────────
                              JS tidak     Semua   Blok CSRF via   Expired 24 jam
                              bisa akses   path    same-site only

Alur Login

1. POST /api/auth/login  { "email": "...", "password": "..." }

2. AuthService.login()
   ├── Cari user di DB via UserRepository.findByEmail()
   ├── Verifikasi password via BCrypt.checkpw()
   ├── Generate JWT via JwtUtil.generate(userId, {email, role})
   └── Return LoginResult(token, userResponse)

3. AuthController.login()
   └── res.setAuthCookie(token, maxAgeSeconds)
       → Set-Cookie: token=<jwt>; HttpOnly; ...

4. Client menerima cookie — browser menyimpan otomatis

Alur Request Terautentikasi

1. Browser otomatis mengirim cookie di setiap request

2. AuthMiddleware membaca cookie "token"
   ├── Parse JWT → extract claims
   └── SecurityContext.set(new Principal(id, email, role))

3. Controller memanggil SecurityContext.requireAuthenticated()
   ├── Jika Principal ada → lanjut
   └── Jika tidak ada → throw UnauthorizedException → HTTP 401

4. Setelah request selesai (finally):
   └── SecurityContext.clear()  ← PENTING: bersihkan ThreadLocal

Alur Logout

POST /api/auth/logout

AuthController.logout()
└── res.clearAuthCookie()
    → Set-Cookie: token=; HttpOnly; Path=/; Max-Age=0
    ← Browser menghapus cookie

Mengakses User yang Login

Di controller atau service mana pun:

SecurityContext.Principal principal = SecurityContext.requireAuthenticated();
String userId = principal.id();
String email  = principal.email();
String role   = principal.role();

Data Layer / ORM

Cara Kerja `BaseRepository`

BaseRepository<T> menggunakan reflection untuk membangun SQL secara otomatis dari annotation entity. Ini dilakukan sekali di constructor, bukan setiap kali query dieksekusi.

Saat konstruksi:

// BaseRepository membaca annotation @Table dan semua @Column dari class
Table ann = entityClass.getAnnotation(Table.class);
this.tableName = ann.value(); // "accounts"

this.fieldMappings = Arrays.stream(entityClass.getDeclaredFields())
    .filter(f -> f.isAnnotationPresent(Column.class))
    .map(f -> new FieldMapping(f, f.getAnnotation(Column.class).value()))
    .toList();
// [{field: name, col: "name"}, {field: description, col: "description"}, ...]

Saat INSERT:

// Column names dari BaseEntity + fieldMappings
// ["id", "created_at", "updated_at", "is_deleted", "name", "description", "is_active"]
// PreparedStatement dengan ? placeholder untuk setiap kolom

Saat SELECT:

// ResultSet → instance baru via no-arg constructor
// Setiap field di-set via field.set(instance, rs.getObject(col))

Mendefinisikan Entity

@Entity
@Table("products")                       // nama tabel di database
public class Product extends BaseEntity { // id, createdAt, updatedAt, deleted

    @Column("name")
    private String name;

    @Column("price")
    private java.math.BigDecimal price;

    @Column("stock_qty")
    private Integer stockQty;

    @Column("is_active")
    private Boolean isActive = true;

    // getter dan setter untuk setiap field
}

Field yang Dikelola `BaseEntity` (Otomatis)

Field Java	Kolom SQL	Diisi Oleh
`id`	`id` (VARCHAR 36)	`BaseRepository.insert()` → UUID
`createdAt`	`created_at`	`BaseRepository.insert()`
`updatedAt`	`updated_at`	`BaseRepository.insert()` + `update()`
`deletedAt`	`deleted_at`	`BaseRepository.softDelete()`
`deleted`	`is_deleted`	`BaseRepository.softDelete()`

Custom Query di Repository

Untuk query yang tidak bisa ditangani BaseRepository, tambahkan method langsung:

public class ProductRepository extends BaseRepository<Product> {

    public ProductRepository(DataSource ds) { super(ds, Product.class); }

    // Custom query: produk berdasarkan kategori
    public List<Product> findByCategoryId(String categoryId) {
        String sql = "SELECT " + cols() + " FROM products "
                   + "WHERE category_id = ? AND is_deleted = false";
        try (Connection c = dataSource.getConnection();
             PreparedStatement ps = c.prepareStatement(sql)) {
            ps.setString(1, categoryId);
            ResultSet rs = ps.executeQuery();
            List<Product> results = new ArrayList<>();
            while (rs.next()) results.add(map(rs));   // map() dari BaseRepository
            return results;
        } catch (Exception e) {
            throw new RuntimeException("findByCategoryId failed", e);
        }
    }
}

cols() dan map() adalah protected method dari BaseRepository yang bisa digunakan oleh subclass.

Soft Delete

Semua operasi delete tidak menghapus data dari database. BaseRepository.softDelete() hanya mengupdate:

UPDATE accounts SET is_deleted = true, deleted_at = NOW() WHERE id = ?

Semua query search() dan findById() otomatis menyertakan WHERE is_deleted = false, sehingga data yang di-soft-delete tidak muncul di hasil query tanpa tindakan khusus.

Membuat Module Baru

Ilustrasi: membuat module Logistics dengan entity Shipment.

Langkah 1 — Tambahkan di `MODULES` (generator)

Buka generate-project.sh dan tambahkan entry baru:

MODULES["Logistics"]="
shipments:Shipment
carriers:Carrier
shipping_routes:ShippingRoute
"

Jalankan generator ulang. Semua file skeleton akan dibuat otomatis.

Langkah 2 — Daftarkan di `App.java`

import com.company.erp.modules.logistics.LogisticsModule;

// di dalam main():
modules.register(new LogisticsModule());

Langkah 3 — Tambahkan DDL di `schema.sql`

CREATE TABLE IF NOT EXISTS shipments (
    id           VARCHAR(36)  NOT NULL PRIMARY KEY,
    name         VARCHAR(200) NOT NULL,
    description  TEXT,
    is_active    BOOLEAN      NOT NULL DEFAULT TRUE,
    -- tambahkan kolom bisnis di sini
    tracking_no  VARCHAR(100),
    status       VARCHAR(50)  NOT NULL DEFAULT 'PENDING',
    created_at   TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at   TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at   TIMESTAMP,
    is_deleted   BOOLEAN      NOT NULL DEFAULT FALSE
);

Membuat Entity Baru

Ilustrasi: menambah entity Warehouse ke module Inventory secara manual (tanpa generator).

1. Entity Class

// src/.../modules/inventory/warehouse/Warehouse.java
@Entity
@Table("warehouses")
public class Warehouse extends BaseEntity {

    @Column("name")     private String  name;
    @Column("address")  private String  address;
    @Column("city")     private String  city;
    @Column("capacity") private Integer capacity;
    @Column("is_active") private Boolean isActive = true;

    // getter dan setter
}

2. UseCase Interface

// Warehouse UseCase.java
public interface WarehouseUseCase {
    PageResult<WarehouseResponse> list(int page, int perPage,
                                       String sortBy, String direction, String keyword);
    WarehouseResponse getById(String id);
    WarehouseResponse create(WarehouseRequest request);
    WarehouseResponse update(String id, WarehouseRequest request);
    void delete(String id);
    byte[] exportPdfBytes();
    byte[] exportExcelBytes();
    byte[] exportCsvBytes();
}

3. Repository

public class WarehouseRepository extends BaseRepository<Warehouse> {
    public WarehouseRepository(DataSource ds) { super(ds, Warehouse.class); }
    // tambahkan custom query jika diperlukan
}

4. Service

public class WarehouseService implements WarehouseUseCase {
    private final WarehouseRepository repository;
    private final WarehouseMapper mapper = new WarehouseMapper();

    public WarehouseService(WarehouseRepository repository) {
        this.repository = repository;
    }

    @Override
    public PageResult<WarehouseResponse> list(...) {
        return repository.search(keyword, page, perPage, sortBy, direction)
                         .map(mapper::toResponse);
    }
    // ... implementasi method lainnya
}

5. Daftarkan di Module

Buka InventoryModule.java dan tambahkan:

WarehouseRepository warehouseRepo = new WarehouseRepository(ds);
WarehouseService    warehouseSvc  = new WarehouseService(warehouseRepo);
WarehouseController warehouseCtrl = new WarehouseController(warehouseSvc);

router.get("/api/inventory/warehouses/export/pdf",   warehouseCtrl::exportPdf);
router.get("/api/inventory/warehouses/export/excel", warehouseCtrl::exportExcel);
router.get("/api/inventory/warehouses/export/csv",   warehouseCtrl::exportCsv);
router.get("/api/inventory/warehouses/:id",          warehouseCtrl::getById);
router.get("/api/inventory/warehouses",              warehouseCtrl::list);
router.post("/api/inventory/warehouses",             warehouseCtrl::create);
router.put("/api/inventory/warehouses/:id",          warehouseCtrl::update);
router.delete("/api/inventory/warehouses/:id",       warehouseCtrl::delete);

6. Tambahkan DDL

-- di schema.sql
CREATE TABLE IF NOT EXISTS warehouses (
    id          VARCHAR(36)  NOT NULL PRIMARY KEY,
    name        VARCHAR(200) NOT NULL,
    address     TEXT,
    city        VARCHAR(100),
    capacity    INTEGER,
    is_active   BOOLEAN      NOT NULL DEFAULT TRUE,
    created_at  TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at  TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
    deleted_at  TIMESTAMP,
    is_deleted  BOOLEAN      NOT NULL DEFAULT FALSE
);

Menjalankan Project

Prasyarat

Java 21+ (java -version)
Maven 3.8+ (mvn -version)

Langkah 1 — Generate Project

chmod +x generate-project.sh
./generate-project.sh

Generator akan membuat seluruh struktur project di direktori saat ini.

Langkah 2 — Compile

mvn clean compile

Langkah 3 — Jalankan (Mode Development)

mvn compile exec:java

Server berjalan di http://localhost:8080. Database H2 in-memory otomatis dibuat.

Langkah 4 — Verifikasi

# Login
curl -c cookies.txt -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}'

# List accounts (kirim cookie otomatis)
curl -b cookies.txt http://localhost:8080/api/finance/accounts

Konfigurasi

Edit src/main/resources/application.properties:

server.port=8080

# Development (H2 in-memory)
db.url=jdbc:h2:mem:erpdb;DB_CLOSE_DELAY=-1;NON_KEYWORDS=VALUE
db.user=sa
db.password=

# JWT
jwt.secret=ganti-dengan-secret-minimal-256-bit-di-production
jwt.expiration.ms=86400000

Untuk production, gunakan environment variable:

export DB_URL=jdbc:postgresql://localhost:5432/erpdb
export DB_USER=appuser
export DB_PASSWORD=secret
export JWT_SECRET=super-secret-production-key

mvn package
java -jar target/erp-app-1.0.0-SNAPSHOT.jar

Membangun Fat JAR

mvn package
java -jar target/erp-app-1.0.0-SNAPSHOT.jar

Menjalankan Test

# Semua test
mvn test

# Test spesifik
mvn test -Dtest=AuthServiceTest

# Test dengan output verbose
mvn test -Dtest=AuthServiceTest -pl . --no-transfer-progress

Cara Menulis Unit Test

Unit test di framework ini tidak butuh Spring Test Context, tidak butuh embedded server. Cukup instantiasi Service dengan mock Repository:

@ExtendWith(MockitoExtension.class)
class AccountServiceTest {

    @Mock AccountRepository repository;
    AccountService service;

    @BeforeEach
    void setUp() {
        service = new AccountService(repository);  // inject mock langsung
    }

    @Test
    void getById_found() {
        Account entity = new Account();
        entity.setId("abc"); entity.setName("Kas");

        when(repository.findById("abc")).thenReturn(Optional.of(entity));

        AccountResponse resp = service.getById("abc");

        assertThat(resp.getName()).isEqualTo("Kas");
    }

    @Test
    void getById_notFound() {
        when(repository.findById("x")).thenReturn(Optional.empty());

        assertThatThrownBy(() -> service.getById("x"))
            .isInstanceOf(NotFoundException.class)
            .hasMessageContaining("x");
    }
}

Tidak ada @SpringBootTest, tidak ada @MockBean, tidak ada startup overhead. Test selesai dalam milidetik.

Contoh Lengkap CRUD Module

Berikut adalah contoh end-to-end untuk module CRM dengan entity Contact.

Login dan Dapatkan Cookie

curl -c cookies.txt -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}' | python3 -m json.tool

Response:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "email": "admin@example.com",
    "role": "ADMIN"
  }
}

Cookie token otomatis tersimpan di cookies.txt.

Create Contact

curl -b cookies.txt -s -X POST http://localhost:8080/api/crm/contacts \
  -H "Content-Type: application/json" \
  -d '{"name":"Budi Santoso","description":"Lead dari LinkedIn","isActive":true}' \
  | python3 -m json.tool

Response:

{
  "success": true,
  "message": "Contact created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Budi Santoso",
    "description": "Lead dari LinkedIn",
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-15T10:30:00"
  }
}

List dengan Pagination dan Filter

curl -b cookies.txt -s \
  "http://localhost:8080/api/crm/contacts?page=0&perPage=5&keyword=budi&sortBy=name&direction=asc" \
  | python3 -m json.tool

Response:

{
  "success": true,
  "message": "Success",
  "data": {
    "data": [
      { "id": "550e...", "name": "Budi Santoso", ... }
    ],
    "total": 1,
    "page": 0,
    "perPage": 5,
    "totalPages": 1
  }
}

Get By ID

curl -b cookies.txt -s \
  http://localhost:8080/api/crm/contacts/550e8400-e29b-41d4-a716-446655440000 \
  | python3 -m json.tool

Update

curl -b cookies.txt -s -X PUT \
  http://localhost:8080/api/crm/contacts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{"name":"Budi Santoso","description":"Prospek potensial","isActive":true}' \
  | python3 -m json.tool

Export

# PDF
curl -b cookies.txt -o contacts.pdf \
  http://localhost:8080/api/crm/contacts/export/pdf

# Excel
curl -b cookies.txt -o contacts.xlsx \
  http://localhost:8080/api/crm/contacts/export/excel

# CSV
curl -b cookies.txt -o contacts.csv \
  http://localhost:8080/api/crm/contacts/export/csv

Delete (Soft)

curl -b cookies.txt -s -X DELETE \
  http://localhost:8080/api/crm/contacts/550e8400-e29b-41d4-a716-446655440000 \
  | python3 -m json.tool

Data tidak benar-benar dihapus dari database. is_deleted = true dan deleted_at diisi.

Error Handling

401 Unauthorized (tidak login):

{ "success": false, "message": "Authentication required" }

404 Not Found:

{ "success": false, "message": "Contact not found: abc123" }

422 Validation Error:

{
  "success": false,
  "message": "Validation failed",
  "data": {
    "name": ["must not be blank"],
    "email": ["invalid email format"]
  }
}

Roadmap

Framework ini masih dalam pengembangan aktif. Berikut fitur yang direncanakan:

v0.2 — Robustness

Circular dependency detection di Container
Request body size limit untuk mencegah OOM attack
Connection pool monitoring — expose metrik HikariCP
Graceful shutdown — tunggu request yang sedang diproses sebelum mati
Rate limiting middleware — batasi request per IP

v0.3 — Developer Experience

Hot reload — deteksi perubahan file dan restart otomatis
Route inspector — endpoint GET /_routes untuk list semua route terdaftar
Request/Response logging yang bisa dikonfigurasi (level, format)
Environment profiles — dev, staging, prod dengan konfigurasi berbeda

v0.4 — Query Power

Join support di BaseRepository via annotation @JoinColumn
Transactions — @Transactional manual atau BaseRepository.withTransaction()
Bulk insert/update untuk operasi batch
Soft delete filter yang bisa dinonaktifkan untuk admin endpoint
Database migration — built-in versi sederhana Flyway

v0.5 — Module System

Inter-module event bus — module bisa publish/subscribe event tanpa direct coupling
Module isolation — option untuk menjalankan module di classloader terpisah
Lazy module loading — module hanya di-load jika ada request ke route-nya

v0.6 — Security

Role-based access control via @RequiresRole("ADMIN") pada controller method
CSRF protection dengan double-submit cookie pattern
Token refresh — silent refresh sebelum JWT expire
Audit log — catat semua operasi write per user

v1.0 — Production Ready

Distributed tracing — trace ID per request yang diteruskan ke downstream service
Health check endpoint — GET /health dengan status DB, memory, dll
Metrics endpoint — GET /metrics kompatibel dengan Prometheus
WebSocket support — upgrade HTTP connection ke WebSocket
File upload — multipart form data handling
Comprehensive documentation — JavaDoc untuk semua public API

Lisensi

MIT License — bebas digunakan, dimodifikasi, dan didistribusikan.

Berkontribusi

Pull request disambut baik. Untuk perubahan besar, buka issue terlebih dahulu untuk mendiskusikan apa yang ingin diubah.

Pastikan test tetap passing: mvn test

Dibuat dengan ☕ dan rasa ingin tahu yang tidak kunjung padam.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
README.md		README.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

☕ Framework

Daftar Isi

Tentang Project

Apa yang Bisa Dilakukan

Stack Teknis

Masalah yang Diselesaikan

1. "Framework sebagai black box"

2. "Annotation magic yang tidak transparan"

3. "Dependency bloat"

4. "Boilerplate yang tidak terkontrol"

Filosofi Desain

Eksplisit Lebih Baik dari Implisit

Satu Layer, Satu Tanggung Jawab

Library, Bukan Framework atas Framework

Testability by Default

Arsitektur

Struktur Folder

Framework Components

WebServer

Router

Request dan Response

MiddlewareChain

Container

Validator

ExceptionHandler

AppModule

Request Lifecycle

Dependency Injection

Di App.java

Di FinanceModule

Routing

Registrasi Route

Endpoint Standar Per Entity

Query Parameters untuk list

Authentication & Session

Mengapa HttpOnly Cookie, Bukan Bearer Token?

Alur Login

Alur Request Terautentikasi

Alur Logout

Mengakses User yang Login

Data Layer / ORM

Cara Kerja BaseRepository

Mendefinisikan Entity

Field yang Dikelola BaseEntity (Otomatis)

Custom Query di Repository

Soft Delete

Membuat Module Baru

Langkah 1 — Tambahkan di MODULES (generator)

Langkah 2 — Daftarkan di App.java

Langkah 3 — Tambahkan DDL di schema.sql

Membuat Entity Baru

1. Entity Class

2. UseCase Interface

3. Repository

4. Service

5. Daftarkan di Module

6. Tambahkan DDL

Menjalankan Project

Prasyarat

Langkah 1 — Generate Project

Langkah 2 — Compile

Langkah 3 — Jalankan (Mode Development)

Langkah 4 — Verifikasi

Konfigurasi

Membangun Fat JAR

Menjalankan Test

Cara Menulis Unit Test

Contoh Lengkap CRUD Module

Login dan Dapatkan Cookie

Create Contact

List dengan Pagination dan Filter

Get By ID

Update

Export

Delete (Soft)

Error Handling

`WebServer`

`Router`

`Request` dan `Response`

`MiddlewareChain`

`Container`

`Validator`

`ExceptionHandler`

`AppModule`

Di `App.java`

Di `FinanceModule`

Query Parameters untuk `list`

Cara Kerja `BaseRepository`

Field yang Dikelola `BaseEntity` (Otomatis)

Langkah 1 — Tambahkan di `MODULES` (generator)

Langkah 2 — Daftarkan di `App.java`

Langkah 3 — Tambahkan DDL di `schema.sql`

Packages