🇬🇧 English (default) · 🇮🇩 Bahasa Indonesia (sumber)

AWCMS — Online-First ERP & Business Solutions Template (AWCMS-family superset)

AWCMS is the AWCMS-family ERP/back-office template — used DIRECTLY, developed from the awcms-mini technical base. Its operating mode is hybrid online + offline with an online-first priority (online is the primary path; offline/LAN is the resilience mode), and it is ERP-ready and built for integrated SaaS. It is the family's superset template: it absorbs the full website/e-commerce module cluster, UI/UX, and auth hardening of awcms-micro on top of the awcms-mini foundation and ERP scope (ADR-0035, refining ADR-0034). By contrast, awcms-mini stays hybrid offline-first (SaaS-ready) and awcms-micro stays the lean full-online website-only template. The base provides reusable foundation modules + neutral ERP-readiness contracts (ADR-0020); domain modules — ERP and website/content alike — are added directly in src/modules/, not a separate derived repo. Absorption map: docs/awcms/absorb-awcms-micro-roadmap.md. See also docs/awcms/erp-extension-contracts.md.

Status: foundation actively developed. Legacy code files in this repo have already been removed (see commit chore(foundation): remove legacy repository files) and this repo has been rebuilt from scratch on a modular-monolith technical standard (Bun + Astro 7 + PostgreSQL/RLS). Twenty modules are already live (the authoritative list is the registry in src/modules/index.ts; see docs/ARCHITECTURE.md for the current code state) — ten foundation modules plus ten website/content modules (theming, media-library, blog-content, tenant-domain, visitor-analytics, data-lifecycle, seo-distribution, form-drafts, site-search, comments) — as a foundation for ERP, SaaS, and website/e-commerce development — not just a generic CMS/base, and not a finished ERP either.

Table of contents

• Why this repo was rebuilt
• Direction: awcms-mini technology base, ERP-foundation scope
• High-level architecture
• Hybrid online-first principle
• Stack
• Core principles
• Document package
• For contributors
• Implementation status
• Security
• Governance & community
• Versioning
• License

Why this repo was rebuilt

The old version of AWCMS was built on a combination of Node.js, Vite/React (admin & public), and Supabase. Throughout the migration cycle (ADR-013 through ADR-023), every component was moved in stages to a new runtime and architecture:

