03 — Architecture #

Modular monolith Laravel. Service layer + event-driven + repository pattern. Same codebase untuk standalone & SaaS via APP_MODE flag.

1. Architectural Principles #

1. Modular monolith — semua modul (FO, CM, BE, POS, Acc, AI, pSEO) dalam 1 Laravel app, dipisah via app/Modules/{Module}/ namespace.
2. Service layer — logic bisnis di Services\*, controller hanya orchestrate.
3. Event-driven — operasi penting fire event; listener tangani side-effect (queue, GL post, notification).
4. Repository pattern — abstract DB access di Repositories\* untuk testability.
5. Format-based adapter — integrasi pihak ketiga via adapter berdasarkan format API, bukan per vendor (sesuai global rule "no hardcoded providers").
6. Standalone-first, SaaS-compatible — codebase identik, mode dipilih runtime via APP_MODE.
7. Append-only audit — semua perubahan kritis tercatat di audit_logs.
8. Idempotency by default — semua webhook & external mutation pakai idempotency_key.

2. Folder Structure #

app/
├── Console/
│   └── Commands/                 # artisan commands
│       ├── NightAuditCommand.php
│       ├── OtaSyncCommand.php
│       ├── PseoSitemapCommand.php
│       └── LicenseHeartbeatCommand.php
├── Events/                        # domain events
│   ├── ReservationCreated.php
│   ├── ReservationCheckedIn.php
│   ├── FolioCharged.php
│   ├── PaymentReceived.php
│   ├── OtaBookingIngested.php
│   └── ...
├── Listeners/                     # event handlers (queue-able)
│   ├── PostFolioToGl.php
│   ├── SendConfirmationEmail.php
│   ├── SyncRoomToOta.php
│   ├── NotifyHousekeeping.php
│   └── ...
├── Http/
│   ├── Controllers/
│   │   ├── Admin/                # admin panel routes
│   │   ├── Owner/                # owner-only routes
│   │   ├── Staff/                # staff (FO/HK/POS/Acc) routes
│   │   ├── Guest/                # public guest portal
│   │   ├── Api/                  # REST API
│   │   └── Webhook/              # OTA webhooks, payment callbacks
│   ├── Middleware/
│   │   ├── RequirePair.php       # license pairing gate
│   │   ├── EnsureProperty.php    # multi-property scope
│   │   ├── TenantInitializer.php # SaaS only
│   │   └── AuditLogger.php
│   └── Requests/                 # FormRequest validators
├── Models/
│   ├── Property.php
│   ├── Room.php
│   ├── RoomType.php
│   ├── RatePlan.php
│   ├── Reservation.php
│   ├── Guest.php
│   ├── Folio.php
│   ├── Charge.php
│   ├── Payment.php
│   ├── HousekeepingTask.php
│   ├── PosOrder.php
│   ├── GlAccount.php
│   ├── JournalEntry.php
│   ├── Provider.php              # BYOK integration provider
│   ├── License.php
│   └── ...
├── Modules/                       # business logic per modul
│   ├── FrontOffice/
│   │   ├── Services/
│   │   │   ├── ReservationService.php
│   │   │   ├── CheckInService.php
│   │   │   ├── NightAuditService.php
│   │   │   └── RoomAssignmentService.php
│   │   ├── Repositories/
│   │   ├── DTOs/
│   │   └── Policies/
│   ├── ChannelManager/
│   │   ├── Services/
│   │   ├── Adapters/             # format-based adapters
│   │   │   ├── BookingComAdapter.php
│   │   │   ├── AgodaAdapter.php
│   │   │   ├── TravelokaAdapter.php
│   │   │   └── ChannelAdapterInterface.php
│   │   ├── Jobs/
│   │   │   ├── PushAvailabilityJob.php
│   │   │   ├── PullBookingsJob.php
│   │   │   └── ResolveConflictJob.php
│   │   └── DTOs/
│   ├── BookingEngine/
│   ├── Pos/
│   ├── Housekeeping/
│   ├── Accounting/
│   │   ├── Services/
│   │   │   ├── GlPostingService.php
│   │   │   ├── ReportService.php
│   │   │   └── EFakturService.php
│   │   └── Posting/
│   │       └── PostingRules.php
│   ├── Ai/
│   │   ├── Services/
│   │   │   ├── AiClient.php
│   │   │   └── ConciergeService.php
│   │   ├── Adapters/             # FORMAT-based, not vendor
│   │   │   ├── OpenAICompatibleAdapter.php
│   │   │   ├── AnthropicFormatAdapter.php
│   │   │   ├── GeminiFormatAdapter.php
│   │   │   └── AiAdapterInterface.php
│   │   └── DTOs/
│   ├── Payment/
│   │   ├── Adapters/             # FORMAT-based payment
│   │   │   ├── RedirectFlowAdapter.php
│   │   │   ├── EmbedFlowAdapter.php
│   │   │   ├── QrisFlowAdapter.php
│   │   │   └── PaymentAdapterInterface.php
│   │   └── Services/
│   ├── Pseo/
│   │   ├── Services/
│   │   │   ├── PseoRouteResolver.php
│   │   │   ├── ContentGenerator.php
│   │   │   └── SitemapGenerator.php
│   │   └── Templates/
│   ├── Compliance/                # Indonesia-specific
│   │   ├── Services/
│   │   │   ├── Pb1Service.php
│   │   │   ├── EFakturService.php
│   │   │   ├── LaporWnaService.php
│   │   │   └── KtpOcrService.php
│   ├── License/
│   │   ├── Services/
│   │   │   ├── LicenseClient.php       # adopt v3 from whitelabel
│   │   │   └── PairingService.php
│   │   └── Middleware/
│   ├── Tenancy/
│   │   ├── Bootstrappers/
│   │   └── Services/
│   └── ...
├── Providers/
│   ├── AppServiceProvider.php
│   ├── EventServiceProvider.php
│   ├── RouteServiceProvider.php
│   ├── ModuleServiceProvider.php  # auto-register modules
│   ├── TenancyServiceProvider.php # SaaS only
│   └── AdapterServiceProvider.php # bind format adapters
└── Support/
    ├── Money.php                  # value object Rp dengan presisi
    ├── DateRange.php
    └── ...

