System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The DRX CRM system is a privacy-first, full-stack Point of Sale (POS) and Customer Relationship Management (CRM) platform designed for small businesses and regulated retail environments. The architecture follows a mobile-first philosophy, prioritizing financial accuracy, immutable audit trails, and role-based accountability. It utilizes a modern web stack to provide multi-business support through a robust multi-tenancy model.
The system is structured as a Next.js 16 application integrated with Supabase for backend services, including a PostgreSQL database, real-time subscriptions, and Row Level Security (RLS). Its architecture ensures data isolation between businesses (tenants) and enforces strict role hierarchies for operational security.
Sources: README.md:1-12, testsprite_tests/standard_prd.json:7-14
Core Tech Stack
The architecture is built on a modular "Wrelik Modular Stack" designed for scalability and type safety.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS, Shadcn/ui |
| Backend | Supabase (PostgreSQL, RLS, Auth, Server Actions) |
| State/Data | Real-time subscriptions, Prisma ORM (migrated from Supabase-js for core handlers) |
| Infrastructure | Vercel (Hosting), Sentry (Monitoring), PostHog (Analytics) |
| Testing | Vitest, Playwright, TestSprite (AI-automated PRD verification) |
Sources: README.md:27-48, CHANGELOG.md:32-48, testsprite_tests/standard_prd.json:42-52
Multi-Tenancy and Data Isolation
The architecture employs a "Tenant Isolation" model where each business is treated as a separate entity. Data isolation is enforced both at the application level via businessId checks and at the database level using PostgreSQL Row Level Security (RLS) policies.
The diagram shows the flow of a user request through authentication and tenant verification to ensure they can only access data belonging to their specific business.
Sources: README.md:89-98, CHANGELOG.md:41-45, testsprite_tests/standard_prd.json:15-18
Role-Based Access Control (RBAC)
The system architecture enforces a strict role hierarchy to control access to sensitive operations such as price overrides, inventory adjustments, and user management.
Permission Hierarchy
- Super Admin: Enterprise administration and system-wide management.
- Owner: Full business access, billing, and high-level privacy settings.
- Manager: Inventory management, staff management, and reporting.
- Supervisor: Sales, discounts, voids, and basic customer management.
- Cashier: Standard POS operations and limited customer viewing.
Key Subsystems
1. Inventory Intake & Cost Tracking
The inventory subsystem uses an approval-based workflow for tracking costs. It includes logic for calculating "cost per gram" or "cost per unit" automatically during the intake process.
- Audit Logic: All adjustments require a reason code (e.g., "Damaged", "Transfer") to maintain the audit trail.
- Approval Gate: Managers must approve intakes if the cost deviates significantly (e.g., >50%) from the calculated average cost.
Sources: test-inventory-intake.sh:75-105, deploy-inventory-intake.sh:77-85, app/(app)/help/page.tsx:75-85
2. Audit and Compliance System
A critical component of the architecture is the immutable audit trail. The system captures all sensitive actions including:
- Price overrides and voids.
- Permissions modifications.
- Inventory adjustments.
- Right to be Forgotten (RTBF) requests for PII masking.
Sources: testsprite_tests/standard_prd.json:20-27, app/(app)/admin/page.tsx:43-55
3. Help Center Synchronization
The system includes a decoupled synchronization script (sync-help-center.ts) that maps internal documentation to the Featurebase platform. This allows for automated updates of the customer-facing help center based on localized TypeScript data structures.
Sources: scripts/sync-help-center.ts:1-25, scripts/help-center-data.ts:1-15
Database Schema Overview
The architecture relies on several core tables within the PostgreSQL schema to maintain state and relationship integrity.
| Table Name | Description |
|---|---|
business_profile | Stores core business metadata, settings, and logos. |
user_roles | Manages the mapping between users and their tenant-specific roles. |
inventory | The product catalog containing unit measurements and quantities. |
inventory_intakes | Records of incoming stock with cost tracking. |
sales | Immutable transaction records for all POS activity. |
system_audit_log | Centralized, append-only log of all administrative and sensitive actions. |
Sources: README.md:89-98, app/(app)/admin/page.tsx:48-60, deploy-inventory-intake.sh:25-35
Versioning Policy
DRX follows a strict versioning protocol where a VERSION file at the root serves as the single source of truth. The system uses a specialized script (scripts/version.ts) to:
- Analyze
CHANGELOG.mdfor [Unreleased] changes. - Suggest Major, Minor, or Patch bumps based on the content (e.g., Breaking changes = Major).
- Synchronize version strings across the UI components (Sidebar, Admin Console, Footer).
Sources: scripts/version.ts:1-60, CHANGELOG.md:52-58
Conclusion
The DRX CRM system architecture is designed to provide a secure, auditable, and performant environment for retail operations. By combining a modern React-based frontend with a hardened PostgreSQL/Supabase backend, the system achieves strict multi-tenant isolation and role-based security. The inclusion of automated testing, immutable audit logs, and structured version management ensures long-term maintainability and compliance with privacy standards.