Aori — Gambaran Menyeluruh Proyek

Navigasi dokumen: 02.roadmap adalah urutan implementasi dan status aktual; 04.study menguji blueprint ini melalui kasus bisnis; AGENTS.md pada root repository menerapkan ketiganya sebagai aturan kerja.

Dokumen ini merangkum struktur, tujuan, arsitektur, domain bisnis, alur aplikasi, dan arah pengembangan Aori berdasarkan struktur monorepo, dokumentasi internal, manifest workspace, skema Prisma, serta implementasi aplikasi yang tersedia.

1. Apa Itu Aori dan Tujuannya

Apa itu Aori?

Aori adalah platform digital terpadu untuk mengelola operasi bisnis end-to-end. Aori menggabungkan fondasi organisasi dan identitas, katalog barang atau jasa, transaksi commerce, pembayaran, pengiriman, gudang, serta inventori dalam satu ekosistem multi-tenant, ringkasnya: Aori adalah aplikasi SAAS Multi-Tenant Modern.

Aori bukan hanya aplikasi toko atau kumpulan fitur CRUD. Aori dirancang sebagai operating system bisnis yang membantu berbagai jenis organisasi menjalankan proses hariannya secara konsisten, terukur, aman, dan dapat berkembang dari satu unit usaha menjadi organisasi multi-cabang.

Aori dirancang bukan hanya untuk organization owner, tapi juga untuk anggota-anggotanya. Konektivitas, keamanan, ringan, serta personalisasi menjadi fitur utama yang ditawarkan.

Tujuan Aori

Tujuan utama Aori adalah menyederhanakan dan menyatukan operasi bisnis yang biasanya tersebar di banyak sistem. Dengan satu fondasi data dan akses, bisnis dapat mengelola orang, proses, barang atau jasa, transaksi, serta sumber daya fisik secara terhubung sehingga keputusan operasional menjadi lebih cepat dan akurat.

2. Visi Aori

Menjadi platform operating system bisnis yang menyatukan seluruh siklus operasi organisasi secara terpadu, aman, terukur, dan siap berkembang.

Visi ini berarti Aori ingin membantu bisnis membangun fondasi operasional yang kuat: setiap domain memiliki tanggung jawab yang jelas, setiap transaksi dapat ditelusuri, setiap akses dapat dikendalikan, dan setiap bagian sistem dapat berkembang tanpa kehilangan konsistensi.

3. Misi Aori

Misi Aori adalah:

1. Menyediakan satu sumber kebenaran untuk operasi bisnis melalui batas kepemilikan data yang jelas pada setiap domain.
2. Menyederhanakan pengelolaan organisasi multi-cabang dan multi-tim melalui identity, workspace, member, employee, role, dan permission.
3. Menjaga keamanan dan kontrol akses dengan autentikasi, session, RBAC, validasi, rate limiting, serta perlindungan infrastruktur.
4. Menjaga akurasi transaksi dan histori operasional melalui snapshot historis, immutable ledger, dan pencatatan perubahan yang dapat ditelusuri.
5. Menyediakan platform yang modular dan dapat dikembangkan agar aplikasi, micro-frontend, dan internal package dapat berbagi fondasi yang konsisten.
6. Mendukung beragam model bisnis seperti retail, F&B, jasa, workshop, distribusi, pendidikan, manufaktur, kesehatan, dan bidang lainnya.

Ringkasan Eksekutif

Aori adalah platform operasional dan commerce multi-tenant untuk bisnis yang ingin mengelola organisasi, pengguna, anggota tim, karyawan, katalog, penjualan, pembayaran, pengiriman, gudang, dan inventori dalam satu ekosistem.

Secara teknis, Aori dibangun sebagai monorepo Bun/Turborepo yang memisahkan beberapa aplikasi dan paket bersama. Pusat data dan otorisasi diarahkan ke apps/api, sedangkan apps/app/container merupakan aplikasi web utama untuk pengguna operasional. Domain bisnis dipisahkan ke lima database MongoDB:

1. Billing — plan, subscription, entitlement, usage metering, serta invoice Aori kepada tenant.
2. Identity/Runner — user, autentikasi, organisasi, workspace, member, team, collaboration, role, permission, employee, HR, payroll, dan data organisasi.
3. Catalog — brand, kategori, produk, varian, layanan, harga, media, SEO, dan promosi.
4. Commerce — customer, cart, order, invoice, payment, refund, dan shipment.
5. Inventory — warehouse, bin, stock, lot, serial, movement, reservation, transfer, dan stocktake.

