System Capabilities

EZY Portal System Capabilities (Public-Safe)

This file is the canonical source for shared, cross-module capabilities in EZY Portal.

Use this file when documenting common behavior so we do not duplicate the same technical topics in every module.

Scope

This document is public-facing and tenant-oriented.

Include only high-level capability information:

role and scope-based visibility
tenant isolation and governance
archive/trash/restore lifecycle behavior
bulk operations at a concept level
search/index freshness behavior
cross-module consistency and integration behavior

Do not include sensitive implementation detail:

API routes, HTTP methods, or payload contracts
internal service names, middleware names, or file paths
hidden/admin/internal endpoint inventories
infrastructure internals that increase attack surface

Authoring Rules

Keep this file as the single source of truth for shared capabilities.
Module documentation should link here and only describe module-specific behavior.
When adding a new module, add a module summary that references this file instead of duplicating shared topics.

Permission Model

EZY Portal uses a unified permission model that is consistent across every module.

Each capability area declares a stable permission key (for example a sales-orders area, an employees area, a deals area). Within each key, access is granted at one of three levels: Read, Write, or Admin.
Read is required to list and view records, Write is required to create or modify them, and Admin is reserved for sensitive actions such as cancel, delete, or configuration changes.
Some capabilities declare a dependency chain: granting a sub-capability requires a minimum level on its parent capability, so users cannot be granted a derived ability without the underlying access.
Most modules also distinguish between internal users (people inside the tenant) and external accounts (portal-invited collaborators); operational screens and write actions are limited to internal users.
Region/scope-based access (where a user’s region or assignment determines which records they can see) layers on top of permission levels. Reads are filtered, writes are blocked when out of scope, and a “soft” mode is available that warns instead of blocks for migration scenarios.

Optimistic Concurrency

All editable business documents use an optimistic-concurrency contract to keep concurrent edits safe.

Every record carries a version number that increments on each successful change.
Update and workflow requests must include the version the client started from. If the stored version has moved on, the request is rejected with a conflict response and no change is applied.
The user is expected to reload the latest record, review what changed, and retry. This prevents one user’s edit from silently overwriting another’s.

Event-Driven Consistency

Modules communicate through a resilient event pipeline so that downstream consumers (search, audit, denormalized caches, other modules) remain consistent even during transient outages.

Outbound events are published through a resilient publisher: under healthy conditions events are delivered directly, and during a broker outage they are written to a per-service outbox and replayed by a background recovery worker. No domain change is lost because of a temporary messaging failure.
Inbound events are processed through an inbox that records each delivery by an idempotency key, so duplicate deliveries are detected and processed exactly once. Failed handlers are retried with back-off rather than dropped.
Together, the outbox and inbox give cross-module workflows at-least-once delivery with deduplication, which is what enables features like “post a document and have its effects appear in other modules within seconds.”

Idempotent Writes

Create and workflow endpoints accept an idempotency key so that retries (network glitches, double-clicks, automated re-tries) are safe.

A request that repeats the same idempotency key returns the original outcome instead of producing a duplicate record.
Internally generated keys (for example a deterministic key for a workflow transition) ensure that automation and integrations can re-drive operations without creating duplicates.

Audit Trail

Every module emits structured audit events for create, update, delete, and workflow transitions on the entities that matter.

Each audit entry captures the actor, the tenant context, what changed (before/after where applicable), and when the change happened.
Audit events flow through the same resilient pipeline as other domain events, so audit history is durable even if downstream consumers are temporarily unavailable.
Tenants can rely on a complete record of who did what across modules, with consistent shape so audit search and exports work uniformly.

Entity Reference Integrity

When a record in one module references master data owned by another module (for example a commerce document referencing a business partner, a price list, an item, or a warehouse), the platform tracks that reference so master data cannot silently disappear from under live records.

When a referencing record is created or updated, references are registered with the owning module.
When a referencing record is cancelled or deleted, references are released.
Deleting master data that is still referenced is blocked with a clear error indicating that the record is in use. Users must first remove or reassign the referencing records.

This applies across modules and is what makes cross-module deletes safe.

Document Linking and Cross-Module Flow

Many tenant workflows span modules — a quote becomes an order, an order becomes a delivery, a delivery becomes an invoice, an invoice generates a receipt — and the platform tracks these relationships consistently.

