AGENTS.md — BitCode Platform

Multi Brain (MANDATORY — read before starting work)

Read .multibrain/session.md before starting work.
Use .multibrain/session.md as the master index only.
Open only the .multibrain/buckets/*.md files that match the current task.
Open .multibrain/context/*.md only when the selected bucket points to deeper context that matters.
After meaningful work, update the relevant named bucket and refresh the master index if needed.

Code Search: bit-rag MCP (MANDATORY — use before Grep)

Use bit-rag___rag_search_code with root_path="D:\NodeJS\lowcode" for ALL code search.
bit-rag has hybrid search (dense + BM25 keyword + RRF fusion) — handles both semantic and identifier queries.
If search returns "Indexing started" (new/changed project), use Grep as fallback while indexing completes.
Do NOT use ccc (.cocoindex_code/ is legacy — bit-rag replaces it).

Understanding the Project

Read these docs before making any changes:

Doc	What It Covers	When to Read
`docs/architecture.md`	System design, data flow, core concepts, tech stack	First time touching the project, or when working across layers
`docs/codebase.md`	Full file map with one-line descriptions per file	When you need to find where something lives
`docs/features.md`	Feature inventory (67 features), status, gaps, roadmap	When planning work or understanding what exists vs what's missing
`engine/docs/features/`	Per-feature deep docs (models, APIs, processes, views, etc.)	When working on a specific engine feature
`docs/adr/README.md`	ADR index — daftar 5 ADR (Mitosis compiler, cross-platform arch, component roadmap, reactive engine, metadata-driven UI)	When asking why a UI architectural decision was made, or before adding a new ADR
`docs/components-progress.md`	Component progress tracker — Stencil/Mitosis/Contract/A11y status per component (P0/P1/P2)	When asking which UI components are done or planning next component to build

Project Overview

Modular low-code ERP platform. Go engine reads JSON definitions and produces running applications. Inspired by Odoo, Frappe, NocoBase.

JSON is the source code. Go is the runtime. Modules are the packaging. Stencil Web Components are the UI.

bitcode/
├── engine/              Go runtime
│   ├── cmd/             Entry point (bitcode CLI — serve, dev, init, validate, etc.)
│   ├── internal/        Private app code (compiler, domain, runtime, infrastructure, presentation)
│   ├── pkg/             Public packages (ddd, security, plugin SDK)
│   ├── modules/         Built-in modules (base, crm, sales)
│   ├── embedded/        Go-embedded modules compiled into binary
│   └── plugins/         Plugin runtimes (TypeScript, Python)
├── packages/
│   ├── components/      Stencil Web Components (@bitcode/components, 122 components, 11 groups)
│   ├── go-json/         go-json — JSON/JSONC programming language engine (standalone Go package)
│   ├── go-json-runtimes/ Script runtime engines for go-json (separate go.mod: goja, quickjs, yaegi, Node.js, Python)
│   └── tauri/           Tauri 2.0 native shell (desktop + mobile)
├── samples/
│   └── erp/             Sample ERP application (CRM + HRM)
├── docs/                Project-level documentation
└── sprints/             Sprint planning & tracking

Conventions

Go 1.24+ (engine + go-json), standard project layout (cmd/, internal/, pkg/)
DDD internally, flat JSON externally — users never see DDD terms
Convention over configuration — sensible defaults everywhere
All PK and FK are UUID (TEXT in SQLite, UUID in Postgres, CHAR(36) in MySQL)
Tests: every package with logic has _test.go. Run cd engine && go test ./...
No comments unless absolutely necessary (complex algorithms, public API docs)
No type suppression — no as any, @ts-ignore, or equivalents

Tooling: `rtk` Wrapper

This project uses rtk (Rust toolkit) as a wrapper for go build, go test, go vet, etc. It parses output to reduce token usage.

Default: Use rtk go test ./... -count=1 normally — it summarizes pass/fail counts.

When you need full output (compilation errors, verbose test output, debugging failures): pipe through | Out-String to bypass rtk's output parsing:

rtk go test ./io/ -run TestCache -v -count=1 2>&1 | Out-String
rtk go build ./... 2>&1 | Out-String
rtk go vet ./... 2>&1 | Out-String

Use full output when:

Tests fail and you need to see which test/assertion failed
Build errors need full compiler output
You need verbose (-v) test names and timing
Any situation where rtk's summary says "No tests found" but tests should exist (rtk may not parse certain flag combinations like -race)

File Structure Rules (Engine)

engine/internal/compiler/parser/ — JSON parsers. One file per definition type.
engine/internal/domain/ — Domain models. DDD patterns (entity, aggregate, events). No DB imports.
engine/internal/runtime/ — Execution engines (process executor, agents, workflow, plugins).
engine/internal/infrastructure/ — External concerns (DB, cache, module loader, i18n).
engine/internal/presentation/ — HTTP layer (routes, middleware, views, templates).
engine/pkg/ — Public packages reusable outside engine (ddd, security, plugin SDK).
engine/modules/ — Built-in modules (base is always installed).
engine/embedded/ — Go-embedded modules compiled into the binary.
engine/plugins/ — Plugin runtimes (TypeScript, Python).

File Structure Rules (Components)

packages/components/src/components/ — Stencil Web Components (each has .tsx + .css).
packages/components/src/core/ — Shared infrastructure (types, API client, event bus, form engine, i18n, BcSetup, data-fetcher, validation-engine, field-utils, bc-native, offline-store).
packages/components/src/utils/ — Shared utilities (expression eval, format, validators).
packages/components/src/global/themes/ — Theme CSS files (dark.css, custom themes).
packages/components/docs/ — Per-component documentation (self-contained for future repo split).
packages/components/src/i18n/ — Translation files (11 languages).

File Structure Rules (go-json)

packages/go-json/lang/ — Core language engine: AST, parser, compiler, VM, scope, types, errors, expr engine, debugger.
packages/go-json/stdlib/ — Layer 2 stdlib functions (120+ functions: math, strings, arrays, maps, datetime, encoding, crypto, validate, format, env, types, path, JSON). Layer 1 is expr-lang built-ins (~68 functions, zero work).
packages/go-json/runtime/ — Runtime API: NewRuntime(), Execute(), program cache, limits, logger, session context.
packages/go-json/cmd/go-json-lite/ — Lite CLI entry point (core only, no script runtimes).
packages/go-json-runtimes/cmd/go-json/ — Full CLI entry point (script runtimes wired in). This is the recommended install.
packages/go-json/examples/ — Runnable programs backing the README, verified by examples_test.go.
packages/go-json/codegen/ — Code generation (reserved for Phase 4.5b+).
packages/go-json/io/ — I/O modules (reserved for Phase 4.5c+).
packages/go-json/testdata/ — Test fixture programs (.json and .jsonc).
Design doc: docs/plans/2026-07-14-runtime-engine-phase-4.5a-go-json-core-language.md
Implementation plan: docs/plans/2026-07-14-runtime-engine-phase-4.5a-go-json-core-language-plan.md
Tests: cd packages/go-json && go test ./... -v

When Making Changes

Adding a New Feature (Engine)

Add parser in engine/internal/compiler/parser/ if it has a JSON definition
Add domain types in engine/internal/domain/ if it has business logic
Add runtime in engine/internal/runtime/ if it executes something
Add infrastructure in engine/internal/infrastructure/ if it talks to external systems
Wire in engine/internal/app.go
Add feature doc in engine/docs/features/
Write tests

Adding / Modifying Components

Add/edit component in packages/components/src/components/
Update packages/components/src/components.d.ts if new component
Run npm run build in packages/components/ to verify
Add/update component doc in packages/components/docs/ (1 md file per component)
Update packages/components/docs/README.md index if new component

Documentation Updates (MANDATORY)

After ANY code change, update the relevant docs:

What Changed	Update These
New file or directory added	`docs/codebase.md` — add to file map
Architecture change (new layer, new service, new data flow)	`docs/architecture.md` — update diagrams and component tables
Feature added, completed, or status changed	`docs/features.md` — update status (✅/⚠️/❌), check off roadmap items
Engine feature added/changed	`engine/docs/features/*.md` — update or create per-feature doc
New module or module structure change	`docs/codebase.md` — update module section
New component added to packages/components	`docs/codebase.md` — update components section, `packages/components/docs/` — add component doc
Public API changed (new endpoint, new config)	`README.md` — update config table, CLI commands, or feature list
Major milestone or project-level change	`README.md` — update overview

Rule: if you changed code, you changed docs. No exceptions.

i18n Check (MANDATORY)

After ANY implementation that adds user-facing text (templates, error messages, labels, UI strings):

Check if the text needs i18n support
If yes — use the t template function ({{t .Locale "key"}}) instead of hardcoded strings
Add translation keys to the module's i18n/*.json files
At minimum provide en (English) translations as the default
If the module already has other locale files (e.g., id.json), add translations there too

Rule: no hardcoded user-facing strings in templates. Use i18n keys.

Required languages (11): en, id, ar, de, es, fr, ja, ko, pt-BR, ru, zh-CN

All 11 locale files must be provided for every module that has user-facing text. English (en) is the default fallback.

What To Work On Next

Completed ✅

Remaining (Engine)

Offline Mode (In Progress — Phase 1-2 of 5 complete)

Design doc: docs/plans/2026-04-28-offline-mode-design.md Implementation plan: docs/plans/impl/offline-mode-implementation.md Feature ref: engine/docs/features/offline-mode.md

Architecture: Stencil components (unchanged) run inside Tauri's native WebView. bc-native.ts bridge routes native capability calls to Tauri IPC or Web API fallback. Go engine generates _off_* columns/tables for offline tracking and provides sync API endpoints.

What's done:

Phase 1: Foundation — Engine understands mode:"offline", generates _off_* columns, creates infrastructure tables, sync API stubs
Phase 2: Tauri Shell — Tauri 2.0 project, bc-native.ts bridge (13 methods), build pipeline (desktop/android/ios)
Phase 2.5: Per-model app.mode in model.json — resolution chain: model → module → project → default("online")
Phase 2.5: offline-store.ts — intercept layer that routes CRUD to local SQLite (offline models) or fetch() (online models)
Phase 2.5: Schema sync endpoint — GET /api/v1/sync/schema returns offline model list + field definitions for device registration

What's NOT done (Phase 3-5):

Phase 3: Sync Engine — device registration flow, outbox recording, sync push/pull, envelope grouping
Phase 4: Conflict Resolution — HLC, field-level merge, receipt numbering, inventory deltas
Phase 5: Polish — SQLite encryption, offline auth, cross-platform testing

CRITICAL CONTEXT for future sessions:

Server-side _sync_* tables are Go-generated, NOT JSON models. They are infrastructure tables (like audit_log, data_revisions, ir_migration) created directly via sync_schema.go DDL. They do NOT appear in admin panel, do NOT get auto-CRUD, and developers never define them. Future task: When the base/core module is migrated from Go code to JSON model definitions, these sync tables should be evaluated for migration too — but they may intentionally stay as Go-generated infrastructure.
Client-side _off_* tables are defined in TWO places (known duplication):
- engine/internal/infrastructure/persistence/offline_schema.go — Go DDL for server-side schema generation
- packages/tauri/src-tauri/src/main.rs — Rust SQLite migrations for client-side This duplication exists because Phase 3 (schema sync) is not yet implemented. Once Phase 3 is done, the Tauri client should receive schema from server during device registration, eliminating the Rust-side hardcoded migrations.
bc-native.ts uses window.__TAURI__ global (requires withGlobalTauri: true in tauri.conf.json). This avoids npm dependency on @tauri-apps/api — Stencil components stay framework-agnostic.
Mobile plugins (barcode-scanner, biometric) are behind Cargo feature flag mobile-plugins because they require platform-specific SDKs that don't compile on desktop. Enable with cargo build --features mobile-plugins.
offline-store.ts intercepts at the data-fetcher level. It checks BcSetup.isModelOffline(modelName) and routes to BcNative.dbSelect()/BcNative.dbExecute() for offline models, or falls through to normal fetch() for online models. This means existing Stencil components work without modification.

Full roadmap with 75 features: see docs/features.md

Multi-Brain Session Memory (ALWAYS ACTIVE)

Lightweight cross-session memory system. Lives in .multibrain/. Complements (does not replace) the JCE .opencode-context.md + .opencode-jce/context/ system and the handoffs/ folder.

When .multibrain/session.md exists (it does now):

Session start: Read .multibrain/session.md first. Then open only the bucket file(s) matching the current task. Do not open all buckets.
After meaningful work: Append ONE short entry (date + 3–8 bullets) to the matching bucket file. Update the bucket's "Last touched" line and the master .multibrain/INDEX.md if status changed.
Bucket selection: Match the task to a bucket. If a task spans buckets, write the primary entry to the most relevant bucket and add a one-line cross-reference in the secondary bucket.

Buckets (see .multibrain/INDEX.md for live status):

ui-library — packages/ui Mitosis components, ADR-007/008/009/010/013, contract-first freeze
engine — Go engine, runtime, JSON definitions, modules, persistence
flutter — packages/ui-flutter adapter, token bridge, FPW adaptive, demo parity
offline-mode — Tauri shell, sync engine, bc-native bridge, _off_* tables
adr — Architecture Decision Records (active frontier: ADR-017/018 Block Catalog)
demo-app — packages/ui/demo-app + packages/ui-flutter/example parity sweeps

Rules:

One file per bucket; append-only within a bucket (never overwrite past entries).
Never delete bucket files or the archive. Move resolved entries to .multibrain/archive/ only when a bucket exceeds ~50 entries.
Multi-brain is for AI session context, not human docs. Human-facing docs still go to docs/, engine/docs/features/, and handoffs/.
If another agent is working a different feature, do not remove or rewrite their bucket entries — append your own with a date.

Session Handoff

Ketika pekerjaan perlu dilanjutkan di session baru (context terlalu panjang, ganti hari, atau perlu fresh session), gunakan folder handoffs/ untuk menyimpan konteks handoff.

Cara Membuat Handoff

Buat file di handoffs/ dengan format nama: YYYY-MM-DD-<topic>.md
- Contoh: handoffs/2026-04-28-offline-mode-phase-4.md
- Gunakan tanggal + topik agar unik dan tidak bentrok dengan handoff lain
Isi file handoff dengan:
- Apa yang sudah dikerjakan — summary pekerjaan yang selesai
- Apa yang belum selesai — task yang tersisa
- Konteks penting — keputusan desain, gotcha, hal yang perlu diingat
- File yang diubah — daftar file yang di-touch
- Next steps — langkah konkret untuk melanjutkan

Di session baru, mulai dengan instruksi:

Lanjutkan pekerjaan dari handoff file: handoffs/2026-04-28-offline-mode-phase-4.md

oia terkadang, ada orang/agent lain yang sedang mengerjakan fitur berbeda, jadi jangan sembarangan untuk meremove atau melakukan hal-hal yang bisa merusak kerjaan orang/agent lain, konfirmasikan terlebih dahulu jika memang butuh hal-hal penting, tapi jika masih scope kamu silahkan lakukan

WAJIB berpikir kritis, detail, mateng, lengkap dan jujur. Setelah selesai per phase, update semua docs terkait lalu commit.


### Aturan

- **Satu file per handoff** — jangan timpa file handoff yang sudah ada
- **Nama harus unik** — gunakan tanggal + topik spesifik
- **Jangan hapus handoff lama** — biarkan sebagai history/referensi
- **Handoff bukan dokumentasi** — ini konteks untuk AI session, bukan docs untuk manusia

handoffs/ ├── 2026-04-28-offline-mode-phase-4.md ├── 2026-05-01-graphql-subscriptions.md └── 2026-05-03-marketplace-mvp.md


## Testing

```bash
cd engine
go test ./... -v          # All engine tests
go test ./pkg/ddd/        # Specific package
go test ./... -count=1    # No cache

cd packages/go-json
go test ./... -v          # All go-json tests
go test ./lang/ -v        # Language engine tests only

Current: 588 Go engine tests + 82 go-json tests + 74 Stencil tests, 0 failures. Build: OK.

Build

cd engine
make build    # Build bitcode binary
make install  # Install bitcode to $GOPATH/bin
make serve    # Start production server
make dev      # Start dev server (auto-detects mode)
make test     # Run tests
make tidy     # go mod tidy

Navigation Menu

Repository navigation

AGENTS.md

AGENTS.md

AGENTS.md — BitCode Platform

Multi Brain (MANDATORY — read before starting work)

Code Search: bit-rag MCP (MANDATORY — use before Grep)

Understanding the Project

Project Overview

Conventions

Tooling: `rtk` Wrapper

File Structure Rules (Engine)

File Structure Rules (Components)

File Structure Rules (go-json)

When Making Changes

Adding a New Feature (Engine)

Adding / Modifying Components

Documentation Updates (MANDATORY)

i18n Check (MANDATORY)

What To Work On Next

Completed ✅

Remaining (Engine)

Offline Mode (In Progress — Phase 1-2 of 5 complete)

Multi-Brain Session Memory (ALWAYS ACTIVE)

Session Handoff

Cara Membuat Handoff

Build

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md — BitCode Platform

Multi Brain (MANDATORY — read before starting work)

Code Search: bit-rag MCP (MANDATORY — use before Grep)

Understanding the Project

Project Overview

Conventions

Tooling: rtk Wrapper

File Structure Rules (Engine)

File Structure Rules (Components)

File Structure Rules (go-json)

When Making Changes

Adding a New Feature (Engine)

Adding / Modifying Components

Documentation Updates (MANDATORY)

i18n Check (MANDATORY)

What To Work On Next

Completed ✅

Remaining (Engine)

Offline Mode (In Progress — Phase 1-2 of 5 complete)

Multi-Brain Session Memory (ALWAYS ACTIVE)

Session Handoff

Cara Membuat Handoff

Build

Tooling: `rtk` Wrapper