Pemisahan ini menunjukkan bahwa Aori tidak sekadar aplikasi CRUD toko. Visi arsitekturnya adalah menjadi operating system bisnis: identitas dan akses sebagai fondasi, catalog sebagai sumber barang/jasa, commerce sebagai batas transaksi, dan inventory sebagai sumber kebenaran operasional stok.

Arah Produk dan Arsitektur

Visi produk tersebut diwujudkan dengan menyatukan hal-hal yang biasanya tersebar di banyak aplikasi:

• identitas pengguna dan login;
• struktur organisasi dan cabang;
• kontrol akses berbasis peran;
• data karyawan dan struktur jabatan;
• payroll dan absensi;
• katalog barang dan jasa;
• promosi serta harga;
• customer dan pesanan;
• pembayaran, invoice, refund, dan pengiriman;
• gudang dan inventori;
• pelaporan serta integrasi lintas domain.

Visi ini juga tampak dari perhatian terhadap histori. Perubahan jabatan, role, alamat, harga, produk, pajak, diskon, dan item transaksi dirancang agar tidak merusak kebenaran historis.

Prinsip Misi dalam Implementasi

Misi operasional Aori tercermin dalam implementasi berikut:

1. Menyediakan satu sumber kebenaran untuk operasi bisnis. Data inti setiap domain memiliki batas kepemilikan yang jelas.
2. Membuat bisnis multi-cabang dan multi-tim mudah dikelola. Organization, workspace, member, employee, position, dan permission mendukung struktur yang berkembang.
3. Menjaga keamanan akses dan data. Autentikasi, session, MFA/passkey, trusted origin, proxy identity, RBAC, CORS, rate limiting, security headers, dan validasi request disiapkan sebagai fondasi.
4. Menjaga akurasi transaksi dan histori. Commerce menggunakan snapshot historis; inventori menggunakan fixed-point integer serta immutable movement ledger.
5. Menyediakan platform yang dapat dikembangkan. Aplikasi dipisahkan dari paket komponen, helper, hook, icon, HTTP client, database types, dan konfigurasi bersama.
6. Mendukung berbagai tipe bisnis. Model catalog dan service tidak dibatasi pada satu industri: retail, F&B, jasa, workshop, distribusi, pendidikan, manufaktur, kesehatan, dan lainnya dapat direpresentasikan.

4. Struktur Monorepo

Aori menggunakan struktur workspace berikut:

apps/
├── api/                    Express API dan pusat layanan backend
├── app/container/          Aplikasi web utama operasional
├── commerce/               Aplikasi commerce/storefront terpisah
├── docs/                   Dokumentasi internal berbasis Next.js/MDX
└── landing/                Aplikasi landing/public marketing
 
contracts/
└── i18n/                   Kontrak dan pesan internasionalisasi
 
### Peran `contracts/` untuk Micro-frontend
 
`contracts/` adalah internal package yang ditujukan untuk aplikasi utama di bawah `apps/app/*`. Direktori `apps/app/*` merupakan ekosistem aplikasi micro-frontend, dengan `apps/app/container` sebagai root atau host utamanya.
 
Setiap internal package yang perlu digunakan bersama oleh beberapa micro-frontend, terutama ketika membutuhkan konfigurasi dan perilaku yang sama, terlebih dahulu direfactor dan ditempatkan di dalam `contracts/`. Dengan cara ini, kontrak, tipe, konfigurasi, dan kebutuhan lintas micro-frontend memiliki satu sumber yang konsisten.
 
Package yang pada awalnya hanya digunakan di dalam cakupan `apps/app/container` juga dapat dinaikkan statusnya menjadi internal package di `contracts/` apabila micro-frontend lain membutuhkan kemampuan yang sama. Setelah dinaikkan, package tersebut dapat digunakan bersama oleh seluruh aplikasi micro-frontend tanpa duplikasi implementasi.
 
