Documentation

1. Introduction to Vertex CRM

Vertex CRM is a high-performance, Salesforce-style customer relationship management platform built for speed, clarity, and multi-organization use. This documentation provides an in-depth guide to installing, configuring, and using the platform in production environments. It is intended for administrators, implementers, and end users who need a comprehensive reference for daily operations, security, and compliance.

The platform supports core CRM objects: Accounts, Contacts, Leads, Opportunities, Activities, Tasks (Validate), Products, Price Books, Cases, Campaigns, and Reports—plus a multichannel Inbox (WhatsApp via AiSensy or Meta Cloud API, email marketing workflows). Role-based access control (RBAC) ensures that users see only the data and features permitted by their role and profile within each organization. Super administrators can manage all organizations; organization administrators can manage users, roles, and permissions within their org.

2. System Requirements and Deployment

Vertex CRM is delivered as a single Go binary and uses SQLite by default, making it suitable for lightweight deployments without a separate database server. For production, ensure the host meets the following: a modern 64-bit operating system (Linux, Windows, or macOS), at least 512 MB RAM (1 GB or more recommended for larger datasets), and sufficient disk space for the database and any file uploads (e.g., task attachments, inbox media). The application listens on a configurable TCP port (default 8080) and serves HTTP; for production, it is recommended to run behind a reverse proxy (e.g., Nginx, Caddy) with TLS termination.

Deployment options include on-premises installation, private cloud, or a hosted instance provided by your organization or a partner. Environment variables control the database connection (e.g., DATABASE_URL), port, secret key for sessions, and optional features such as logo URL and company name. Refer to the project README and your deployment runbook for exact steps. After deployment, the first run performs database migrations and seeds default organizations and demo data if applicable; the default super-admin credentials should be changed immediately in production.

3. Authentication and Access

Users authenticate via the login page with a username and password. Sessions are maintained using signed cookies (JWT). Passwords are stored in hashed form and are never transmitted or logged in plain text. After login, users are associated with one or more organizations and, within each organization, with a role and a profile that define their permissions. The organization switcher in the header allows users with access to multiple organizations to switch context; the current organization determines which data (accounts, contacts, leads, etc.) is visible and which actions are allowed.

Super administrators (users with the global admin flag) can access all organizations and all administrative functions. Organization administrators are users whose profile in that org includes "admin" with list and update permissions; they can assign roles and profiles to other users, manage roles, profiles, queues, SLA rules, and other setup items for that org. Regular users see only the sidebar and features permitted by their profile (e.g., accounts list/read/create/update/delete, leads list/read, etc.). The RBAC documentation (e.g., docs/RBAC.md in the deployment) describes the full hierarchy and how to assign roles.

4. Core Objects and Workflows

4.1 Accounts and Contacts

Accounts represent companies or organizations; contacts represent people and can be linked to an account. Both are scoped by organization. Use the Accounts and Contacts list pages to view, search, and manage records. Create and edit forms capture standard fields (name, website, phone, industry, address, etc.). List views support sorting and, where configured, filtering. Export to CSV is available for accounts and contacts for users with list permission.

4.2 Leads and Opportunities

Leads represent prospects (with status, rating, source, lead score). Leads can be converted or managed through the pipeline. Opportunities represent deals with stages, amount, close date, and probability. The opportunity board provides a visual pipeline view. Stage progression and line items (products) are supported. Forecast and reporting features aggregate opportunity data for management visibility.

4.3 Activities and Tasks (Validate)

Activities include tasks and events (calls, meetings, emails, WhatsApp) and can be linked to accounts, contacts, leads, or opportunities. The Validate (Tasks) section provides task tracking with status, progress percentage, and due dates. Task attachments support file uploads (e.g., PNG, JPG, DOC, PDF, XLS, CSV) within configured size limits. Use these for follow-ups, project tracking, and compliance or validation workflows. Inbox follow-ups and reminders create CRM activities so the next action stays visible outside the chat thread.

4.4 Products, Price Books, and Cases

Products define the items or services you sell; they can include region and category for multi-region catalogs. Price books group products with optional custom pricing; price book entries link products to a price book with a unit price. Cases are used for support or issue tracking, with status, priority, and optional SLA due dates driven by SLA rules. Queues can be used to assign cases to teams.

4.5 Campaigns and Reports

Campaigns track marketing initiatives (type, status, budget, cost) and can have campaign members (leads or contacts). Email marketing campaigns and flows (where enabled) live alongside CRM records. Reports allow you to build and run saved report definitions (e.g., accounts by industry, open pipeline, leads by source); results can be viewed in the UI and used for dashboards where configured.