config/
├── app.php
├── hotel.php                      # global hotel config
├── modes.php                      # standalone / saas mode flags
├── tenancy.php                    # SaaS only
├── license.php                    # client kit v3 config
├── ai.php                         # default adapter config
├── ota.php                        # OTA defaults
├── pseo.php                       # pSEO routes & templates
└── ...

database/
├── migrations/
│   ├── shared/                    # jalan di standalone & SaaS tenant DB
│   ├── landlord/                  # SaaS central DB only
│   └── tenant/                    # SaaS tenant DB only (= shared sebenarnya)
├── seeders/
│   ├── ProductionSeeder.php
│   ├── DemoSeeder.php
│   └── ...
└── factories/

resources/
├── views/
│   ├── layouts/
│   ├── admin/
│   ├── owner/
│   ├── staff/
│   ├── guest/                     # public booking engine
│   ├── pseo/
│   └── license/
│       ├── pair-wizard.blade.php
│       └── pair-success.blade.php
├── js/
└── css/

routes/
├── web.php
├── admin.php
├── owner.php
├── staff.php
├── guest.php
├── api.php
├── webhook.php
├── pseo.php
├── pair-routes.php                # license v3 from kit
└── tenant.php                     # SaaS only

storage/
└── app/
    ├── llm-presets/               # JSON presets (autofill UI)
    ├── ota-presets/
    ├── payment-presets/
    └── lock-presets/

3. Layer Diagram #

┌─────────────────────────────────────────────────────────────┐
│  HTTP Layer (Controllers)                                   │
│  • Validate request via FormRequest                         │
│  • Authorize via Policy                                     │
│  • Delegate to Service                                      │
│  • Format response (Resource / Blade view)                  │
└──────────────┬──────────────────────────────────────────────┘
               │