packages/
├── auth/                   Auth client/server dan integrasi Better Auth
├── components/             Komponen aplikasi bersama
├── configs/                Konfigurasi CSS, ESLint, metadata, dan TypeScript
├── core/                   Tipe dan fondasi inti
├── dataset/                Dataset region serta utilitas refinement
├── db/                     Tipe dan akses database yang dihasilkan
├── engines/mini-search/    Mesin pencarian ringan
├── helpers/                Helper umum
├── hookform/               Integrasi form
├── hooks/                  React hooks bersama
├── http/                   HTTP client, Cloudinary, dan utilitas HTTP
├── i18n/                   Utilitas internasionalisasi
├── icons/                  Icon fill, outline, tone, brand, loader, preset, dll.
├── permissions/            Permission definitions dan hooks
├── ui/                     Komponen UI terisolasi seperti dialog, form, table,
│                           sidebar, sheet, carousel, chart, dan theme
└── utils/                  Utilitas umum
 
tools/
├── cli/                    CLI internal
└── scripts/                Script generator dan tooling repository
 
`tools/*` berisi alat bantu development lokal dan sesekali digunakan untuk mendukung proses build. Isinya bukan domain bisnis utama aplikasi, melainkan CLI internal, generator, dan script repository yang membantu pengembang menjalankan, menghasilkan, memvalidasi, atau membangun bagian-bagian proyek.
 
infrastructure/             Dokumentasi/konfigurasi infrastruktur
data/                       Asset atau data repository
public/                     Asset publik

Repository ini memiliki sekitar 1.262 file terlacak, dengan sumber utama TypeScript/TSX, Prisma, Markdown/MDX, JSON, CSS, JavaScript, dan asset gambar/icon.

5. Aplikasi yang Tersedia

5.1 apps/api

apps/api adalah Express API mandiri. Aplikasi ini memegang tanggung jawab backend lintas domain:

• route dan controller domain bisnis;
• validasi request;
• autentikasi dan session melalui Better Auth;
• komposisi data dari beberapa database;
• invitation dan permission organisasi;
• operasi password dan penghapusan akun;
• health check dan metadata service;
• error response terstruktur;
• middleware keamanan.

Route dasar yang terdokumentasi:

• GET / — status API;
• GET /api — indeks API;
• GET /api/v1/health — health check;
• GET /api/v1/meta — metadata service;
• GET /healthz — alias health check deployment;
• POST /api/users/me/password — tambah/ubah password;
• DELETE /api/users/:userId — penghapusan akun dengan pemeriksaan keamanan;
• route organization invitation dan permission.

API menggunakan format error konsisten:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Pesan aman untuk client",
    "requestId": "id-request"
  }
}

5.2 apps/app/container

Ini adalah aplikasi web utama Aori. Teknologi utamanya Next.js, React, SWR, Zustand, Motion, dnd-kit, dan paket internal monorepo.

Layout locale memuat:

• session server;
• pesan locale;
• AppProvider;
• IntlProviderApp;
• AuthSessionProvider;
• navigasi sidebar;
• network presence;
• toaster.

Halaman utama mengambil data user dan organisasi melalui proxy API, menampilkan skeleton ketika loading, lalu meneruskan data ke dashboard. Aplikasi menggunakan locale route dan kontrak i18n terpusat.

5.3 apps/commerce

Aplikasi commerce dipisahkan sebagai permukaan khusus commerce. Keberadaannya menunjukkan bahwa pengalaman jual-beli atau transaksi dapat dikembangkan tanpa mencampur seluruh concern operasional internal ke aplikasi utama.

5.4 apps/landing

Landing page publik untuk memperkenalkan Aori, menjelaskan nilai produk, dan menjadi pintu masuk marketing/public web.

5.5 apps/docs

Aplikasi dokumentasi internal Aori. Isinya membahas playbook integrasi API, Better Auth, komposisi lintas database, React Native/Expo, security checklist, dan CI.

Sistem dokumentasinya memetakan file Markdown/MDX menjadi route catch-all. Nama file bernomor dipakai untuk pengurutan, lalu dinormalisasi menjadi segment dan slug. Utilitas route juga mendeteksi konflik seperti file guides.mdx bersamaan dengan guides/index.mdx.

6. Model Identitas dan Organisasi

Fondasi model organisasi Aori memisahkan tiga konsep penting:

User
├── identity/authentication
 
Member
├── organization access/RBAC
 
WorkspaceParticipant
├── assignment ke agenda Workspace
 
Employee
└── employment/HR/payroll/attendance

User

User adalah identitas akun, bukan otomatis seorang karyawan. User menyimpan username, nama, email, status, platform role, session, account provider, profile, personalization, address, link, passkey, dan two-factor data.

Readiness projection

