🚀 Production Ready

Soulcode API Boilerplate

Template project TypeScript + Express.js untuk membangun REST API yang scalable, type-safe, dan production-ready untuk ekosistem Soulcode.

100%

TypeScript Strict

DDD

Architecture

Auto

Route Loading

Built-in

Validation

🎯 Mengapa Soulcode Boilerplate?

Solusi lengkap untuk development API yang cepat, aman, dan terstruktur dengan best practices industri.

Domain-Driven Design — Struktur terorganisir berdasarkan domain bisnis
Type-Safe — Full TypeScript dengan strict mode aktif
Auto-Routing — Automatic route discovery dengan konvensi naming
Built-in Validation — Request validation menggunakan Valibot

Production Ready — Logging, error handling, dan monitoring terintegrasi
Developer Friendly — Hot reload, debugging, dan dokumentasi lengkap
SQL Injection Safe — Parameterized queries by default
Transaction Support — Database transaction management built-in

💡 Filosofi Utama

"Write clean, maintainable code with clear separation of concerns. Every layer has its own responsibility."

🛠️ Tech Stack Modern

Kombinasi teknologi terbaik untuk performa dan developer experience optimal.

Core Framework

⚡ Node.js v20.11.1

🔷 TypeScript Latest

🚂 Express.js

📦 pnpm

Soulcode Internal Libraries

🌐

@soulcodeku/soulcode-http

HTTP server & routing utilities dengan auto-discovery

🗄️

@soulcodeku/soulcode-mysql

MySQL database adapter dengan connection pooling

🛡️

@soulcodeku/soulcode-core-backend

Core utilities, error handling, dan exception classes

📨

@soulcodeku/soulcode-rabbitmq

Message broker integration untuk background processing

Development Tools

⚡ tsx (Hot Reload)

🔍 ESLint

🧪 Jest

✅ Valibot

🏗️ Layered Architecture

Domain-Driven Design dengan pemisahan concerns yang jelas dan dependency injection.

🎮 Controller — Handle HTTP requests & responses

⬇️

⚙️ Service — Business logic & external service calls

⬇️

🗄️ Repository — Database operations (INSERT/UPDATE/DELETE)

⬇️

📊 Queries — SELECT operations & data retrieval

📁 Domain

Business rules dan entities. Wajib unit test!

🔄 Use Case

Flow orchestration untuk kompleks business process

🛠️ Helper

Utility functions. Wajib unit test!

📁 Struktur Project

Organisasi kode yang intuitif berdasarkan domain bisnis.

Project Explorer

📂 rest-boilerplate-ts/

├── 🗂️ database/ # Database migrations

├── 📂 src/

└── 🚀 app/

├── 🌐 http/ # REST API endpoints

└── 📦 [domain]/[feature]/

├── 📄 *.controller.ts

├── ⚙️ use-case/ # Orchestration

└── 🗄️ repo/ & queries/ # DB Logic

├── ⚡ libs/ # Shared Utilities

└── 📦 storage/ # Logs & Static Files

🎯

Konvensi Penamaan

Folder: kebab-case | Class: PascalCase | Variable: camelCase

🚀 Quick Start Guide

Dari clone sampai running dalam 5 menit!

1

Clone Repository

                        git clone <repository-url> &&
                        cd rest-boilerplate-ts
                    

2

Setup NPM Registry

                        npm login --registry=https://npm.pkg.github.com
                        --scope=@soulcodeku
                    

3

Install & Configure

                        pnpm install

                        cp .env.example .env # Edit konfigurasi
                            database
                    

4

Run Development Server

                        pnpm dev # Server running di
                            http://localhost:3000
                    

✓

Test API

curl http://localhost:3000/api/health

🔐 Security & Validation

Keamanan terintegrasi dari awal development.

🛡️

Request Validation

Schema validation menggunakan Valibot dengan type inference otomatis ke TypeScript

🔒

SQL Injection Prevention

Parameterized queries by default — tidak ada raw query tanpa sanitasi

⚠️

Error Handling

Exception classes dari soulcode-core-backend dengan proper HTTP status codes

📝

Structured Logging

Context object logging untuk debugging dan monitoring production

                // Contoh: Validation Schema dengan Valibot
                import * as v from 'valibot';

                export const CreateUserRequest = v.object({
                email: v.pipe(v.string(), v.email()),
                name: v.pipe(v.string(), v.minLength(3)),
                role: v.union([v.literal('admin'), v.literal('user')])
                });
            

🗄️ Database Strategy

MySQL integration dengan best practices untuk performance dan maintenance.

Connection Management

Connection pooling dengan limit configurable
Auto-reconnect dan error recovery
Transaction support untuk data consistency

Query Optimization

raw() untuk query sederhana
rawQuery() untuk complex queries
Parameterized queries untuk keamanan

Migration Naming Convention

Tipe	Format	Contoh	Kapan Digunakan
Product Backlog	`PB-x.x.x.sql`	`PB-1.2.0.sql`	Feature development
Production Issue	`YYYYMMDDHHmmss.sql`	`20240121143000.sql`	Hotfix production

🔀 Git Workflow

Branching strategy yang terstruktur untuk development yang aman.

🌿 Feature Development

dev → feature/nama-fitur → PR ke dev

Develop fitur baru
Code review & testing
Merge ke dev

🚨 Production Hotfix

main → hotfix/issue-name → PR ke main & dev

Fix critical issue
Deploy immediately
Sync ke dev

🐛 Bug Fixes

dev → bugfix/bug-name → PR ke dev

Fix non-critical bugs
Testing di dev
Merge setelah review

🚀 Deployment

dev → PR ke main → Deploy

Comprehensive testing
Staging validation
Production deploy

                📝 Conventional Commits
                
                    feat: | fix: | docs: | refactor: | test: | chore:

🐳 Containerization

Docker & Production Ready

Deploy dengan mudah menggunakan Docker untuk lingkungan yang konsisten dan scalable.

🐳

Docker Support

Siap pakai dengan Dockerfile dan docker-compose.yml untuk development maupun production.

🚀

Multi-stage Builds

Optimasi image size untuk production yang lebih ringan dan aman (hanya runtime dependencies).

                # Jalankan environment lengkap (App + DB)

                docker-compose up -d --build

                # Health check otomatis untuk memastikan service siap

✅ Production Ready Checklist
                    Graceful Shutdown handling
                        
Process Management
                            (PM2/Docker)

                    Automated Health Checks
Environment Variable
                            Validation

                

🎨 Best Practices

Standar kode yang wajib diikuti untuk maintainability.

📐

Layer Responsibilities

Domain = Business rules, Queries = SELECT, Repo = Write operations, Use-case = Orchestration

🧪

Testing Wajib

Unit test wajib untuk layer Domain dan Helper. Integration test untuk flow lengkap

🚫

Error Handling

Gunakan exception classes. Tidak boleh try-catch sembarangan di layer tertentu

Siap Membangun API Production-Ready? 🚀

Mulai dengan Soulcode Boilerplate dan fokus pada business logic, bukan infrastruktur!

⚡

Fast Development

🛡️

Secure by Default

📈

Scalable