5. Multichannel Inbox and WhatsApp

The Inbox consolidates customer conversations so sales and support work from one place. WhatsApp can be connected in either of two ways (configure under Setup → Integrations → WhatsApp):

• AiSensy (BSP): save Project ID and Project API password/key; point AiSensy project webhooks to /webhooks/aisensy. Outbound session text, approved templates, and media use the Project API.
• Meta WhatsApp Cloud API: save phone number ID and access token; point Meta webhooks to /webhooks/whatsapp.

When AiSensy is ready for the organization, outbound prefers the Project API; otherwise Cloud API is used. Agents can:

• Reply with free text inside the customer service window
• Send Meta-approved WhatsApp templates (manage templates in admin Ui where enabled)
• Upload and send media attachments (subject to WhatsApp size/type limits)
• Create follow-up or reminder activities on the related CRM record
• Generate and share payment links (shop payment-link API when HealthyOme-style connector is configured; otherwise Razorpay credentials where saved)
• Share catalog / subscription cards when the shop catalog connector is enabled

Record-scoped WhatsApp chat is also available from lead/contact pages. Conversation history should stay attached to the account so handovers do not lose context.

6. Administration and Setup

Access Setup via the user menu (username in the header) or the Setup (cog) icon in the sidebar; visibility requires admin list permission. Setup includes: Users (list and assign role/profile per org); Roles and Profiles (create and edit; profiles define object-level permissions); Queues; SLA Rules; Email Templates; Integrations (WhatsApp / AiSensy, Meta Ads, Google Ads where configured, Razorpay, shop/HealthyOme connectors); Organizations (edit name, domain, logo, color); and Audit Log. Only users with admin update permission (or super admin) can assign roles and permissions or create/edit roles and profiles. Ensure at least one organization administrator per org for user management.

Organizations are the top-level tenant. Default seed organizations can be customized or extended. Each organization has its own data; users can be granted access to one or more orgs via user_org_roles. Logo and branding (e.g., primary color) can be set per organization and affect the login and app header when that org is selected.

7. Integrations and API

Vertex CRM can be integrated with external systems via REST APIs and OAuth-based connectors (Meta, Google where enabled). API endpoints typically follow a pattern such as /api/v1/accounts, /api/v1/contacts, etc. Authentication is via session cookie, Authorization: Bearer <JWT>, or an organization API key (vcr_…) created under Setup → API Keys. OpenAPI stub: /docs/openapi.json.

Inbound webhooks include Lead Ads / partner capture (POST /webhooks/inbound-leads), Meta WhatsApp (/webhooks/whatsapp), and AiSensy (/webhooks/aisensy). Shared secrets and Project API keys must be rotated on staff changes and never committed to source control.

When integrating, respect rate limits and use the documented API contracts. Sensitive credentials should be stored in environment variables or encrypted org settings, not in logs.

8. Security and Compliance

Implement TLS in production; use strong secrets for session signing; and restrict database and admin access to authorized personnel. Apply the principle of least privilege: assign users only the roles and permissions they need. Review audit logs periodically for suspicious activity. For data protection (e.g., GDPR, CCPA, India’s DPDP Act), ensure lawful basis for processing, document retention, and honor data subject rights (access, correction, deletion, portability) as described in the Privacy Policy. WhatsApp conversation content is personal data—treat messaging consent and retention as part of your privacy programme.

9. Backup, Recovery, and Maintenance

Back up the database file (and any uploaded files, including inbox media under the org upload path) regularly. Test restore procedures. Plan for maintenance windows when applying upgrades. During upgrades, follow the project's release notes and migration guidance. Monitor disk space, response times, and error rates in production. For high availability, consider redundant deployments and load balancing as appropriate for your SLA.

10. Troubleshooting and Support

Common issues include login failures (verify credentials and that the account is active), missing sidebar items (check user role and profile permissions for the current org), WhatsApp send failures (confirm AiSensy Project API key or Cloud API token, webhook URL, and signature secret), and slow performance (check database size, indexes, and server resources). Logs and error messages can help diagnose problems. For further assistance, see the Support page and contact your administrator or the team responsible for your Vertex CRM instance.

This documentation is intended for production use. For the latest feature-specific details, refer to in-app Setup → Integrations, release notes, and deployment docs such as AISENSY-WHATSAPP and INBOX-COMPOSER.