• chore(mcp): migrasi awcms-mcp ke runtime Bun (ADR-019, #113)
• chore(public): migrasi awcms-public ke Bun (ADR-019, #113)
• chore(admin): migrasi awcms admin (Vite/React) ke Bun (ADR-019, #113)
• docs: referensi keputusan arsitektur kanonik (ADR-013…023 per produk)
• docs(readme): add architecture update note (PostgreSQL-only, RLS wajib, EmDash optional)
• docs: inventaris pemakaian Supabase (audit off-Supabase, #108)

Once every component (mcp, public, admin) had finished moving and Supabase was no longer used, the legacy files in this repo were removed (chore(foundation): remove legacy repository files) — not to retire the repo, but to clear the ground so AWCMS could be rebuilt on the new standard foundation, with a much broader business scope than before.

Direction: awcms-mini technology base, ERP-foundation scope

This repo adopts the stack and technical standard from awcms-mini — AhliWeb's modular monolith standard — as its technology base, then develops it toward ERP scope and absorbs awcms-micro's website/e-commerce cluster. The three family repos (awcms-mini, awcms, awcms-micro) are three sibling templates used directly (ADR-0034), not a base-and-derivative hierarchy; awcms is the ERP/back-office lineage template, now positioned as online-first hybrid, ERP + integrated-SaaS ready, and the family superset (ADR-0035). This repo's focus is providing the foundation + ERP-readiness contracts + a complete website/e-commerce capability set (absorbed from awcms-micro, see docs/awcms/absorb-awcms-micro-roadmap.md), and ERP domain modules are added directly in src/modules/ when the template is used:

• Reusable foundation modules — tenant, identity/access (RBAC/ABAC/RLS), central profile, sync/outbox, workflow, reporting, observability, etc. — used as-is by the domain modules built on top of them.
• Neutral ERP-readiness contracts — passive data shapes, capability ports, and event payload schemas (business transaction, posting, period-lock, item/currency/UoM, inventory movement, reporting projection — ADR-0020) that are implemented/consumed by ERP modules added directly in src/modules/ (or by other family templates), not given their logic by the base itself.
• Business-integration framework — the same offline-first-safe outbox/queue pattern + provider adapters (e.g. payment gateways, marketplaces, tax/Coretax, logistics) as the mounting point for domain connectors built on top of this template.
• Multi-tenant/multi-entity scale — RBAC/ABAC/RLS + tenant/legal-entity/organization-unit boundaries (ADR-0013) reused across domain modules.

Actual ERP domain modules (finance/GL, inventory/warehouse, procurement, manufacturing, HR/payroll) and business verticals (POS, school portal, etc.) are added directly in this template's src/modules/ when it is used (ADR-0034) — not in a separate derived repo. (The former docs/awcms/derived-application-guide.md guide is now DEPRECATED.)

Technology base adopted from awcms-mini:

Aspect	Before (old repo)	Now (awcms-mini base)
Runtime	Node.js	Bun (Bun-only, see ADR-0002)
Web framework	Vite + React (separate admin/public)	Astro 7 (SSR on Bun, single modular-monolith shell)
Database	Supabase (managed Postgres)	PostgreSQL with mandatory RLS (ADR-0003)
Architecture	Separate apps (mcp, public, admin)	Modular monolith, microservice-ready (ADR-0001), reusable base modules (Tenant, Identity, Profile, Access/RBAC-ABAC, Sync, Workflow, Reporting)
Operating mode	Online-dependent	Hybrid online-first (online is the primary path; offline/LAN is the resilience mode with HMAC-signed sync outbox, ADR-0006)
API contract	Ad-hoc	Validated OpenAPI/AsyncAPI, standard response helper

Reusable base modules (Tenant, Identity, Profile, Access/RBAC-ABAC, Sync, Workflow, Reporting) from awcms-mini are used as-is as the foundation; ERP domain modules and business integrations are developed directly on top of that foundation, in this template's src/modules/ — not in a separate derived repo (ADR-0034, superseding ADR-0022).

High-level architecture

flowchart TB
  subgraph Client["Client / LAN"]
    ADM[Admin SSR]
    APP[ERP domain modules<br/>in src/modules/]
  end

  subgraph App["AWCMS — Bun + Astro 7 (Modular Monolith)"]
    API[REST API /api/v1<br/>OpenAPI]
    MW[Middleware:<br/>Auth · Tenant · ABAC · Module-enabled · Audit]
    MOD[Foundation modules:<br/>Tenant · Identity/Access · Profile ·<br/>Sync · Workflow · Reporting · Email ·<br/>Module Mgmt · Domain Events · Logging]
    EVT[Domain events<br/>AsyncAPI]
  end

  subgraph Data["Data & Storage"]
    PG[(PostgreSQL<br/>RLS FORCE + Audit)]
  end

  subgraph Ext["ERP-readiness contracts (passive, ADR-0020)"]
    ERP[ERP modules<br/>in src/modules/, ADR-0034]
    PROV[External business provider<br/>tax/Coretax, payment, etc.]
  end

  ADM --> API
  APP --> API
  API --> MW --> MOD
  MOD --> PG
  MOD --> EVT
  MOD -. outbox/queue .-> PROV
  EVT -. consumes contract .-> ERP

Loading

These foundation modules do not implement ERP logic — they only provide neutral contracts (events, posting request/result, period-lock, etc.) that are consumed by ERP modules added directly in src/modules/. External business providers connect via outbox/queue, not a direct transaction path, so critical flows keep running when an external connection has issues (ADR-0006).

Hybrid online-first principle

awcms's operating mode is hybrid online + offline with an online-first priority: online connectivity is the primary path and deployment default (synced multi-branch, public portals, provider integrations). Offline/LAN capabilities (HMAC outbox/sync, ADR-0006) remain present and supported as a resilience mode when connectivity drops — not the primary assumption like awcms-mini, which is offline-first. Data flow stays idempotent and safe to reconcile when back online:

flowchart LR
  Tx[Operational action] -->|"online (primary)"| Server[(Central server / SaaS)]
  Tx -.->|when offline/LAN| Local[(Local / LAN DB)]
  Local --> Outbox[Outbox event + object queue]
  Outbox -->|when back online| Sync[Sync push/pull<br/>HMAC signed]
  Sync --> Server
  Server -->|conflict| Manual[Manual resolution + audit]
  Server -.-> Deliver[Send to external provider]

Loading

Stack

• Runtime: Bun (ADR-0002 — Bun-only; Node.js only via a written, maintainer-approved exception)
• Web framework: Astro 7 (SSR on Bun, @astrojs/node as adapter)
• Database: PostgreSQL with RLS FORCE (ADR-0003)
• Architecture: Modular monolith, microservice-ready (ADR-0001)
• Operating mode: Hybrid online-first — online is the primary path; offline/LAN is the resilience mode, optional sync outbox (ADR-0006)
• Security baseline: RBAC + ABAC default-deny + PostgreSQL RLS + Audit Log (ADR-0004)
• Contracts: OpenAPI + AsyncAPI, versioned independently from the package release (ADR-0007, ADR-0008)
• Family model: direct-use templates, domain modules in src/modules/ (ADR-0034, superseding the derived pathway of ADR-0013/0022); awcms = online-first hybrid & superset absorbing awcms-micro (ADR-0035); tenant/entity boundaries & service-extraction criteria remain from ADR-0013

Core principles

1. Foundation modules are reusable as-is by every domain module built on top — not rewritten per use.
2. ERP-readiness contracts are passive and neutral (data shapes, capability ports, event schemas) — actual ERP business logic does not live in this base (ADR-0020).
3. Multi-tenancy requires tenant_id, RLS FORCE, tenant context, and default-deny ABAC on every tenant-scoped table/endpoint.
4. External business providers (tax, payment, logistics, etc.) must not become a critical-path dependency and must never be called inside a DB transaction — always via outbox/queue.
5. Sensitive data (passwords, session tokens, personal/business identifiers) must be hashed/masked/redacted — never stored/logged raw.
6. Deletable master/config data uses soft delete; default lists hide deleted_at, restore requires permission and is audited (ADR-0005).
7. Documentation, migrations, API/event contracts, tests, and agent skills follow the real implementation — not the other way around.
8. Backend is Bun-only; Node.js exceptions only with maintainer approval + documented note.

Document package

The master document package lives in docs/awcms/ — adapted from the docs/awcms-mini/ package in the awcms-mini repo, tailored to a broader ERP-foundation scope:

flowchart LR
  A[01 Canvas Induk] --> B[02 PRD]
  B --> C[03 SRS]
  C --> D[04 ERD]
  D --> E[05 OpenAPI/AsyncAPI]
  E --> F[06 Issues]
  F --> G[07 Sprint/Test]
  G --> H[08 SOP]
  H --> I[09 Roadmap Repo]
  I --> J[10 Coding Standard]
  J --> K[11 Blueprint]
  K --> L[12 Generator Prompt]
  L --> M[13 Traceability]
  M --> N([Ready for Coding])
  D --> TD[16 Backend & DB]
  E --> TD
  E --> UX[14 UI/UX] --> FE[15 Frontend]
  TD --> N
  FE --> N
  T17[17 Seed/RBAC/ABAC] --> N
  T18[18 Config/Env] --> N
  T21[21 Module Admission] --> N
  SEC[20 Threat Model] -. gates .-> N

Loading

• 01–13 planning → contract → execution; 14–18 technical design; 19 glossary; 20 threat model & security architecture; 21 module admission governance.
• Important note: many documents in this package use ERP/retail domain examples as illustration — the pattern is reusable, the entities/endpoints/screens are examples that domain modules in src/modules/ swap or extend for their own domain needs. See docs/awcms/README.md for translation status and other important notes.
• Architectural decisions are recorded in docs/adr/ (40 ADRs currently).
• Current code state (not a plan): docs/ARCHITECTURE.md.

For contributors

1. Read AGENTS.md — technical work contract, mandatory rules, security guardrails.
2. Read CONTRIBUTING.md — contribution flow, setup, commit conventions, Definition of Done.
3. Use the project skills in .claude/skills/ so standards are applied consistently (one skill per topic: migration, endpoint, ABAC guard, audit log, testing, etc.).
4. Work atomically per issue; add a migration when the schema changes, OpenAPI when the API changes, AsyncAPI when an event changes.
5. Validate (bun run check — the main CI gate; the full sub-check chain and its order are documented in CONTRIBUTING.md and package.json's check script — not duplicated here to avoid drift) before opening a PR. For non-trivial UI changes, add/run a real browser E2E separately — bun run test:e2e (Playwright + Bun), needs a live app + DATABASE_URL.

Implementation status

Twenty modules are live in code — the authoritative list is the registry in src/modules/index.ts, with per-module detail in docs/ARCHITECTURE.md and each module's own README at src/modules/*/README.md. Foundation: logging (audit trail), tenant-admin, profile-identity, identity-access (login, sessions, RBAC/ABAC, MFA/OIDC/SSO, business-scope, SoD, admin write CRUD — Issue #166/#171), module-management (per-tenant enable/disable, enforced on every request), domain-event-runtime (cross-module event publisher), sync-storage (HMAC-signed outbox/inbox, conflict resolution, R2 object queue), workflow-approval, email (dispatch + templates), reporting (projections + export). Website/content: theming, media-library, blog-content (absorbed news-portal — ADR-0044), tenant-domain, visitor-analytics, data-lifecycle, seo-distribution, form-drafts, site-search, comments. The admin SSR shell (/admin/*) provides read + write (create/edit/soft-delete/restore) screens across all of the above. The rest of awcms-micro's website/e-commerce capabilities are being absorbed incrementally — see docs/awcms/absorb-awcms-micro-roadmap.md.

Full change history is in CHANGELOG.md; current issue/PR status is on GitHub Issues (work is tracked directly as GitHub issues, not a static backlog).

Security

• Vulnerability reporting policy: SECURITY.md (use private vulnerability reporting — not a public issue).
• Threat model & security architecture: docs/awcms/20_threat_model_security_architecture.md.
• Automation: Dependabot, CodeQL, GitHub secret scanning + push protection, GitGuardian, CI hygiene (Bun-only + no-secret).

Governance & community

Document	Contents
CONTRIBUTING.md	How to contribute
CODE_OF_CONDUCT.md	Community behavior standards
GOVERNANCE.md	Roles, decision-making, releases
SUPPORT.md	Help channels
SECURITY.md	Security policy
docs/adr/	Architecture Decision Records

Versioning

Semantic Versioning + Changesets; full history in CHANGELOG.md. Every PR that changes behavior must include a changeset (enforced by bun run changesets:policy:check in CI). Current release version is 6.1.0.

Version numbering policy (important, read before comparing versions):

• The package release version (package.json, this README) uses a deliberate legacy major-number line — jumping directly from 0.2.0 to 5.0.0 per maintainer decision, NOT a tool-computed SemVer increment, so version comparisons across the rebuild never look like a downgrade from the last legacy tag (v4.6.0). 5.0.0 and above are NOT backward-compatible with any legacy v2.x–v4.x release — the entire codebase was rewritten from scratch on a new foundation. See ADR-0024.
• Contract version (info.version in OpenAPI/AsyncAPI) and module descriptor version/status (src/modules/*/module.ts) follow their own independent SemVer policy, not mechanically tied to the package release version. See ADR-0008.

License

Licensed under the MIT license — see LICENSE. Latest development-standard audit: docs/awcms/AUDIT_STANDAR_PENGEMBANGAN_2026-07-04.md.