S&DP Architecture Explorer

Keputusan Arsitektur

Primary Database

Source of truth untuk write, versioning, relationship, idempotency, policy, dan ledger.

Strong consistency

JSON Document

Profil, role, capability, requirement, dan konfigurasi sparse yang dapat berkembang tanpa DDL rutin.

Flexible schema

Manticore Search

Projection terdenormalisasi untuk pencarian, filter, CMS, dan dashboard. Disposable dan dapat di-reindex.

Eventually consistent

External Services

Masterdata, AWB, dan Billing tetap menjadi pemilik data masing-masing. S&DP menyimpan external ID.

No authoritative duplication

OOP ke Data Model

Encapsulation

Ownership per service dan akses melalui API/event.

Inheritance

Role taxonomy dan default capability, bukan table-per-subclass.

Polymorphism

Behavior dipilih berdasarkan capability, workflow, dan policy.

Composition

Satu party dapat menerima banyak role dan capability tanpa menggandakan identity.

Hybrid Persistence ERD

erDiagram ENTITY_DOCUMENT { uuid entity_id PK string entity_type string external_party_id int schema_version json document bigint version string status } ENTITY_RELATIONSHIP { uuid relationship_id PK uuid source_entity_id FK uuid target_entity_id FK string relationship_type json metadata } ACTIVITY_EVENT { uuid activity_id PK uuid actor_entity_id FK string activity_type string external_transaction_id string idempotency_key UK json facts } POLICY_DOCUMENT { uuid policy_id PK string policy_code int policy_version json definition string status } LEDGER_ENTRY { uuid ledger_entry_id PK uuid activity_id FK uuid policy_id FK decimal amount string currency string entry_type string status } OUTBOX_EVENT { uuid event_id PK string aggregate_type uuid aggregate_id bigint aggregate_version string event_type json payload } ENTITY_DOCUMENT ||--o{ ENTITY_RELATIONSHIP : source ENTITY_DOCUMENT ||--o{ ENTITY_RELATIONSHIP : target ENTITY_DOCUMENT ||--o{ ACTIVITY_EVENT : performs ACTIVITY_EVENT ||--o{ LEDGER_ENTRY : produces POLICY_DOCUMENT ||--o{ LEDGER_ENTRY : calculates ENTITY_DOCUMENT ||--o{ OUTBOX_EVENT : publishes

JSON tidak dipakai untuk menggantikan constraint. Uang, relationship penting, idempotency, validity period, dan lifecycle transaksi tetap typed.

Write → Projection → Read

1. Client
create/update agent

→

2. S&DP API
validate external IDs

→

3. Primary DB
document + relation + outbox dalam satu transaksi

→

4. Outbox Relay
enrich dan upsert versi terbaru

→

5. Manticore
search/list projection

Aturan Read

Search & CMS

Baca Manticore

Text search, faceting, filter, pagination, dan dashboard.

Detail Authoritative

Baca primary/service owner

Candidate ID dari Manticore dapat di-hydrate bila perlu.

Approval & Eligibility

Jangan percaya index

Evaluasi primary DB dan policy engine.

Commission & Settlement

Jangan percaya index

Gunakan activity, policy version, dan ledger typed.

Data Ownership

Data	Source of Truth	Yang disimpan S&DP
Customer/account, PIC, kontak	Masterdata	`customer_account_id`
Alamat & wilayah	Masterdata	`address_id`
File dokumen	Attachment/Masterdata	ID + status verifikasi S&DP
Agent role & hierarchy	S&DP	JSON document + typed relationship
AWB, sender, recipient, status	AWB Service	ID transaksi + immutable facts untuk kalkulasi
Policy komisi	S&DP	Versioned policy JSON
Accrual/reversal komisi	S&DP	Typed immutable ledger
Invoice/payment/settlement	Billing	`billing_external_id`
Search projection	Derived	Manticore; rebuildable

Uji Perubahan Bisnis

Tambah MOBILE_AGENT

Tambah role, capability, document requirement, workflow, dan policy sebagai data.

Zero DDL

Komisi tier baru

Buat policy version baru dengan validity period. Ledger lama tetap menunjuk versi lama.

Zero DDL

Atribut profil baru

Tambah field JSON, naikkan schema version, validasi dengan JSON Schema, lalu update projection.

Zero DDL primary*

Multi-currency ledger

Jika belum tersedia sebagai invariant typed, lakukan migration dan update accounting rules.

DDL layak

Relationship bisnis baru

Tambah relationship type dan metadata selama constraint existing cukup.

Zero DDL

Double-entry accounting

Konsep fundamental baru; jangan dipaksakan ke JSON.

DDL wajib

* Perubahan searchable attribute mungkin tetap memerlukan perubahan konfigurasi/index Manticore. Zero-DDL database tidak berarti zero-governance.

User Journeys

Alur tulis selalu selesai di PostgreSQL terlebih dahulu. Manticore diproyeksikan asinkron dan tidak dipakai untuk keputusan approval atau uang.

sequenceDiagram actor Applicant participant API as "S&DP API" participant MD as Masterdata participant DB as PostgreSQL participant Relay as Outbox Relay participant MS as Manticore Applicant->>API: Self-register with MP-001 API->>MD: Validate external IDs MD-->>API: Valid API->>DB: Entity, referral, outbox in one transaction DB-->>API: PENDING version 1 API-->>Applicant: Accepted Relay->>DB: Claim unpublished event Relay->>MS: Upsert newer sourceVersion Relay->>DB: Receipt and publish acknowledgement

Registration

Self-service stores a typed REFERRED_BY edge. CMS registration stores only the external operator ID.

Touches: entity_document, entity_relationship, outbox_event

Verification

Document status lives in bounded JSON; approval audit is an idempotent typed activity.

Touches: entity_document, activity_event, outbox_event

AWB & Commission

Create, receive, and handover use unique keys. Commission pins the activity and policy version.

Touches: activity_event, policy_document, ledger_entry

Settlement & Projection

Billing callback ID is unique. Projection receipts make consumer processing auditable.

Touches: ledger_entry, outbox_event, projection_receipt

See USER-JOURNEYS.md for six complete sequence diagrams and exact columns touched.

SQL Examples

Pilih skenario

Snippets are abbreviated for reading. The transactionally complete, rerunnable examples are in scenario-queries.sql; DDL and helper functions are in schemas.sql.

Production Guardrails

Transactional Outbox

Hindari dual-write DB + Manticore pada request yang sama.

Version Ordering

Projection membawa sourceVersion; event lama tidak boleh menimpa event baru.

Idempotency

Deduplicate berdasarkan event ID atau aggregate ID + version.

Schema Contract

JSON memakai schema_version, JSON Schema, validation, dan migration strategy.

Replay & Reindex

Manticore harus dapat dibangun ulang sepenuhnya dari primary DB.

Safe Policy DSL

Gunakan decision table/DSL terbatas, bukan arbitrary SQL atau JavaScript.