Video scripts

Vietnamese original: demo-video-series.md.

This document is used to record a series of marketing videos that introduce Astra. The storyline comes from use-case-01.md: a courier company that takes orders (OMS), runs parcel operations (OPS), handles customer care (CARE) and manages receivables and the ledger (BMS). Everything shown in the videos is code that actually runs in the repository, as a thin slice: enough to prove the mechanism, not yet the full scope of the use case. The platform mechanism videos (9, 11 to 17) and the new business videos (19 to 21) have a "To be accurate" section that states the current limits; each video links to the code to show developers in demo-code-snippets.md (code excerpted from the repo, with flow diagrams).

Background music: "Corporate Tower" by Mare Production (freesound.org/s/612264), CC BY 4.0, edited.

Vietnamese voice-over: the male voice "Xuân Vĩnh" from VieNeu-TTS v3 Turbo (Apache-2.0), synthesized by scripts/video-voiceover.py from the narration.json file in each video folder. The English versions use the Kokoro-82M voice am_michael (Apache-2.0) via hyperframes tts, synthesized by scripts/video-voiceover.py --lang en from narration.en.json. Fonts: Be Vietnam Pro (SIL OFL 1.1) for text, JetBrains Mono for code.

1. Preparing the recording environment

Requirements: JDK 25, Docker Desktop (the whole stack runs with 8 GB of RAM allocated to Docker), kubectl, k3d, jq, Bash 5 (brew install bash; the scripts re-run themselves under Bash 5 if the default shell is macOS Bash 3.2), Rust (only needed when changing the Wasm modules or the CDC worker).

make k3d-up          # k3d cluster: 2 kernel pods, PostgreSQL (wal_level=logical), Redis, Keycloak, Seata, Rust CDC worker
make demo-seed       # 2 tenants: saigon-express, hanoi-express; data via the REST API, Keycloak login
open http://localhost:8080/desk/          # Desk (Keycloak login, PKCE)

make demo-reset && make demo-seed         # clean up before each recording session (documents, ledger, overlays, BMS, Redis)
make demo-express SCENES="10 11" PAUSE=0  # run terminal scenes; drop PAUSE=0 to press Enter through each step

make k3d-up rebuilds the images, syncs the Keycloak realm (scripts/keycloak-sync-realm.sh), prepares the database (scripts/db-setup.sh: BMS schema, CDC role/publication) and deploys everything.

Video 8 (the kernel refuses a superuser) and Video 9 (live reload) also need the Docker Compose stack. k3d and dev mode both default to port 8080, so run dev mode on another port and point every script at it:

make infra-up && make build                          # PostgreSQL :5432, Redis, Keycloak :8180 (Video 8 only needs this far)
                                                     # infra-up runs scripts/keycloak-compose-dev.sh: dev Keycloak accepts HTTP from the host + realm sync
make dev DEV_ARGS=-Dquarkus.http.port=8081           # Video 9
BASE=http://localhost:8081 make demo-seed            # seed into dev mode; reset with: scripts/demo-reset.sh compose

Demo users (shared password: Astra@123, realm deploy/keycloak/realm/astra-realm.json)

Recording tools

Tip: 1440×900 window; terminal at 16 to 18 pt; record right after demo-reset + demo-seed so document numbers match the script (ORD-<date>-00007…). The date in the order number is the date the seed ran.

2. Feature map → where it is proven

3. Video list

Suggested length: teaser 60 to 90 seconds, feature videos 3 to 6 minutes, developer videos 6 to 8 minutes.

Video 0: Teaser "One platform, every business process" (90 seconds)

Developer code: S0

Cut quickly from footage of the later videos:

