RayLab-Core/Docs/Phase-04-Technical-Foundation.md

# RayLab Core Phase 4 --- Technical Foundation

## Tujuan

Fase 4 menetapkan fondasi teknis RayLab Core. Dokumen ini mendefinisikan
teknologi, konvensi pengembangan, dan standar implementasi yang akan
digunakan secara konsisten pada seluruh modul.

------------------------------------------------------------------------

# Tujuan Akhir

Project dapat dijalankan dengan satu perintah:

``` bash
docker compose up -d
```

Kemudian endpoint health dapat diakses:

``` text
GET /health
```

Response:

``` json
{
  "status": "ok"
}
```

------------------------------------------------------------------------

# Technology Stack

## Backend Framework

**NestJS**

Alasan:

-   Modular architecture
-   Dependency Injection
-   Guard, Middleware, Interceptor
-   Swagger integration
-   Testing support
-   Sangat cocok untuk aplikasi enterprise.

------------------------------------------------------------------------

## Programming Language

**TypeScript**

Keuntungan:

-   Type safety
-   Maintainability
-   IDE support
-   Konsisten dengan NestJS

------------------------------------------------------------------------

## Database

**PostgreSQL**

Digunakan sebagai database utama RayLab Core.

Semua data aplikasi disimpan di PostgreSQL.

------------------------------------------------------------------------

## ORM

**Prisma**

Keuntungan:

-   Type-safe query
-   Migration
-   Schema management
-   Autocomplete
-   Maintainable

------------------------------------------------------------------------

## Cache

**Redis**

Digunakan untuk:

-   Session
-   Cache
-   Rate limiting
-   Queue (apabila diperlukan)

Redis bukan penyimpanan data utama.

------------------------------------------------------------------------

## API Documentation

**Swagger (OpenAPI)**

Seluruh endpoint wajib memiliki dokumentasi.

Minimal mencakup:

-   Summary
-   Description
-   Request DTO
-   Response DTO
-   Error Response

------------------------------------------------------------------------

## Validation

Menggunakan:

-   class-validator
-   class-transformer

Seluruh request divalidasi sebelum masuk business logic.

------------------------------------------------------------------------

## Logging

Menggunakan:

**Pino**

Target:

-   Structured Logging
-   Performance
-   Mudah diintegrasikan dengan monitoring.

------------------------------------------------------------------------

## Testing

Standar pengujian:

### Unit Test

-   Jest

### Integration Test

-   Jest

### End-to-End Test

-   Playwright

Standar ini mengikuti roadmap pengujian RayLab.

------------------------------------------------------------------------

## Containerization

Seluruh aplikasi dijalankan menggunakan Docker.

Container utama:

-   raylab-core
-   postgres-raylab
-   redis

------------------------------------------------------------------------

## Configuration

Konfigurasi menggunakan:

-   .env
-   NestJS Config Module

Business logic tidak boleh mengakses process.env secara langsung.

------------------------------------------------------------------------

# Coding Convention

## Dependency Injection

Semua dependency menggunakan Dependency Injection NestJS.

Tidak diperbolehkan:

``` typescript
new UserRepository();
```

------------------------------------------------------------------------

## Naming Convention

Folder:

``` text
users
groups
authorization
registry
```

Class:

``` text
UserService
UsersController
UserRepository
CreateUserDto
```

------------------------------------------------------------------------

## UUID

Seluruh entity menggunakan UUID v7 sebagai primary key.

Tidak menggunakan integer auto increment.

------------------------------------------------------------------------

## API Versioning

Semua endpoint menggunakan format:

``` text
/api/v1/
```

Perubahan besar menggunakan versi API baru.

------------------------------------------------------------------------

## Standard Response

### Success

``` json
{
  "success": true,
  "data": {},
  "meta": {}
}
```

### Error

``` json
{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User not found"
  }
}
```

------------------------------------------------------------------------

# Development Convention

Seluruh modul wajib mengikuti aturan berikut.

-   Satu module mewakili satu domain bisnis.
-   Tidak ada query database di Controller.
-   Tidak ada business logic di Frontend.
-   Integrasi eksternal hanya melalui Adapter.
-   Seluruh endpoint memiliki DTO.
-   Seluruh endpoint memiliki validasi.
-   Seluruh endpoint memiliki dokumentasi Swagger.
-   Seluruh perubahan penting menghasilkan Audit Log.
-   Seluruh modul dapat diuji secara mandiri.

------------------------------------------------------------------------

# Struktur Project

``` text
raylab-core/

├── src/
├── prisma/
├── docs/
├── tests/
├── scripts/
├── docker/
├── package.json
├── docker-compose.yml
└── README.md
```

------------------------------------------------------------------------

# Hasil Akhir Fase 4

Setelah fase ini selesai, RayLab Core memiliki fondasi teknis yang
konsisten, modern, dan siap digunakan sebagai dasar implementasi seluruh
modul pada fase berikutnya.

Dokumen ini menjadi acuan resmi untuk pemilihan teknologi, standar
coding, struktur project, dan konvensi pengembangan RayLab Core.