Server Actions
Relevant source files
The following files were used as context for generating this wiki page:
Server Actions in DRX CRM serve as the primary mechanism for handling type-safe server-side mutations and data processing within the Next.js 16 framework. They facilitate direct communication between the frontend components and the backend infrastructure, specifically managing operations related to Point of Sale (POS), Inventory Management, and Role-Based Access Control (RBAC).
Sources: README.md:46-48, README.md:143-145
Architectural Overview
The project utilizes Server Actions as a modern alternative to traditional API routes for state mutations. While API routes (under app/api/) are still used for certain programmatic integrations and complex data fetching, Server Actions are integrated into the React component lifecycle to handle user-driven events like form submissions and inventory adjustments.
Data Flow for Mutations
Server Actions interact directly with the Supabase backend, leveraging PostgreSQL and Row Level Security (RLS) to ensure data isolation between different business tenants.
The diagram above illustrates the typical flow of a Server Action from the user interface through the security layers to the database.
Sources: README.md:143-150, app/api/team/route.ts:7-25
Key Functional Areas
Server Actions are categorized by the core modules they support, focusing on maintaining immutable records and enforcing business logic.
1. Inventory and Intake Management
Actions in this module handle the transition of physical goods into the system. This includes recording costs, calculating unit prices (cost-per-gram), and processing manager approvals for unusual cost deviations.
- Intake Recording: Captures product, quantity, and total cost.
- Approval System: Routes intakes to managers if price deviations exceed a 50% threshold.
- Cost History: Maintains an immutable log of cost changes over time.
Sources: README.md:183-188, deploy-inventory-intake.sh:14-23
2. Team and Role Management
The system enforces a strict role hierarchy where higher roles (Owners/Managers) manage lower roles (Supervisors/Cashiers). Server Actions facilitate these changes while validating permissions server-side.
| Role | Permissions |
|---|---|
| Owner | Full access, billing, privacy presets, and staff management. |
| Manager | Inventory management, reporting, and staff management. |
| Supervisor | Voids, discounts, and customer management. |
| Cashier | Sales processing and basic customer entry. |
Sources: README.md:58-60, app/(app)/settings/team/page.tsx:165-188, testsprite_tests/standard_prd.json:20-25
3. POS and Financial Mutations
Server Actions handle the finalization of sales, including fractional quantity calculations and price overrides. These actions are designed to be immutable, ensuring that once a transaction is processed, it generates a permanent audit trail.
This sequence ensures that every financial change is verified and logged.
Sources: testsprite_tests/standard_prd.json:44-50, README.md:145-148
Security and Compliance
Server Actions are the primary enforcement point for several critical security protocols:
Role-Based Access Control (RBAC)
Every action performs a server-side check against the user's role stored in the user_roles table. For example, a handleRoleChange request is validated to ensure the requester has users.manage permissions.
Sources: app/(app)/settings/team/page.tsx:83-95, testsprite_tests/standard_prd.json:80-85
Right to be Forgotten (RTBF)
Specific actions are designated for privacy compliance, allowing for the permanent masking of Personally Identifiable Information (PII) and the removal of tenant roles upon user request.
Sources: CHANGELOG.md:73-75, testsprite_tests/standard_prd.json:115-125
Audit Logging
Sensitive actions—such as voids, inventory adjustments, and price overrides—automatically trigger an entry into the system audit log. These logs are tenant-isolated and support advanced filtering by action type and date.
Sources: testsprite_tests/standard_prd.json:28-32, README.md:65
Integration with API Routes
While Server Actions handle most internal mutations, the project maintains API routes for specific utility functions and administrative tasks.
GET /api/team: Fetches enriched team member data, including auth details from the Supabase Admin client.POST /api/inventory/intake: Handles programmatic intake submissions.GET /api/admin/audit-logs: Provides filtered access to system logs for authorized administrators.
Sources: app/api/team/route.ts:7-12, deploy-inventory-intake.sh:78-85, testsprite_tests/standard_prd.json:88-95
Summary
Server Actions are central to the DRX CRM architecture, providing a type-safe, secure, and performant way to manage business logic. By integrating directly with Supabase RLS and the project's role hierarchy, they ensure that all mutations are authorized, audited, and consistent with the system's privacy-first design.