1. The customer-order.doctype.yaml file → the "Customer Order" Desk appears.
2. Submit an order → the waybill is generated, the journal entry Debit 131 / Credit 511 appears under the form.
3. Two tenants side by side: Hanoi has an extra VAT field (overlay), Saigon does not.
4. An infinite-loop Wasm script: "stopped after 50 ms".
5. Claude asks "where is parcel WB-…?", the phone number shows as *******567.
6. The "sync pending" badge → "in sync" after a few tens of ms (Rust CDC).
7. Seata: an order over the credit limit, everything rolls back, the undo log is clean.
8. Closing: "Astra: Java 25, Quarkus, PostgreSQL, Rust. Open source."

Video 1: What Astra is & running it in 5 minutes

Developer code: S0

Video 2: DocType, from one YAML file to API, UI and index

Developer code: S1, S12

Video 3: Business rules, hooks & validation

Developer code: S2

Video 4: Document lifecycle, Submit, Cancel, Amend

Developer code: S3

Video 5: Operations, the parcel state machine

Developer code: S3

Video 6: Customer care sees operations

Developer code: S3 (the TicketTriageHook hook follows the same pattern as the hooks in S2/S3)

Video 7: Multi-tenancy

Developer code: S4

Video 8: Fail-closed security

Developer code: S4

make infra-up && make build && make demo-express SCENES=8: a second kernel connects as a superuser and refuses to start. Open deploy/docker/init/01-app-role.sql: the application role is NOSUPERUSER NOBYPASSRLS.

Video 9: For developers, writing an Astra app

Developer code: S2, S12

To be accurate: after step 4, run make demo-reset && make demo-seed, because removing a field from a DocType makes older documents that still have that field impossible to edit; safe schema evolution is still on the roadmap.

Video 10: Running on Kubernetes

Video 11: Keycloak, one identity, per-tenant roles, per-DocType permissions (scene 9)

Developer code: S5

To be accurate: row-level permission conditions are still on the roadmap. SAML SSO and SCIM now run, see Video 21.

Video 12: Append-only ledger (scene 10)

Developer code: S6

To be accurate: a trigger blocks UPDATE/DELETE; the role that owns the table can still DROP/ALTER, so production should run the kernel with a role that does not own the tables. An audit hash chain is still on the roadmap.

Video 13: Per-tenant overlays (scene 11)

Developer code: S7

To be accurate: overlays add/modify fields, they do not add hooks or permissions yet; they cannot remove an app's fields.

Video 14: Tier 2 Wasm, a tenant's own freight formula (scene 12)

Developer code: S8

To be accurate: Chicory has no instruction counting (fuel) yet, so the CPU limit is a time deadline. Tier 1 (JVM hot-swap) is still on the roadmap.

Video 15: MCP, an AI agent uses Astra with the user's permissions (scene 13)

Developer code: S9