┌──────────────▼──────────────────────────────────────────────┐
│  Service Layer (app/Modules/*/Services/*)                   │
│  • Business logic                                           │
│  • Transaction management                                   │
│  • Event dispatching                                        │
│  • Coordinate Repositories + Adapters                       │
└──────────────┬─────────────────────┬────────────────────────┘
               │                     │
       ┌───────▼───────┐    ┌────────▼─────────┐
       │ Repositories  │    │ Adapters         │
       │ (DB access)   │    │ (External APIs)  │
       │ Eloquent +    │    │ Format-based,    │
       │ scopes        │    │ BYOK config      │
       └───────┬───────┘    └────────┬─────────┘
               │                     │
       ┌───────▼───────┐    ┌────────▼─────────┐
       │ MySQL/Postgres│    │ External: OTA,   │
       │ via Eloquent  │    │ Payment, AI, WA, │
       └───────────────┘    │ SMS, Lock        │
                            └──────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  Event Bus (Laravel Events + Queue)                         │
│  • Async listeners → side effects                           │
│  • GL posting, OTA sync, email, audit log                   │
└─────────────────────────────────────────────────────────────┘

4. Event Flow Examples #

A. Guest checks in via FO #

[FO staff] click "Check-in" on reservation
    ↓
ReservationController@checkIn
    ↓
CheckInService::execute(ReservationId)
    ├─ Update reservation.status = 'in_house'
    ├─ Update room.status = 'occupied'
    ├─ Open folio if not exists
    ├─ Auto-post room charge (1st night)
    ├─ Generate registration card PDF
    └─ Fire event: ReservationCheckedIn
        ↓
        Listeners (async via queue):
          ├─ SendCheckInEmailListener     → mail queue
          ├─ NotifyHousekeepingListener   → realtime ws + db
          ├─ AuditLogListener              → audit_logs append
          ├─ SyncRoomToOtaListener         → ota-sync queue (block other OTAs)
          ├─ PostFolioToGlListener         → GL journal entry
          ├─ TriggerLaporWnaListener       → if guest WNA, queue lapor
          └─ AwardLoyaltyPointsListener    → if member

B. OTA booking ingest (Booking.com webhook) #

POST /webhook/ota/booking-com (HMAC verified)
    ↓
WebhookController@handleBookingCom
    ↓
ProcessOtaBookingJob::dispatch($payload) → ota-ingest queue
    ↓
[worker] OtaBookingIngestService::ingest($payload)
    ├─ Map OTA room type → internal RoomType
    ├─ Find or create Guest (email match or create new)
    ├─ Create Reservation
    ├─ Open folio + post charges
    ├─ Mark inventory taken (sync back to other OTAs)
    └─ Fire: OtaBookingIngested
        ↓
        Listeners:
          ├─ SendConfirmationEmail         (if email present)
          ├─ SyncOtherOtasListener         → push reduced ARI to all other OTAs
          ├─ AuditLog
          └─ NotifyFrontOffice             → realtime

C. AI Concierge guest message #

[Guest WhatsApp] "Boleh extend checkout sampai 2 PM?"
    ↓
WhatsAppWebhookController@receive
    ↓
ConciergeService::handleMessage($from, $text)
    ├─ Lookup guest by phone
    ├─ Build context: reservation, room, current charges
    ├─ AiClient::ask(systemPrompt, userText, context)
    │     ↓
    │   AdapterFactory::resolve(activeProvider) → e.g. OpenAICompatibleAdapter
    │     ↓
    │   POST {base_url}/chat/completions (BYOK API key)
    │     ↓
    │   Return AI text + structured action (if any)
    ├─ If action = "request_late_checkout":
    │     LateCheckoutService::request(reservation, until=14:00)
    │     ↓ Fire ReservationModified event
    └─ Send AI reply via WhatsApp

5. Adapter Pattern (BYOK rule) #

Interface #

// app/Modules/Ai/Adapters/AiAdapterInterface.php
interface AiAdapterInterface
{
    public function chat(array $messages, array $options = []): AiChatResponse;
    public function listModels(): array;
    public function tokenCount(string $text): int;
}

Format-based implementations #

// OpenAI-compatible (covers DeepSeek, Groq, Together, Fireworks,
// Mistral, DeepInfra, OpenRouter, Cerebras, OpenAI itself,
// Ollama, LM Studio, vLLM)
class OpenAICompatibleAdapter implements AiAdapterInterface { ... }

// Anthropic format
class AnthropicFormatAdapter implements AiAdapterInterface { ... }

// Gemini format
class GeminiFormatAdapter implements AiAdapterInterface { ... }

Resolution #

// app/Modules/Ai/Services/AiClient.php
public function ask(string $prompt): AiChatResponse
{
    $provider = Provider::active('ai')->first();
    $adapter = AdapterFactory::for($provider->api_format)
        ->withConfig([
            'base_url'       => $provider->base_url,
            'api_key'        => decrypt($provider->api_key_encrypted),
            'extra_headers'  => $provider->extra_headers ?? [],
            'model'          => $provider->default_model,
        ]);

    return $adapter->chat([
        ['role' => 'system', 'content' => $this->systemPrompt()],
        ['role' => 'user',   'content' => $prompt],
    ]);
}

Hard rule: TIDAK ADA class bernama OpenAIAdapter, MidtransAdapter, BookingComAdapter dengan logic vendor-specific. Class adapter purely format-based.

Untuk OTA (yang spec API-nya per-vendor sangat unik) — pengecualian terbatas: BookingComAdapter, AgodaAdapter, TravelokaAdapter boleh ada karena API mereka bukan "format keluarga". Tapi tetap implement ChannelAdapterInterface shared. (Ini decision pragmatik — payment & AI bisa format-based, OTA tidak.)

6. Mode Selection #

// config/modes.php
return [
    'mode' => env('APP_MODE', 'standalone'), // standalone | saas
    'tenancy_enabled' => env('APP_MODE') === 'saas',
    'license_required' => env('APP_MODE') === 'standalone',
];

// app/Providers/AppServiceProvider.php
public function register()
{
    if (config('modes.tenancy_enabled')) {
        $this->app->register(TenancyServiceProvider::class);
    }
    if (config('modes.license_required')) {
        $this->app->register(LicenseServiceProvider::class);
    }
}

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        // Standalone only
        \App\Modules\License\Middleware\RequirePair::class,
        // SaaS only
        \App\Modules\Tenancy\Middleware\TenantInitializer::class,
    ]);
})

Middleware self-skip jika mode tidak match.

7. Tenancy Strategy (SaaS) #

stancl/tenancy v4. DB-per-tenant, subdomain identification.

Request → app.{tenant}.hotelxyz.com
    ↓
TenantInitializer middleware
    ├─ Resolve tenant by subdomain
    ├─ Switch DB connection: tenant_<uuid>
    ├─ Switch cache prefix: tenant:<uuid>:
    ├─ Switch storage path: tenants/<uuid>/
    └─ Continue request

Central DB tetap accessible via central() helper untuk billing, plan, etc.

Detail: 18-SAAS_UPGRADE_PATH.md.

8. RBAC #

spatie/laravel-permission. Roles:

• owner — semua, tidak bisa di-revoke
• manager — semua kecuali billing & owner-level config
• front_office — reservation, guest, folio, payment
• housekeeping — room status, task
• pos_cashier — POS only + folio post
• accounting — GL, AR/AP, report, e-Faktur
• revenue_manager — rate plan, channel manager
• maintenance — work order
• hr — employee, payroll (Phase 2)
• read_only_auditor — view all, no edit

Permission granular: reservation.create, reservation.cancel, folio.transfer, gl.post, ota.sync, dll.

Detail matrix: 15-ADMIN_SECURITY.md.

9. Audit Log #

spatie/laravel-activitylog + custom append-only constraint.

Tracked actions:

• All Reservation, Folio, Charge, Payment, JournalEntry CUD
• All login/logout, 2FA, password reset
• All RBAC role/permission changes
• All admin config changes (BYOK provider add/edit/delete — tanpa expose key)
• All license activate/heartbeat/revoke

Append-only enforcement: trigger DB-level + Eloquent observer prevent UPDATE/DELETE pada audit_logs.

10. Idempotency #

Semua POST yang mutate state (booking create, payment, OTA push, etc.) accept Idempotency-Key header. Service cek di Redis (TTL 24h) — kalau sudah ada response cached, return tanpa eksekusi ulang.

$key = $request->header('Idempotency-Key');
if ($cached = Cache::get("idem:{$key}")) {
    return $cached;
}
$response = $this->service->execute(...);
Cache::put("idem:{$key}", $response, 86400);
return $response;

11. Event Catalog (key events) #

12. Naming Conventions #

13. Coding Standards #

• PSR-12 + Laravel Pint default
• PHPStan level 6 minimum (level 8 target untuk new code)
• Strict types declared: declare(strict_types=1);
• Eloquent OK untuk queries simple; DB query builder untuk reporting (faster, less hydration)
• DTOs untuk data transfer cross-layer (spatie/laravel-data ringan)
• No mixed kecuali strict-typed downstream
• No facades di service layer — inject via constructor

14. Testing Strategy #

• Unit tests — service methods, adapter contract conformance
• Feature tests — HTTP request → response flow
• Integration tests — OTA mock servers (Booking.com sandbox), payment sandbox
• Browser tests (Pest+Dusk) — wizard pairing, booking engine flow
• Architecture tests (Pest arch) — enforce adapter naming, no facades in services
• Mutation tests (Infection) — high-value modules: pricing, accounting, tax

Coverage target: 80% line coverage modul accounting + tax + pricing (highest risk). 50% baseline lain.

Detail: 21-QA_CHECKLIST.md.

15. Technical Debt Policy #

• TODO → harus include issue link + due date
• "Temporary" workaround → tracked sebagai task di 22-PROGRESS.md
• Deprecation: minimum 1 minor version warning sebelum removal
• No silent fallback yang masking bug — semua fallback log + telemetry