Readiness bukan satu persentase global. API membangun projection terpisah untuk UserProfile, Organization, dan MemberWork agar identity personal tidak dipaksa bergantung pada tenant, dan kesiapan kerja tidak mencampur lifecycle Employee atau Workspace. UserProfile hanya menghitung item profil yang benar-benar dapat dilengkapi oleh User; status keamanan seperti verifikasi email dilaporkan terpisah. Organization hanya dapat memuat checklist yang relevan untuk actor, permission, entitlement, dan category; MemberWork selalu dibatasi pada membership Organization asal. Progress UI tidak pernah menjadi authorization atau entitlement.

Organization

Organization adalah tenant root dan sumber tenant-scoping. Organization memiliki owner, members, teams, workspaces, projects, collaboration, employees, addresses, links, FAQ, positions, permission roles, dan work shifts. Organization juga dapat membentuk hierarchy parent-child untuk kebutuhan grup atau cabang.

Workspace

Workspace adalah ruang kerja operasional untuk agenda di dalam satu organization. Ia tidak pernah menjadi tenant dan tidak dapat ada tanpa organization owner. Participant eksternal tidak menjadi member organization owner: mereka tetap berasal dari organization asal dan mendapat scope terbatas melalui collaboration yang aktif.

Member, Team, dan WorkspaceParticipant

Member menentukan siapa yang boleh mengakses organization. Member memiliki status, role/permission, invitation context, dan akses yang tidak sama dengan status employment. Team adalah kelompok internal yang tenant-scoped (Team.organizationId wajib); TeamMember.memberId wajib dan employee adalah konteks opsional. WorkspaceParticipant menyimpan assignment terpisah ke agenda workspace agar member dapat ikut nol, satu, atau banyak workspace.

Project menyimpan deliverable, timeline, dan budget. Collaboration menyimpan pihak, approval, scope, dan dasar legal kerja bersama. Keduanya bukan sinonim Workspace: satu collaboration dapat mengatur beberapa workspace milik organization owner.

Employee

Employee merepresentasikan hubungan kerja. Employee dapat memiliki employee code, posisi, tipe employment, status employment, kontrak, salary, payroll, attendance, shift, BPJS, dan pajak.

Pemisahan ini penting: seseorang dapat menjadi member tanpa menjadi employee, misalnya auditor, owner, consultant, atau partner.

7. RBAC, Permission, dan Invitation

Aori membedakan position dan permission role:

• Position menggambarkan jabatan dalam struktur organisasi: CEO, Branch Manager, Supervisor, Cashier, Barista.
• Permission role menggambarkan kemampuan sistem: OWNER, HR_MANAGER, CASHIER, WAREHOUSE_ADMIN.

Satu orang dapat memiliki jabatan tertentu tetapi permission yang lebih terbatas atau berbeda. Pemisahan ini membuat struktur HR tidak mengunci desain keamanan aplikasi.

Permission module yang disiapkan mencakup:

• attendance;
• employee;
• finance;
• inventory;
• member;
• order;
• organization;
• payroll;
• product;
• report;
• settings;
• shift.

Permission yang terdokumentasi dan telah diberlakukan antara lain:

• product.read;
• product.create;
• product.update;
• product.delete;
• organization.faq.create;
• organization.faq.update;
• organization.faq.delete.

Invitation menggunakan token acak yang dikirim melalui email, sedangkan database menyimpan hash SHA-256 token. Invitation dapat dipreview, diterima secara atomik, dibatasi masa berlaku, dan dicabut oleh owner.

8. Domain Database

8.1 Billing/Subscription

Database billing adalah sumber kebenaran subscription dan entitlement. Authorization tetap dimiliki Runner/domain pemilik resource. Di dalamnya terdapat:

• BillingAccount sebagai identitas penagihan tenant; organizationId adalah referensi scalar tervalidasi ke Runner, bukan foreign key lintas database;
• Plan berversi, Subscription, dan snapshot komersial agar perubahan plan tidak mengubah tagihan historis;
• Entitlement sebagai proyeksi capability dan quota efektif;
• UsageRecord yang immutable dan idempoten untuk metering dari domain pemilik resource;
• BillingInvoice dan BillingPayment untuk tagihan Aori kepada organization, berbeda dari invoice customer di Commerce.

Setiap aksi berfitur memeriksa dua boundary: entitlement menentukan apakah tenant berhak atau masih di bawah quota, lalu permission menentukan apakah actor boleh melakukannya. Domain pemilik resource menghitung usage secara atomik; Billing tidak menjadi bottleneck write untuk domain operasional.