Each link records source and target documents, the line-level mapping, and an open-quantity that decrements as fulfillment progresses.
“Cancel” on an upstream document propagates to its downstream links and reverses the related effects (for example reversing fulfillment or releasing a credit) in a fail-closed way: if the reversal cannot complete, the cancel does not silently succeed.
This is the foundation for “copy-from” flows, partial fulfillment tracking, and the cancel-guard that prevents cancelling an upstream document when active downstream documents still depend on it.

Document Numbering and Fiscal Periods

Business documents (invoices, orders, receipts, transfers, employee numbers, etc.) get their numbers from a centralized per-tenant numbering service.

Each document type has its own series, allocated per tenant and aware of the fiscal calendar.
Number allocation is idempotent — a retried allocation does not consume an extra number.
“Copy-from” flows allocate fresh numbers for the new document rather than reusing a source number.

Documents with a date are validated against the tenant’s fiscal calendar before they are saved or transitioned.

A closed or locked period blocks both draft and posted writes whose date falls inside it.
Programmatic actors (managed tenants, tenant API keys) get a more permissive variant that checks period existence rather than its open/closed status, so back-office automation and migrations can proceed under controlled conditions.

Custom Fields

Every document and master-data entity supports tenant-defined custom fields without code changes.

Tenants can add custom fields to entities they own; values are stored alongside the record.
Custom-field definitions are cached for performance and refreshed across all service instances when changed, so updates are visible to every user without restart.
Custom fields participate in the same import/export, audit, and visibility rules as built-in fields.

Read-Side Privacy and Masking

Sensitive fields (pricing, personally identifiable information) are masked on the read path based on the viewer’s scope.

When a viewer’s scope does not include a particular price list, region, or PII tier, the affected fields are hidden in API responses rather than returned in raw form.
Masking is fail-closed: if the access-control service cannot be reached or returns an error, the platform masks the data rather than exposing it. This means a temporary access-control outage degrades visibility, never confidentiality.

Bulk Operations

Bulk create, update, and transition operations are available for high-volume integrations.

Bulk endpoints are reserved for programmatic tenant access (tenant API keys), not interactive portal users. This keeps the interactive UI predictable and pushes mass changes through an auditable, rate-controlled path.
Bulk operations honor the same validation, audit, entity-reference, and lifecycle rules as single-record operations.

Archive, Trash, and Restore Lifecycle

Records that are no longer active follow a consistent lifecycle.

Archive removes a record from default lists while keeping it accessible and reversible.
Trash (soft delete) is reserved for stronger removal; trashed records are excluded from normal queries.
Restore is available from trash. Browsing the trash and restoring records is gated to elevated roles (typically system administrators) so accidental destruction can always be recovered, but only by the right people.
Workflows that depend on a parent record (tasks under a project, lines under a document) become read-only when the parent enters a terminal, archived, or deleted state, preventing edits that would otherwise create orphaned data.

Document Duplication

Most document types support a one-click duplication that clones the header and lines into a fresh draft, with new numbering and a clean audit trail. This is intended for templating common documents without copying state-machine history.

Cross-Module Reference Validation

When a record refers to an item, partner, or other master record, the reference is validated at create and update time.

Inactive or missing master records are rejected with a clear validation error before the document is saved.
This prevents silently-broken references from accumulating across modules.

PDF Export

Document types that support printing expose a PDF export. When the print service is not configured for a tenant, the platform returns a clean “not available” response rather than failing in an opaque way, so UI surfaces can hide or disable the action gracefully.

Search Index Freshness

Searchable entities publish change events to the platform search pipeline on every create, update, and delete.

Search results catch up to changes within seconds under normal conditions.
Per-tenant reindex is available for recovery scenarios (after a bulk import, schema change, or migration) and runs without taking the module offline.

Service Reliability

Backend services warm critical query plans and connection pools at startup so that the first request after a deploy or restart does not pay a cold-start penalty. This is an internal reliability behavior with one user-visible effect: there is no warm-up period during which the UI feels sluggish after a deployment.

Module References

open-documentations/bp/README.md
open-documentations/items/README.md
open-documentations/pricing-tax/README.md
open-documentations/prospects/README.md
open-documentations/projects/README.md
open-documentations/commerce/README.md
open-documentations/communications/README.md
open-documentations/crm/README.md
open-documentations/finance/README.md
open-documentations/hr/README.md
open-documentations/inventory/README.md