Copy page

Pendahuluan

Overview Developer

Overview Developer

OmniStream adalah platform CRM omnichannel event-driven yang dibangun sebagai monorepo Rust + SvelteKit. Seluruh backend, frontend, migrasi database, dan infrastruktur development hidup pada satu repository — satu PR dapat menyentuh kode aplikasi, migrasi, dan dokumentasi sekaligus.

Halaman ini menjelaskan tata letak repo, bahasa, dan alat yang dipakai supaya developer baru bisa bernavigasi tanpa tersesat.

Bahasa dan stack

• Rust untuk seluruh backend — axum (HTTP), tokio (async), sqlx (PostgreSQL), mongodb, rdkafka (Redpanda), redis. Dependensi menggunakan rustls-tls (bukan native-tls) untuk semua HTTP client (reqwest, S3, lettre).
• SvelteKit (Svelte 5) untuk frontend, memakai Svelte 5 runes ($state, $derived, $effect, $props) bukan store v4. File state diberi ekstensi .svelte.ts. Styling menggunakan Tailwind CSS v4 dengan plugin @tailwindcss/vite.
• PostgreSQL untuk data relasional, MongoDB untuk koleksi pesan volume tinggi, Redis untuk pub/sub real-time, Redpanda (API-compatible Kafka) untuk antrian event.

Tata letak monorepo

Code
omnistream/
├── crates/                 # Workspace Rust — 6 crate
│   ├── omni-common/        # Library bersama: model DB, pool, Kafka/Redis client, config
│   ├── webhook-ingestor/   # HTTP server penerima webhook (WhatsApp, Instagram, Messenger, Email)
│   ├── chat-engine/        # Konsumer Kafka yang memproses pesan masuk
│   ├── api-gateway/        # HTTP server REST + JWT auth + RBAC + scheduler
│   ├── message-sender/     # Konsumer Kafka yang mengirim pesan keluar ke Meta/SMTP
│   └── ws-server/          # WebSocket server untuk event real-time
│
├── frontend/               # SvelteKit app (Svelte 5 runes, Tailwind v4)
│   └── src/
│       ├── routes/(app)/   # 15 rute in-scope Panduan Pengguna
│       ├── lib/api/        # Client REST (client.ts)
│       ├── lib/stores/     # State runes (.svelte.ts)
│       └── lib/types/      # Tipe TypeScript bersama
│
├── migrations/             # 41 file migrasi SQLx, auto-run saat start (omni_common::sqlx::migrate!)
│
├── docs/                   # Sumber kebenaran dokumentasi
│   ├── openapi.yaml        # 3372 baris, 21 tag, 90+ endpoint
│   ├── deployment.md
│   └── production-deploy.md
│
├── docs-site/              # Situs Zudoku (berkas Anda baca sekarang)
│
├── scripts/                # Skrip utilitas: seed_agents.sql, e2e_test.py, seed_docs_demo.sql
│
├── docker-compose.yml      # Infrastruktur full-stack
└── docker-compose.dev.yml  # Varian development

Crate dan binary

crates/ adalah satu Cargo workspace. Setiap crate memuat satu atau beberapa binary:

Crate	Binary yang dihasilkan	Peran
omni-common	(library)	Dibagi-pakai oleh semua crate lain
webhook-ingestor	webhook-ingestor	Satu binary dengan empat route /webhook/{whatsapp,messenger,instagram,email} + /health. Memverifikasi HMAC, memproduksi ke Kafka channel.inbound.raw.
chat-engine	chat-engine	Satu binary yang berlangganan channel.inbound.raw dan men-dispatch ke parser per saluran (parser/{whatsapp,messenger,instagram,email}.rs) berdasarkan field channel dalam InboundRawEvent. Upsert PG+Mongo, publikasi Redis.
api-gateway	api-gateway	REST API + RBAC + scheduler + webhook dispatcher
message-sender	message-sender	Satu binary yang berlangganan channel.outbound.job dan men-dispatch ke modul {whatsapp,messenger,instagram,email}.rs. Memanggil Meta Graph API / SMTP.
ws-server	ws-server	WebSocket server untuk event real-time

:::info Single-binary topologi (drift CLAUDE.md D3) CLAUDE.md masih mencantumkan binary per-saluran (misal webhook-ingestor-whatsapp, chat-engine-instagram). Nama tersebut historis — runtime aktual memakai satu binary per crate seperti di tabel di atas. Pemisahan sekarang bersifat logis (route / parser / modul), bukan proses. :::

Konvensi utama

• SQL sebagai string runtime — semua query memakai sqlx::query_as! sebagai string runtime, bukan mode offline. Konsekuensinya Anda tidak perlu sqlx-data.json atau database berjalan untuk kompilasi.
• DATABASE_URL dan MONGODB_URI wajib — tidak ada default fallback; proses gagal start bila variabel kosong.
• Hot-reload integrasi 30 detik — message-sender dan webhook-ingestor memolling tabel integrations setiap 30 detik dan memperbarui memori lewat omni_common::ConfigPoller.
• Migrasi otomatis — omni-common menjalankan sqlx::migrate! pada startup. 41 file migrasi hidup di migrations/ (verifikasi: find migrations -name "*.sql" | wc -l).
• Tanda tangan HMAC webhook keluar — dihitung dengan hmac-sha256 hex dan dikirim sebagai X-Omnistream-Signature.
• Test sequential — cargo test --workspace bisa OOM pada Windows/Docker Desktop karena rdkafka-sys. Pakai cargo test -p <crate> atau docker build -f Dockerfile.test.

Port layanan (mode development)

Layanan	Port	Catatan
API Gateway	3000	REST API utama
Webhook Ingestor	WEBHOOK_INGESTOR_PORT (3001 di compose dev)	Satu binary, empat route /webhook/{whatsapp,messenger,instagram,email} + /health
WS Server	3002	/ws?token=<JWT>
Frontend (SvelteKit)	4000	npm run dev
Mailpit SMTP	1025	Relay email development
Mailpit Web UI	8025	Inspeksi email di browser

chat-engine dan message-sender adalah konsumer Kafka tanpa port HTTP — masing-masing satu binary, men-dispatch per saluran di dalam proses.

Detail lebih lengkap ada di Arsitektur Layanan.

Cara menavigasi kode

• REST route handlers — crates/api-gateway/src/routes/ (20 modul: auth, agents, analytics, contacts, conversations, messages, dll.)
• Model bersama (semua tipe DB) — crates/omni-common/src/models/ (18 modul per docs-site/SCOPE.md Bagian 3; CLAUDE.md saat ini masih drift mencatat "17 model modules")
• Event schema Kafka/Redis — crates/omni-common/src/models/events.rs
• Parser pesan (WhatsApp/Instagram/Email) — crates/chat-engine/src/parser/mod.rs
• Middleware autentikasi — crates/api-gateway/src/middleware/auth.rs
• Scheduler background (campaigns, SLA, webhook delivery) — crates/api-gateway/src/scheduler.rs
• Webhook dispatcher (Redis → HTTP) — crates/api-gateway/src/webhook_dispatcher.rs
• Client API frontend — frontend/src/lib/api/client.ts
• Store state frontend — frontend/src/lib/stores/*.svelte.ts
• Spec OpenAPI — docs/openapi.yaml (dirender di API Reference)

Selanjutnya, lanjut ke Arsitektur Layanan untuk memahami topologi, lalu ke Quickstart untuk menjalankan stack secara lokal.