# Rails ERP v3.2.1 Overview and Evidence Pack Date: 2026-08-23 Status: Working high-level product, architecture, security, and delivery evidence document Audience: Product owners, technical reviewers, implementation partners, auditors, and UAT stakeholders ## 1. Module Catalogue and Functional Specifications Rails ERP is a multi-tenant enterprise resource planning platform covering identity, customer relationship management, commerce, operations, finance, HR, analytics, and administration. The frontend is a React application and the backend is a modular PHP API with PostgreSQL persistence. | Module | Functional scope | Current functional specification | | --- | --- | --- | | Identity and Access Management | Login, signup, tenant onboarding, session handling, users, roles, permissions, activity logs, status workflows, password workflows, profile, account password change | Tenant-aware authenticated access; RBAC-backed menu and route guards; user/role/security pages API-backed; session expiry handling improved | | Settings | Tenant branding, localization, numbering, approvals, inventory defaults, financial periods, payment terms, notification settings, integration settings, API settings, subscription, preferences | Tenant-scoped settings backend added; record-backed tabs and file upload support hardened; remaining work is full module-specific settings breadth and formal UAT | | Contacts | Contacts, categories, activity history, import/export | Live contact categories and activity pages wired; category usage in add/edit contact flows aligned | | Customers | Customer creation, customer register, customer drawer, credit fields, payment terms, industry, Customer 360 entry point | Live customer register with add/edit/view/status/remove; tenant currency support; relationship visibility added | | CRM Leads | Lead sources, lead statuses, lead creation, optional assignment, assignment workbench, lead scoring, conversion, analytics | Lead source/status management added; lead assignment and analytics hardened; lead can be added unassigned; qualified lead conversion flow added | | Opportunities | Opportunity stages, opportunity creation, source dropdown, analytics | Stage/source dropdowns and opportunity analytics added; still needs final end-to-end sales opportunity UAT | | Relationships | Relationship types, record relationships, custom business records | HubSpot-style relationship model implemented under "Relationships"; custom records implemented as "Custom Business Records"; visible in Customer 360 and customer drawer | | Customer 360 | Timeline, engagement, insights, purchases, support, financials | Timeline and engagement cleaned; relationships/custom records visible; insights will be delegated to Cutecat AI Insight service | | Sales | Sales orders, quotations, returns, forecasts, credit | Frontend pages exist; backend schema alignment exists; not yet fully page-by-page hardened | | Purchases | Purchase orders, approvals, inbound receiving, shortlanded, overages, returns, supplier performance | Frontend pages and schema alignment exist; not yet fully page-by-page hardened | | Suppliers | Supplier onboarding, supplier profiles, status, returns, price history, analytics | Frontend pages and schema alignment exist; not yet fully page-by-page hardened | | Inventory | Items, categories, subcategories, brands, stock levels, counts, transfers, scrap, reorder rules, variance | Frontend pages and schema alignment exist; not yet fully page-by-page hardened | | Warehouse | Warehouses, locations, bins, inbound, outbound, transfers, reconciliation, analytics | Frontend pages and schema alignment exist; not yet fully page-by-page hardened | | POS | Shops, stock assignment, terminal, transactions, returns, sessions, reports | Frontend pages exist; backend production wiring not fully verified | | HR and Payroll | Employee directory, profiles, positions, departments, payroll, attendance, leave, recruitment, onboarding, statutory, performance, self-service, analytics | Broad frontend catalogue exists; full backend/API hardening pending | | Assets Management | Asset register, categories, locations, allocations, status, transfers, depreciation, maintenance, audit, compliance | Frontend pages and schema alignment exist; full backend/API hardening pending | | Accounting and Finance | Chart of accounts, journals, invoicing, expenses, receivables, payables, trial balance, P&L, balance sheet, cash flow, tax reports | Frontend pages and schema alignment exist; full backend/API hardening pending | | Approvals | Approval queues, audit trail, module approvals, escalations | Frontend pages exist; workflow hardening pending | | Automation | Rules, builder, triggers, scheduled automations, execution logs, actions | Frontend pages exist; backend workflow hardening pending | | Marketing | Campaigns, automation, audiences, lead nurturing, A/B testing, landing pages, analytics | Frontend pages exist; likely roadmap/prototype until backend scope is validated | | Reports and Data | Standard reports, report builder, data warehouse, datasets, pipelines, exports | Frontend pages exist; analytics/data service strategy pending | | AI Insights | Dashboards and module AI insight views | To be backed by Cutecat, a Python/FastAPI AI agent with module-specific endpoints and subscription gates | | Integrations | Merchant hub, integration pages, API keys, webhooks, notification channels | Backend settings and integration tables partly added; production connectors pending | | Help and Support | Help center, knowledge base, tickets, support history | Frontend pages exist; backend hardening pending | ## 2. Module Maturity Matrix Maturity definitions: - Production-ready: complete API-backed workflow, RBAC, tenant scoping, validation, error handling, test evidence, security evidence, and operational evidence. - Beta: real backend/API wiring exists and main workflows pass, but formal evidence or edge-case coverage remains. - Prototype: UI and some backend/schema exist, but page-by-page hardening is incomplete. - Demo-only: suitable for visual demonstration only; contains mock/local data or incomplete actions. - Roadmap: planned capability with limited or no implementation. | Module | Maturity | Reason | | --- | --- | --- | | IAM | Beta | Functional QA passed, but formal VAPT, load test, automated regression pack, and CI evidence are not yet complete | | Settings | Beta | Most settings passed; module-specific settings breadth and full regression evidence still needed | | Contacts | Beta | Live categories/activity and add/edit alignment improved; import/export needs final evidence | | Customers | Beta | Customer workflows are live; relationship integration now underway | | CRM Leads | Beta | Live lead setup, assignment, analytics, optional assignment, and conversion work completed; final cross-flow UAT pending | | Opportunities | Beta | Live stage/source and analytics work completed; final sales lifecycle UAT pending | | Relationships and Custom Business Records | Beta | Database/API/frontend foundation implemented; contextual creation still being expanded across pages | | Customer 360 | Beta | Timeline and relationship visibility exist; AI insights integration and all tabs need final hardening | | Sales | Prototype | Schema and pages exist; not yet fully hardened page-by-page | | Purchases | Prototype | Schema and pages exist; not yet fully hardened page-by-page | | Suppliers | Prototype | Schema and pages exist; not yet fully hardened page-by-page | | Inventory | Prototype | Schema and pages exist; not yet fully hardened page-by-page | | Warehouse | Prototype | Schema and pages exist; not yet fully hardened page-by-page | | POS | Prototype | Pages exist; full backend/API evidence pending | | HR and Payroll | Prototype | Very broad frontend coverage; backend workflow hardening pending | | Assets Management | Prototype | Pages and schema alignment exist; workflow hardening pending | | Accounting and Finance | Prototype | Pages and schema alignment exist; workflow hardening pending | | Approvals | Prototype | Pages exist; workflow engine evidence pending | | Automation | Demo-only | Builder/pages exist; production execution semantics not yet verified | | Marketing | Demo-only | Pages exist; backend production wiring not verified | | Reports and Data | Prototype | Pages exist; data warehouse/report execution evidence pending | | AI Insights | Roadmap | Cutecat integration strategy agreed; production implementation pending | | Integrations | Prototype | Settings/API/webhook scaffolding exists; external connector evidence pending | | Help and Support | Demo-only | Pages exist; production helpdesk backend evidence pending | ## 3. Version History and Release Notes for v3.2.1 ### Version 3.2.1 - CRM, IAM, Settings, and Relationship Foundation Hardening Release date: 2026-08-23 Release type: Hardening/beta milestone Key changes: - Rebuilt public auth page with live login and tenant signup. - Added tenant onboarding for new business accounts with 14-day trial flow assumptions. - Hardened authenticated route guard, session expiry behavior, RBAC navigation filtering, and tenant context. - Replaced mock IAM pages with API-backed user, role, permission, security, status, activity, and password workflows. - Added user profile and account password change capabilities. - Removed backend project branding from user-facing UI. - Added tenant settings backend/API coverage for branding, localization, numbering, approvals, inventory defaults, financial periods, payment terms, notifications, integrations, API keys, subscription, and preferences. - Improved settings save behavior and tenant-scoped persistence. - Hardened contacts, contact categories, contact activity history, and category usage across add/edit contact flows. - Hardened customers, customer add/edit/view/status/remove, tenant currency display, customer drawer, and Customer 360 entry points. - Added Salesforce-aligned lead statuses, opportunity stages, lead source/stage setup pages, optional lead assignment, lead assignment workbench, lead scoring, conversion, pipeline, and analytics improvements. - Added opportunity analytics and source/stage dropdown alignment. - Added CRM relationship model and custom business records: - Relationship types - Record relationships - Custom business record types - Custom business record fields - Custom business records - Connected relationships and custom records into Customer 360 and the customer drawer. Known limitations: - Frontend bundle remains large; route-level code splitting is still required. - Formal VAPT, load testing, disaster recovery test evidence, and full CI/CD evidence are not yet attached. - Many non-CRM modules remain prototype-level pending page-by-page hardening. ## 4. System Context, Component, Deployment, Integration, and Data Architecture Diagrams ### System Context ```mermaid flowchart LR User[Business User] --> Web[Rails ERP Web App] Admin[System/Tenant Admin] --> Web Web --> API[Rails ERP Backend API] API --> DB[(PostgreSQL rails_erp)] API --> Files[(Tenant Files and Branding Assets)] API --> Mail[Email/SMS Providers] API --> Queue[RabbitMQ Planned] API --> Cache[Redis Planned] Web --> AI[Cutecat AI Insight Service] AI --> API AI --> DB ``` ### Component Architecture ```mermaid flowchart TB subgraph Frontend React[React + TypeScript SPA] Guards[Auth Guards + RBAC Route Matrix] UI[Module Pages and Drawers] APIClient[Authenticated API Client] end subgraph Backend Router[PHP Router] Middleware[JWT/Auth/Tenant Middleware] Modules[Business Modules] Repos[Repositories] end subgraph Data Platform[(platform)] IAM[(iam)] CRM[(crm)] Settings[(settings)] Other[(module schemas)] end React --> Guards --> UI --> APIClient APIClient --> Router --> Middleware --> Modules --> Repos Repos --> Platform Repos --> IAM Repos --> CRM Repos --> Settings Repos --> Other ``` ### Deployment Architecture ```mermaid flowchart LR Browser[Browser] --> Apache[Apache HTTP Server] Apache --> Static[Vite Build Assets] Apache --> PHP[PHP 8.2 Backend] PHP --> Pg[(PostgreSQL)] PHP -. planned .-> Redis[(Redis)] PHP -. planned .-> RabbitMQ[(RabbitMQ)] PHP -. planned .-> ObjectStore[(Object/File Storage)] PHP -. planned .-> Cutecat[Cutecat FastAPI AI Service] ``` ### Integration Architecture ```mermaid flowchart LR ERP[Rails ERP API] --> Webhooks[Outbound Webhooks] ERP --> Email[Email/SMS] ERP --> Payments[Payment/Merchant Connectors] ERP --> Imports[CSV/File Imports] ERP --> Cutecat[Cutecat AI Insight API] External[External Systems] --> PublicAPI[Public API/API Keys] PublicAPI --> ERP ``` ### Data Architecture ```mermaid flowchart TB Tenant[platform.tenants] --> Users[iam.users] Tenant --> Settings[settings.*] Tenant --> Contacts[contacts.contacts] Tenant --> Customers[crm.customers] Contacts --> Customers Customers --> Leads[crm.leads] Leads --> Opportunities[crm.opportunities] Customers --> Timeline[crm.customer_timeline_events] Customers --> Relationships[crm.record_relationships] Relationships --> RelationshipTypes[crm.relationship_types] Relationships --> BusinessRecords[crm.business_records] BusinessRecords --> RecordTypes[crm.business_record_types] RecordTypes --> RecordFields[crm.business_record_fields] ``` ## 5. Technology Stack and Infrastructure Specifications | Layer | Technology | | --- | --- | | Frontend | React 18, TypeScript, Vite, shadcn/Radix UI, Tailwind CSS, React Router, React Query, Recharts | | Backend | PHP 8.2, modular PSR-4 application structure | | Database | PostgreSQL database named `rails_erp`, schema-per-domain design | | Web server | Apache HTTP Server | | Auth | JWT/session-based authentication with tenant-aware request context | | Planned cache | Redis for permission cache, tenant settings, throttling, dashboard cache, idempotency | | Planned queue | RabbitMQ for notifications, audit/event publishing, integrations, long-running jobs | | AI service | Cutecat Python/FastAPI service planned for module-specific insights | | Test tools currently observed | TypeScript compiler, ESLint, Vitest scaffold | | API collection | Postman collection exists for Users/IAM | ## 6. Database ERD and Data Dictionary ### High-Level ERD ```mermaid erDiagram PLATFORM_TENANTS ||--o{ IAM_USERS : owns PLATFORM_TENANTS ||--o{ SETTINGS : configures PLATFORM_TENANTS ||--o{ CONTACTS : owns PLATFORM_TENANTS ||--o{ CRM_CUSTOMERS : owns CRM_CUSTOMERS ||--o{ CRM_LEADS : converts_from_or_links CRM_LEADS ||--o{ CRM_OPPORTUNITIES : converts_to CRM_CUSTOMERS ||--o{ CRM_CUSTOMER_TIMELINE_EVENTS : has CRM_CUSTOMERS ||--o{ CRM_CUSTOMER_CREDIT_EVENTS : has CRM_RELATIONSHIP_TYPES ||--o{ CRM_RECORD_RELATIONSHIPS : defines CRM_BUSINESS_RECORD_TYPES ||--o{ CRM_BUSINESS_RECORD_FIELDS : defines CRM_BUSINESS_RECORD_TYPES ||--o{ CRM_BUSINESS_RECORDS : owns ``` ### Data Dictionary Summary | Schema | Main tables | Purpose | | --- | --- | --- | | platform | tenants and tenant setup records | Tenant/business identity, onboarding, subscription context | | iam | users, roles, permissions, user-role mappings, activity/session/security records | Authentication, authorization, auditability | | settings | branding, localization, numbering, approval rules, operational defaults, integrations, API keys, notification settings | Tenant configuration | | contacts | contacts, categories, activities, import/export resources | Shared person/business contact foundation | | crm | customers, leads, opportunities, statuses, sources, stages, activities, assignments, analytics, relationships, business records | CRM, sales pipeline, Customer 360 relationship layer | | sales | sales orders, quotations, returns, credit references | Sales transactions and customer-facing documents | | purchases | purchase orders, receiving, returns, variances | Procurement and inbound operations | | suppliers | supplier records, status, returns, price history | Supplier master data and performance | | inventory | items, categories, stock, movements, counts, reorder rules | Inventory control | | warehouse | warehouses, locations, bins, inbound/outbound, transfers | Warehouse execution | | accounting | chart of accounts, journals, invoices, receivables, payables, reports | Financial accounting | | hr_payroll/org | employee, payroll, attendance, leave, recruitment, organization structure | HR and payroll | | assets | asset register, maintenance, depreciation, movements, compliance | Fixed assets and maintenance | | workflow | approvals, queues, audit trail, escalations | Approval orchestration | | reports | analytics snapshots, report outputs, datasets | Reporting and analytics | Full table/column-level dictionary remains a required generated artifact from PostgreSQL metadata. ## 7. API and Integration Documentation Current API pattern: - Versioned route prefix: `/api/v1` - Domain routes: `/api/v1/users`, `/api/v1/settings`, `/api/v1/contacts`, `/api/v1/crm`, etc. - Authenticated requests carry JWT/session authorization and tenant context. - Standard response style observed: - `success` - `message` - `data` CRM and relationship API resources added or hardened: | Resource | Purpose | | --- | --- | | `/api/v1/crm/customers` | Customer list/create/update/status/delete | | `/api/v1/crm/leads` | Lead lifecycle | | `/api/v1/crm/opportunities` | Opportunity lifecycle | | `/api/v1/crm/lead-sources` | Lead source setup | | `/api/v1/crm/lead-statuses` | Lead status/stage setup | | `/api/v1/crm/opportunity-stages` | Opportunity stage setup | | `/api/v1/crm/relationships` | Entity-to-entity relationship records | | `/api/v1/crm/relationship-types` | Relationship type configuration | | `/api/v1/crm/business-record-types` | Custom business record type definitions | | `/api/v1/crm/business-record-fields` | Custom business record fields | | `/api/v1/crm/business-records` | Custom business record instances | Required documentation still pending: - OpenAPI/Swagger specification. - Full Postman collection beyond IAM. - Webhook payload catalogue. - API key lifecycle guide. - Integration retry/idempotency contract. ## 8. Security Architecture, RBAC Matrix, VAPT Results, and Vulnerability Status ### Security Architecture ```mermaid flowchart LR Login[Login/Signup] --> Token[JWT/Session] Token --> Guard[Frontend Auth Guard] Token --> APIAuth[Backend Auth Middleware] APIAuth --> Tenant[Tenant Context] Tenant --> RBAC[Roles and Permissions] RBAC --> Route[Route Access] RBAC --> Action[Action Authorization] APIAuth --> Audit[Activity Logs] ``` Security controls implemented or partially implemented: - Auth guard prevents unauthenticated access to ERP routes. - Authenticated users are redirected away from public auth page. - Tenant context shown in top bar and sent through API layer. - RBAC route and navigation matrix implemented in the frontend. - IAM user, role, permission, activity log, security settings, and password workflows are API-backed. - User profile and password change are available. - Raw UUID exposure removed from user-facing account/customer activity surfaces where hardened. ### RBAC Matrix Summary | Area | Permission examples | | --- | --- | | Dashboards | `dashboard.executive.view`, `dashboard.crm.view`, `dashboard.sales.view`, `dashboard.inventory.view` | | Users/IAM | `users.view`, `users.create`, `users.update`, `users.audit.view`, `roles.view`, `security.view`, `profile.view` | | Contacts | `contacts.view`, `contacts.create` | | CRM | `crm.view`, `customers.create`, `crm.relationships.view`, `crm.business_records.view`, `customer360.view` | | Sales | `sales.view`, `sales.orders.create` | | Purchases | `purchases.view`, `purchases.orders.create` | | Suppliers | `suppliers.view`, `suppliers.create` | | Operations | `inventory.view`, `warehouse.view`, `manufacturing.view`, `pos.view` | | Finance | `accounting.view`, `reports.view` | | Administration | `settings.view`, `approvals.view`, `automation.view`, `integrations.view` | Required security evidence still pending: - Formal VAPT report. - Dependency vulnerability scan report. - Static application security test report. - Dynamic application security test report. - API authorization bypass test evidence. - Tenant isolation test evidence. - Password policy and session management test evidence. Current vulnerability status: no formal vulnerability register is attached to this document. This must be created before production certification. ## 9. Performance, Load Testing, and Availability Reports Observed performance evidence: - Frontend production build succeeds. - Known frontend bundle size issue remains: main JS bundle is above recommended size, requiring route-level code splitting. - Settings save latency issue was identified during QA and optimized. Required performance evidence still pending: - API baseline latency report by endpoint. - Browser performance report for main workflows. - Load test plan and results. - Stress test and soak test results. - Database query performance report. - Availability/SLO report. - Capacity model for expected tenants, users, records, and request rate. No production availability metric should be claimed until these reports are produced. ## 10. Backup, Restoration, and Disaster Recovery Required documentation still pending: - PostgreSQL backup schedule. - Point-in-time recovery policy. - File/object storage backup strategy. - Encryption-at-rest and encryption-in-transit statement. - Restore runbook. - Disaster recovery runbook. - Recovery Time Objective (RTO). - Recovery Point Objective (RPO). - Evidence of successful restore test. Recommended baseline: - Daily full database backup. - Continuous WAL archiving for point-in-time recovery. - Separate backup storage account/location. - Quarterly restore test. - Runbook covering database, uploaded files, environment variables, DNS, and application deployment. ## 11. Source-Code Repository, CI/CD, and Automated Test Evidence Observed source locations: | Component | Local path | | --- | --- | | Backend API | `C:\Apache24\htdocs\cutehorse` | | Frontend SPA | `C:\Apache24\htdocs\railserp` | | AI Insight service | `C:\Apache24\htdocs\cutecatv2` | Observed build/test tooling: - Frontend: `npm run build`, `npx tsc --noEmit`, `npx eslint`, `vitest` - Backend: Composer/PSR-4 PHP project structure - API collection: Postman IAM collection Required evidence still pending: - Remote repository URLs. - Branching strategy. - Pull request/review policy. - CI pipeline configuration. - CD/deployment pipeline configuration. - Unit test report. - Integration test report. - End-to-end test report. - Code coverage report. - Release artifact/version tagging evidence. ## 12. User Manuals, Configuration Guides, and Test/UAT Reports Required manuals: - Tenant signup and onboarding guide. - Admin/IAM guide. - Settings configuration guide. - Contacts and CRM guide. - Customer 360 guide. - Relationship and Custom Business Records guide. - Module-specific guides for Sales, Purchases, Inventory, Warehouse, POS, HR, Assets, Accounting, Reports, AI, Integrations. Required test/UAT artifacts: - IAM UAT script and signed results. - Settings UAT script and signed results. - Contacts/CRM/Relationships UAT script and signed results. - Cross-module process UAT scripts: - Lead to customer to opportunity - Quote to order to invoice - Purchase to receiving to inventory - Inventory transfer to warehouse reconciliation - Employee onboarding to payroll - Defect log and closure evidence. ## 13. IP Ownership and Third-Party/Open-Source Licence Information Product IP ownership should be confirmed contractually by the product owner. Open-source dependency categories observed: - React ecosystem dependencies. - Radix UI/shadcn UI component ecosystem. - Tailwind CSS. - Vite/TypeScript/ESLint/Vitest development tooling. - PHP runtime and Composer autoloading. - PostgreSQL database. Required licence evidence still pending: - Frontend dependency licence report from `package-lock.json`. - Backend dependency licence report from `composer.lock`. - Third-party asset/font/icon licence report. - Confirmation of ownership for custom source code, database schema, UI design, and documentation. - AI service dependency licence report for Cutecat. ## 14. Efficiency and ROI Evidence No ROI or efficiency figures should be presented as final unless backed by measurable assumptions and calculations. Required ROI evidence: - Baseline process time before Rails ERP. - Target process time after Rails ERP. - User count by role. - Transaction volume by module. - Error/rework rate before and after. - Labour cost assumptions. - Licensing/infrastructure/support cost assumptions. - Implementation and training cost assumptions. - Payback period and sensitivity analysis. Recommended calculation model: ```text Annual efficiency value = (baseline minutes per transaction - target minutes per transaction) * annual transaction count / 60 * weighted average hourly labour cost Annual error reduction value = (baseline error rate - target error rate) * annual transaction count * average cost per error Net annual benefit = annual efficiency value + annual error reduction value + avoided software/process cost - annual operating cost ROI = net annual benefit / implementation cost ``` ## Evidence Register | Evidence item | Current status | | --- | --- | | Module catalogue | Drafted in this document | | Module maturity matrix | Drafted in this document | | v3.2.1 release notes | Drafted in this document | | Architecture diagrams | High-level diagrams drafted | | ERD/data dictionary | High-level ERD and schema dictionary drafted; full generated dictionary pending | | API documentation | High-level summary drafted; OpenAPI pending | | RBAC matrix | High-level matrix drafted; full permission export pending | | VAPT | Pending | | Vulnerability register | Pending | | Load/performance test report | Pending | | Backup/DR runbook | Pending | | CI/CD evidence | Pending | | Automated test evidence | Pending | | User manuals | Pending | | UAT reports | Pending | | Licence/IP report | Pending | | ROI calculations | Pending | ## Completion Recommendation Before claiming Rails ERP v3.2.1 as production-ready, complete these evidence tracks: 1. Finish CRM and Relationships contextual linking across Customer 360, customers, contacts, leads, and opportunities. 2. Complete page-by-page hardening for Sales, Purchases, Inventory, Warehouse, Settings module extensions, and Customer 360. 3. Generate OpenAPI documentation from backend routes. 4. Generate PostgreSQL ERD and data dictionary from the live database. 5. Run automated regression tests, role-based UAT, VAPT, dependency scans, and load tests. 6. Produce backup/restore evidence and deployment runbooks. 7. Produce licence/IP and ROI evidence.