Schema memakai MongoDB Prisma dan DATABASE_BILLING_URL.

8.2 Runner/Identity

Database runner adalah sumber kebenaran tenancy dan access control. Di dalamnya terdapat:

• Better Auth: Account, Session, Verification, PasswordReset, JWKS, Passkey, TwoFactor;
• User dan UserProfile;
• UserPersonalization dengan theme, locale, timezone, notification, privacy, content, dan accessibility preferences;
• Organization dan hierarchy;
• Workspace dan Member;
• Invitation;
• PermissionRole dan permission;
• Employee, Position, contract, attendance, shift, payroll;
• Address, Link, FAQ, serta data organisasi lainnya.

Schema memakai MongoDB Prisma dan DATABASE_RUNNER_URL.

8.3 Catalog

Catalog adalah pemilik identitas barang dan jasa yang dapat dijual. Prinsipnya:

• Product adalah generic sellable item;
• Product tidak memiliki pricing, inventory, order, atau customer;
• pricing dipisahkan;
• service definition dibedakan dari operational service record;
• promotion dipisah menjadi rule, condition, target, benefit, dan usage;
• historical/transactional records menyimpan snapshot;
• archive state dipisahkan dari lifecycle bisnis.

Catalog mendukung product physical, digital, service, bundle, subscription, dan tipe lain. Ia juga mendukung brand, kategori bertingkat, translation, media, SEO, identifier, physical attributes, variant, service, price list, dan promotion.

Schema memakai MongoDB Prisma dan DATABASE_CATALOG_URL.

8.4 Commerce

Commerce adalah batas transaksi. Ia memiliki:

• Customer;
• Cart dan CartItem;
• Order dan OrderItem;
• Invoice;
• Payment dan allocation;
• Refund;
• Shipment.

Order adalah aggregate transaksi pusat. Commerce menyimpan snapshot product, service, alamat, diskon, dan pajak agar transaksi lama tetap akurat walaupun catalog berubah.

Nilai uang menggunakan BigInt, bukan Float, karena ketepatan finansial adalah kebutuhan inti. Currency default yang tampak pada schema adalah IDR, tetapi model tetap menyediakan currency field.

Schema memakai MongoDB Prisma dan DATABASE_COMMERCE_URL.

8.5 Inventory

Inventory adalah domain stok operasional. Ia membedakan:

• InventoryItem sebagai representasi operasional product/variant catalog;
• Warehouse dan WarehouseBin;
• WarehouseAssignment;
• WarehouseStock;
• InventoryLot dan InventorySerial;
• InventoryMovement dan InventoryOperation;
• InventoryReservation;
• InventoryTransfer;
• InventoryStocktake.

Stok tersedia tidak disimpan sebagai angka terpisah, melainkan diturunkan dari:

available = onHandQuantity - reservedQuantity

Quantity menggunakan fixed-point integer dengan quantityScale, sedangkan biaya menggunakan BigInt. Stock movement adalah event ledger yang immutable. Master record diarsipkan, dan event historis tidak dihapus.

Schema memakai MongoDB Prisma dan DATABASE_INVENTORY_URL.

9. Pola Integrasi Lintas Domain

Lima database tidak memakai foreign key lintas database. Referensi lintas domain disimpan sebagai scalar ID:

Runner Organization
       │ organizationId
       ├── Catalog Product / Category / Price
       ├── Commerce Customer / Order / Payment
       └── Inventory Warehouse / Stock / Movement

Konsekuensinya:

• setiap query domain wajib tenant-scoped melalui organizationId;
• API menjadi tempat komposisi data lintas database;
• penghapusan lintas domain bukan distributed transaction;
• setiap domain membutuhkan strategi konsistensi dan retry yang jelas;
• snapshot dipakai saat histori harus tetap stabil.

10. Security dan Reliability

Aori telah menyiapkan beberapa lapisan keamanan:

• Better Auth sebagai authority autentikasi;
• session cookie bersama dan trusted origins;
• OAuth provider yang aktif hanya ketika credential tersedia;
• implicit account linking dinonaktifkan;
• passkey dan two-factor model;
• proxy secret antara web app dan API;
• production mutation tidak menerima userId mentah;
• CORS allowlist tanpa wildcard di production;
• CSP, HSTS production, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, dan Permissions-Policy;
• rate limit per IP + path;
• validasi Content-Type JSON;
• request ID untuk tracing;
• error handler yang tidak membocorkan stack trace;
• validasi password kuat dan re-authentication untuk operasi sensitif;
• hash invitation token di database;
• permission check per organisasi;
• pemisahan purge scope berdasarkan domain.

