🇬🇧 English (source) · 🇮🇩 Bahasa Indonesia

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 (ADR-0035, refining ADR-0034). The family today is two repos: this one, and ahliweb/awcms-astro, which carries public pages + a USER admin surface (ADR-0070); awcms-mini and awcms-micro are ARCHIVES, discontinued (ADR-0055). 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 (now a historical note — the port path was closed by ADR-0055): 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-one 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, ten website/content modules (theming, media-library, blog-content, tenant-domain, visitor-analytics, data-lifecycle, seo-distribution, form-drafts, site-search, comments), plus idn-admin-regions (Indonesian administrative-region master data, ADR-0046) — as a foundation for ERP, SaaS, and website/e-commerce development — not just a generic CMS/base, and not a finished ERP either.

• 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

In short: the old repo ran on Node.js + Vite/React + Supabase, and every component was moved in stages to a new runtime and architecture (ADR-013…023) before the legacy files were removed — not to retire the repo, but to clear the ground.

The full account, including the migration commit list and the before/after technology-base table, is in docs/awcms/sejarah-repo.md. It moved there because a README should answer "what is this, now" — and history piling up at the front slowly buries that answer.

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; awcms-micro's website/e-commerce cluster has been absorbed as far as it landed, and the rest is built here under its own admission ADR (ADR-0055 §1). The family under development today is two repos, and only two (ADR-0055): this repo as the system of record, and ahliweb/awcms-astro as public pages + a USER admin surface (ADR-0070) — the pair that replaces all three of the old templates at once. awcms-mini and awcms-micro are archives; the "three sibling templates" position (ADR-0034) no longer holds, and what remains of it is the removal of the derived-repo pathway; 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 (partly originating in awcms-micro as provenance; docs/awcms/absorb-awcms-micro-roadmap.md reads as a list of needs, not a port queue), 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.)

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).

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

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).

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]

• 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: two repos — awcms (system of record, every SYSTEM admin screen) + awcms-astro (public pages + USER admin when declared) (ADR-0055, ADR-0070); direct-use templates, domain modules in src/modules/ (ADR-0034, superseding the derived pathway of ADR-0013/0022); awcms = online-first hybrid & superset (ADR-0035); tenant/entity boundaries & service-extraction criteria remain from ADR-0013

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.

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

• 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/ (0000–0070 currently; 0000 is the template).
• Current code state (not a plan): docs/ARCHITECTURE.md.

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.

Twenty-one 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. System: idn-admin-regions (versioned Indonesian administrative-region master data — ADR-0046). The admin SSR shell (/admin/*) provides read + write (create/edit/soft-delete/restore) screens across all of the above. Website/e-commerce capabilities that do not exist yet are built here under their own admission ADR, not ported from an archive repo (ADR-0055); docs/awcms/absorb-awcms-micro-roadmap.md now reads as a list of needs, not a port queue.

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).

• 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).

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.4.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.

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