To be accurate: the client uses a static bearer token (the dev client's 1-hour token); OAuth discovery for MCP, autonomous AI agents and vector search are still on the roadmap. PII masking applies to the MCP channel, not to Desk.

Video 16: Rust CDC + Sync-Aware LSN (scene 14)

Developer code: S10

To be accurate: the worker reads the slot with pg_logical_slot_peek_binary_changes every 50 ms (at least once, idempotent upsert) and does not use the streaming protocol yet; nothing is pushed to Apache Doris yet.

Video 17: Seata, one submit across three resources (scene 15)

Developer code: S11

To be accurate: Seata Server uses the file store (enough for the demo; production uses DB/Raft); TCC handles idempotency/empty rollback/suspension per branch itself and does not use Seata's fence table yet; the kernel commits its own transaction last (last resource) and is not yet a Seata branch.

Video 19: HRM, HR and payroll

Developer code: astra-apps/hrm (PayrollEntryHook, SalaryCalculator, astra-apps/hrm/wasm/courier-kpi); test HrmPayrollTest.

Goal: an HR and payroll app written on the public SPI, following the Frappe HRMS concepts (Employee, Salary Component, Salary Structure, Salary Structure Assignment, Attendance, Additional Salary, Payroll Entry, Salary Slip). Attendance determines working days, the courier bonus is a tenant Wasm module, and each Payroll Entry writes exactly one accrual journal entry to the ledger. Only the concepts are taken; no code, schema or UI is copied from ERPNext/HRMS.

Setup: make demo-seed loads September 2026 (26 working days) for saigon-express: NV001 has full attendance, delivered 1,067 parcels; NV002 absent on 15/9, half day on 22/9, delivered 1,007 parcels; NV003 started on 14/9, has a 500,000 bonus; NV004 on unpaid leave on 29/9. The script logs in as hanh (hr). If the realm just changed, run scripts/keycloak-sync-realm.sh to get hanh.

To be accurate:

• No personal income tax is computed; net is gross minus the employee share of insurance. The employer share (BHXH, BHYT, BHTN, KPCĐ) is not computed. Insurance rates and caps are seed configuration for the demo and have not been checked against current regulations; the rule that 14 or more days of leave means no BHXH contribution is not handled.
• Minimal attendance: no holiday calendar, shifts, check-in or leave requests with leave balances; the working week is fixed Monday to Saturday; days without an attendance record count as worked. Parcel counts are entered by ops with attendance, not yet pulled automatically from Waybill or STMS through CDC as the use case describes.
• Only 4 calculation types (Fixed, % base, % gross, Wasm), no formula editor yet. No salary payout journal entry (Debit 334 / Credit 112), no bank file export. The accrual journal entry records totals per account, not per employee on 334; all cost goes to 642, with no cost-center allocation.
• The batch runs inside the request that saves the entry (up to 1,000 employees per run); there is no month-end background job or leader election yet. Salary slips and the ledger share one PostgreSQL transaction, without Seata.
• Employees cannot view their own salary slips yet: the if-owner permission applies to writes only, not to reads.
• There is no dedicated payroll Desk yet: the generic Desk shows slip lines as "N item(s)".
• The figures in the table above are the expected results computed from the hook's logic; use the on-screen numbers from the actual recording.

Video 20: STMS, vehicle dispatch with Timefold + AI copilot

Developer code: astra-apps/stms (solver/RoutePlanner, Replanner, copilot/DispatchCopilot, copilot/MockLlmClient); tests RoutePlannerTest, StmsDispatchTest, StmsMcpTest.

Goal: the vehicle routing problem (VRP with capacity and time windows) solved by Timefold Solver inside the kernel; when an incident happens, the plan is re-solved from the current routes; the dispatcher gives commands in Vietnamese through the copilot, and the copilot calls those same MCP tools. The solver, replanning and the tools are real; the copilot's language model is a simulated script for the demo (llm: "mock"). Every frame showing the copilot must show the label "LLM giả lập (kịch bản demo)" (simulated LLM, demo script).

Setup: make demo-seed creates, for each tenant, a fictional hub (saigon-express: HCM-TB Kho Tân Bình), 3 vehicles and 20 delivery/pickup stops for the seed date (STMS_DATE, defaults to today in Vietnam time; use the same value for seed and demo). The script logs in as linh (dispatcher). Run the scenes in order: scenes 3 to 8 use the plan created by scene 2.

To be accurate:

• The copilot does not call any language model: MockLlmClient matches commands against fixed Vietnamese patterns and a small list of place names; commands outside the script produce no tool call. The explanation is written from the solver's real results. The plug-in point for a real LLM provider is the LlmClient interface; there is no implementation yet.
• No map, real road network or live traffic: distance is straight-line distance × 1.3, at a fixed speed of 25 km/h, and a "traffic jam" is a slow zone declared by the dispatcher. No geocoding: stops come with coordinates.
• Replanning means re-solving from the current routes, without keeping the solver running all day; time does not advance, so delivered stops and vehicles on the road are not locked. Adding an urgent order and re-solving are two transactions: if the re-solve fails, the new order is still saved.
• Capacity is one combined total per vehicle (deliveries and pickups added together); there are no pickup-before-delivery constraints, multiple trips, driver shifts and breaks, return-to-hub deadlines, vehicle types or vehicle costs. One hub per plan, no transfers between hubs.
• No AI load forecasting (Tier 1), driver app, GPS or field ETA updates yet. No route map yet: Desk shows a text route table and JSON.
• The demo has about 20 stops and solves in 1 to 2 seconds; larger problems have not been measured. On-screen numbers come from the actual recording; numbers in the phase report were measured on test data and will differ slightly from the seed data.
• DispatchEvents and urgent orders created by tools have the owner stms-mcp / stms-copilot; the real caller is recorded in the MCP server log.

Video 21: SAML SSO and SCIM

Developer code: deploy/keycloak/realm/acme-corp-idp-realm.json, deploy/keycloak/realm/astra-realm.json (identity provider acme-corp), astra-iam (ScimResource, ScimDirectory, ScimPatch); tests SamlBrokerTest, ScimTest.

Goal: a company's employees log in to Astra with their company's IdP over SAML 2.0, and IdP groups become tenant roles; the company's identity management system creates, assigns roles to, disables and deletes accounts over SCIM 2.0, only within its own tenant.

Setup: Keycloak must have the realm acme-corp-idp, the identity provider acme-corp and the SCIM clients. make infra-up (runs scripts/keycloak-compose-dev.sh) or make k3d-up syncs the realm; if Keycloak was already running, re-run scripts/keycloak-sync-realm.sh, then restart astra-server to get /scim/v2. The video's tenant is acme. The users linh and bao here belong to the IdP realm acme-corp-idp; this is not the dispatcher linh from Video 20.

To be accurate:

• The IdP is a Keycloak realm (acme-corp-idp) in the same container, not Okta, Entra or ADFS; the SAML protocol between the two sides is real. The demo replays the browser steps with curl and does not follow the redirect back to Desk.
• Assertion and response are signed and verified; the assertion is not encrypted, the AuthnRequest is not signed. Only SP-initiated; IdP-initiated is not configured; Single Logout is not wired up and not tested.
• On first login Keycloak creates the account acme-corp.<username>; if the email matches a local account, Keycloak asks to link them, and the demo does not show this step. The group → role mapping is fixed in the realm configuration and only for tenant acme; each other company needs its own IdP and mapper.
• SCIM has no Bulk, ETag/meta.version, sort, /Me, meta.lastModified or attributes parameter yet; excludedAttributes only applies to Groups members. Filters support only userName eq and displayName eq. externalId is ignored; only one email is kept; userName cannot be changed.
• Groups are fixed because they are the tenant roles: creating or deleting a group returns 501, only membership can change. A tenant's SCIM client only sees and edits users it provisioned. Deleting through SCIM also deletes the Keycloak account.
• Role changes take effect from the next login or refresh. After active=false, an access token already issued stays valid until it expires, because Astra verifies the JWT offline (5 minutes for regular clients, 1 hour for the demo client astra-dev-cli).
• Listing users fetches members from Keycloak and paginates in memory, with one extra group read call per user: enough for the demo, not meant for hundreds of thousands of users. The SCIM client secrets in the realm JSON are for local environments only.

Video 18: Roadmap, the rest of use-case-01 (In development)

Every frame is labelled "Roadmap / In development".

4. Pre-publication checklist

• Each video only claims what is in the table in section 2; read the "To be accurate" sections before recording the voice-over.
• Video 18 and every roadmap frame carry the "In development" label.
• Video 20: every frame with the copilot clearly shows "LLM giả lập (kịch bản demo)" (simulated LLM, demo script); never say or imply there is a real language model.
• Performance figures (CDC lag, sandbox time) come from the actual recording, not rounded to look better than reality.
• Customer data is fictional seed data (scripts/demo-seed.sh).
• Demo passwords appear only on the local stack; do not record screens that show tokens.
• Videos with CC BY music: the video description includes a credit line (Video 0: see docs/video/teaser/CREDITS.txt).