Bundled Module Development

This page describes, at a high level, how a module inside EPOS is typically structured. It’s background for understanding how the product is built - it is not a guide for building and installing your own module, because that capability doesn’t exist for third parties. See What is an EPOS Module for why.

Typical anatomy

• Data model - the persisted shape of whatever the module manages (e.g. a promotion, an invoice, a stock adjustment), reviewed and versioned alongside the rest of EPOS’s schema.
• Service layer - the business rules: what’s allowed, what’s validated, what triggers what. This is where scope/permission checks and tenant/store boundaries are enforced, not left to the API layer or the UI to remember.
• Permissions - most internal actions require a specific permission, checked server-side, tied to a staff role (Owner, Manager, Cashier, etc.). This is a separate system from the external API scopes documented elsewhere in this site - internal permissions govern what a logged-in staff member can do in Back Office/POS; external scopes govern what an IntegrationClient can read through /v1. They don’t map onto each other.
• Migrations - schema changes ship as reviewed, versioned migrations, applied as part of a release - never as an ad-hoc change to a running database.
• Audit - actions that matter (creating/changing/deleting something, security-relevant settings changes) are recorded in an internal audit trail as part of normal operation.
• Back Office integration - most modules have a Back Office UI surface for staff to manage whatever the module owns.
• POS integration - some modules also affect what happens at the till (e.g. how a promotion is applied during checkout) - handled through EPOS’s own internal POS logic, not through anything exposed externally.
• Testing - modules are expected to have test coverage appropriate to what they do, reviewed the same way the rest of the codebase is.

What’s intentionally not documented here

Specific deployment commands, server filesystem layout, infrastructure/environment configuration, and any other operational detail about how EPOS itself is built and deployed are internal implementation detail and are out of scope for public developer documentation - this page describes shape, not operations.