Penghapusan akun dirancang sebagai operasi berisiko tinggi. Self-delete dan manager delete memiliki persyaratan password, email, dan confirmation phrase. Developer dapat memilih purge scope, tetapi karena database terpisah tidak memiliki distributed transaction, API dapat mengembalikan status incomplete apabila sebagian domain telah selesai dan domain lain gagal.

11. Standar Kontribusi: Keamanan, Performa, dan Validasi

Setiap pendekatan yang diambil oleh contributor dan setiap kode yang ditulis untuk Aori harus merupakan pilihan terbaik yang dapat dipertanggungjawabkan, dengan mempertimbangkan setidaknya aspek keamanan dan performa aplikasi sebagai standar minimum. Pertimbangan ini berlaku sejak perancangan arsitektur, pemilihan dependensi, desain API, pengelolaan data, hingga implementasi antarmuka pengguna.

Setiap input wajib divalidasi sebelum diproses. Pada aplikasi utama apps/app/*, validasi dapat menggunakan Zod versi 4 terbaru dan schema harus ditempatkan di direktori @/schema/* agar kontrak validasi mudah ditemukan, digunakan kembali, dan dipelihara. Pada aplikasi API, validasi tetap WAJIB dilakukan, tetapi implementasinya harus dibuat secara mandiri tanpa menggunakan package eksternal apa pun. Validasi API harus mencakup bentuk, tipe, batasan, dan keamanan data yang diterima sebelum data diteruskan ke domain atau database.

Bootstrap Container bersifat server-first: session dan personalization cookie yang tervalidasi menjadi snapshot first paint. context-session hanya menangani auth/session; context-personalization adalah hook terpisah tanpa fetch atau effect bootstrap global sampai policy sync lintas-device dirancang dan diukur kembali. Provider global tidak boleh menjadikan inventaris multi-session, preference sync, atau metadata non-kritis sebagai syarat render. Inventaris perangkat hanya boleh direfresh melalui aksi eksplisit; snapshot session aktif tetap cukup untuk render awal. Revalidation client tidak boleh memicu router.refresh() hanya untuk menyelaraskan snapshot. Layar yang benar-benar membutuhkan data tersebut memuatnya saat dibuka, dengan loading/error state lokal.

Mobile native berada di repository aori-mobile dan tidak menggunakan cookie browser sebagai sesi. Ia menerima bearer session Better Auth dari header set-auth-token, menyimpannya hanya di Keychain/Keystore melalui Expo SecureStore, lalu memvalidasi ulang token ke API pada setiap cold start. Route operasional dilindungi di tingkat Expo Router, tetapi authorization resource tetap sepenuhnya diperiksa API. Token tidak boleh disimpan di AsyncStorage, URL/deep link, log, analytics, atau state persistence biasa.

OAuth mobile tidak boleh mengirim bearer pada custom URL scheme. Flow native membuat attempt singkat di API dengan exchange-secret yang hanya berada di memori aplikasi; browser menyelesaikan OAuth Better Auth menuju callback API; callback menerbitkan grant opaque sekali pakai ke deep link; lalu aplikasi menukar grant dan exchange-secret melalui HTTPS. Token sementara di server dienkripsi dengan material BETTER_AUTH_SECRET, dan record verification dihapus atomik setelah exchange. Callback URL mobile adalah konfigurasi server (AORI_MOBILE_AUTH_CALLBACK_URL), bukan parameter client. Sebelum rilis production, custom scheme harus diganti/diperkuat dengan universal link atau Android App Link yang tervalidasi.

12. Internasionalisasi dan Pengalaman Pengguna

Aori membangun kontrak i18n yang bersifat multi-layer. Sebagai contoh: Aplikasi container menggunakan locale route, cookie resolution, message loading, dan IntlProviderApp. Secara global aplikasi utama (apps/app/*) memiliki i18n di contracts/i18n sebagai source-of-truth message, namun hanya message yang digunakan bersama atau yang digunakan dibanyak tempat yang ditulis dalam contracts/i18n, sedangkan message yang jarang digunakan seperti untuk Form, halaman auth, dan beberapa lainnya akan di bangun lokal dalam domain-nya masing-masing. Package i18n bersama (packages/i18n) adalah tools untuk membangun semua itu, beserta helper-nya.

User personalization mendukung:

• bahasa dan locale;
• timezone Asia/Jakarta sebagai default;
• format tanggal dan waktu;
• theme system/light/dark;
• accent color dan font size;
• compact mode dan animations;
• notification preferences;
• privacy dan analytics preferences;
• content preferences;
• accessibility preferences seperti high contrast, reduced motion, dan screen-reader optimization.

12. Build, Development, dan Tooling

Workspace menggunakan Bun dan Turborepo. turbo.json mendefinisikan task utama:

• build dengan dependency antar-package dan output .next/dist;
• lint;
• type-check;
• dev tanpa cache dan persistent;
• clean;
• Prisma generation.

API menyediakan command untuk:

• menjalankan server Bun/Express;
• type-check dan lint;
• generate Prisma client untuk empat schema;
• push schema ke lima database;
• membuka Prisma Studio per domain;
• seed database;
• generate database types ke packages/db/types.

Paket internal menjaga konsistensi design system, type system, auth, HTTP access, iconography, form, hooks, data access, dan utility behavior antar-aplikasi.

13. Alur Bisnis End-to-End yang Diinginkan

Skenario dokumentasi utama menggunakan bisnis seperti Satoe Coffee Indonesia:

1. User mendaftar sebagai identity.
2. User membuat Organization/workspace.
3. Sistem membuat membership owner.
4. Owner membuat permission roles.
5. Owner membuat position hierarchy.
6. Owner mengundang user lain.
7. Invitee menerima invitation dan menjadi member.
8. Member dapat dibuat menjadi employee.
9. Employee memiliki position, contract, salary, attendance, shift, dan payroll.
10. Bisnis membuat catalog product/service.
11. Product dapat diberi price, promotion, dan inventory tracking.
12. Customer membuat cart atau order.
13. Commerce menyimpan order, invoice, payment, shipment, dan snapshot.
14. Inventory mereservasi dan mengurangi stok melalui movement ledger.
15. Laporan dapat menggabungkan identity, catalog, commerce, inventory, dan HR berdasarkan organization.

14. Kekuatan Arsitektur Saat Ini

1. Bounded context cukup jelas. Runner, catalog, commerce, dan inventory memiliki ownership model yang eksplisit.
2. Multi-tenancy sudah menjadi prinsip schema. Hampir seluruh entity bisnis membawa organizationId.
3. Histori diperlakukan serius. Snapshot dan immutable event mencegah perubahan master merusak histori transaksi.
4. Presisi data diperhatikan. Uang memakai BigInt dan quantity inventory memakai fixed-point integer.
5. Identity, authorization, dan employment dipisahkan. Ini lebih fleksibel daripada menjadikan satu tabel user sebagai semua hal.
6. API security sudah dipikirkan sejak awal. Ada layer authentication, proxy trust, permission, validation, rate limiting, dan error contract.
7. Monorepo mendukung reuse. Komponen, config, hooks, icons, auth, database types, dan HTTP client dapat digunakan lintas aplikasi.
8. Model product generik. Aori dapat melayani barang fisik, digital, jasa, bundle, dan subscription.

15. Tantangan dan Risiko yang Perlu Dijaga

1. Konsistensi lintas database. Tidak ada transaksi terdistribusi sehingga purge, order-to-inventory, dan sinkronisasi antar-domain perlu idempotency, retry, serta reconciliation.
2. Tenant isolation. Setiap query lintas domain harus selalu memfilter organizationId; kesalahan kecil dapat menjadi kebocoran data antar-tenant.
3. Perbedaan dokumentasi dan implementasi. Beberapa README tampak berasal dari tahap migrasi sebelumnya, sehingga kontrak environment dan nama schema perlu terus diselaraskan dengan kode aktual.
4. Scope produk sangat luas. HR, payroll, commerce, dan inventory membutuhkan rule bisnis, audit trail, serta workflow approval yang rinci.
5. Kematangan UX. Banyak fondasi teknis sudah tersedia; tahap berikutnya perlu memastikan alur onboarding, navigation, empty state, error state, dan mobile experience konsisten.
6. Operational observability. Request ID sudah ada, tetapi production sebaiknya dilengkapi tracing, metrics, structured logs, alerting, dan rekonsiliasi domain.
7. Migration governance. Empat schema Prisma dan generated clients memerlukan proses migration/versioning yang disiplin.

16. Arah Pengembangan yang Masuk Akal

Arah pengembangan yang konsisten dengan fondasi Aori:

Tahap platform foundation

• menyelesaikan kontrak API utama;
• menstabilkan Better Auth dan organization session;
• menyempurnakan onboarding organization/workspace;
• membangun permission management dan invitation UX;
• menambahkan audit log untuk operasi sensitif.

Tahap business operations

• employee directory;
• position dan organization hierarchy;
• attendance dan shift;
• payroll calculation serta approval;
• catalog CRUD, pricing, dan media;
• customer, cart, dan order flow;
• warehouse, reservation, dan stock movement.

Tahap reliability

• idempotency key pada command transaksi;
• outbox/event pattern untuk lintas domain;
• reconciliation job commerce-inventory;
• soft archive dan retention policy;
• observability dashboard;
• contract test API dan integration test per database.

Tahap scale dan ecosystem

• React Native/Expo client;
• public commerce/storefront;
• report builder;
• integrasi payment gateway dan shipping;
• multi-region dataset;
• plugin/integration framework;
• analytics dan business intelligence.

17. Blueprint Domain Terkunci

Bagian ini adalah referensi implementasi ketika istilah legacy bertentangan dengan model domain. Nama fungsi/rute lama yang memakai workspace untuk organization harus dimigrasikan bertahap dan backward-compatible.

Identity dan tenancy

TeamMember.memberId wajib dan employeeId opsional. Participant eksternal tetap Member organization asalnya; ia tidak diubah menjadi Member organization host hanya agar dapat bekerja di sebuah workspace.

Collaboration lintas organization

Collaboration minimal melibatkan dua party. Source of truth partner adalah CollaborationParty, bukan array partnerOrganizationIds, karena setiap party memerlukan role, status, scope, representative, approval, dan masa berlaku. CollaborationWorkspace dapat menghubungkan banyak workspace, tetapi semua workspace itu harus dimiliki owner organization collaboration. Sebelum memberi akses, API harus memverifikasi tenant party/member/team, approval wajib, scope subset, dan validity window.

Lima database

Tidak ada foreign key, join, Prisma relation, atau transaksi ACID lintas database. Gunakan scalar ID tervalidasi, outbox/inbox, idempotency key, ordered write atau compensation, projection read model, dan reconciliation job.

Billing, entitlement, dan retensi

BillingAccount memisahkan identitas penagihan dari Organization. Plan berversi menyimpan harga BigInt minor unit; Subscription menyimpan snapshot komersial. Entitlement adalah capability/quota efektif. Domain pemilik resource menghitung usage atomik dan mengirim metering idempoten.

Setiap aksi berfitur memeriksa entitlement tenant dan permission actor. Subscription tidak memberi permission; permission tidak melampaui limit plan. Data aktif dipertahankan selama periode pembukuan, kemudian archived. Purge hanya sesudah retention/legal policy, legal hold, pemberitahuan, dan export window; ia job auditable, bukan operasi UI rutin.

Kontrak container

apps/app/container adalah host micro-frontend. Ia tidak boleh menyimpulkan entitlement, ownership, role, harga, atau quota dari cookie/route/UI. Parse semua data API untrusted dengan Zod v4 di apps/app/container/schema. Bila endpoint kontraktual belum tersedia, gunakan read-only/loading/empty/unavailable state yang jujur; jangan membuat checkout, upgrade, atau kolaborasi palsu.

18. Kesimpulan

Aori adalah fondasi platform bisnis terpadu yang sedang dibangun dengan pendekatan domain-driven dan multi-tenant. Produk ini ingin menjembatani identity, organisasi, HR, catalog, transaksi, dan inventori tanpa mengorbankan keamanan, presisi finansial, atau histori operasional.

Jika diringkas dalam satu kalimat:

Aori ingin menjadi sistem operasi bisnis multi-cabang yang menyatukan orang, proses, barang/jasa, transaksi, dan stok dalam satu platform yang aman, dapat diaudit, dan siap berkembang.

Dokumen ini disimpan di apps/docs/content/blueprint/03.overview.md agar menjadi orientasi awal yang terpublikasi dan tetap dekat dengan dokumentasi lain bagi contributor, engineer, product owner, dan stakeholder teknis Aori.