OmniCRM System Architecture

This document provides an overview of the OmniCRM system architecture, including component relationships and data flow.

High-Level System Overview

OmniCRM is a comprehensive BSS/OSS platform that integrates several key components to provide complete service management for telecom providers.

Core Components

1. Frontend Applications

OmniCRM Web UI

• React single-page application
• Staff interface for customer management, service provisioning, billing
• Real-time provisioning status updates
• Role-based access control

Self-Care Portal

• Customer-facing portal
• Service management and usage tracking
• Invoice viewing and payment
• Shared codebase with staff UI, different views

2. API Layer

OmniCRM API (Flask/Python)

• RESTful API for all operations
• OpenAPI/Swagger documentation
• JWT-based authentication
• Rate limiting and caching
• WebSocket support for real-time updates

Key API Routes:

• /crm/customer/* - Customer management
• /crm/service/* - Service operations
• /crm/product/* - Product catalog
• /crm/provision/* - Provisioning operations
• /crm/transaction/* - Billing transactions
• /crm/invoice/* - Invoice management

3. Provisioning System

4. Billing & Rating

OCS/CGRateS Integration

• Real-time charging and rating
• Account management
• Balance tracking (monetary, data, voice, SMS)
• Action plans for recurring charges
• Threshold-based notifications

Billing Workflow:

5. Data Model

OmniCRM uses a relational database with the following core models. For visual entity relationship diagrams, see Customers, Contacts, Sites & Services.

Customer & Related Entities

Customer - Central entity representing a company or individual

Field	Type	Description
customer_id	Integer (PK)	Unique identifier
customer_name	String	Company or individual name
customer_account_type	Enum	'Individual' or 'Business'
customer_status	Enum	'Open', 'Closed', 'Suspended', 'Archived'
customer_payment_type	String	'prepaid' or 'postpaid'
customer_enabled	Boolean	Is account active
tax_identifier	String	VAT/GST number
contract_start_date	DateTime	Contract start
contract_end_date	DateTime	Contract end

Contact - People associated with a customer

Field	Type	Description
contact_id	Integer (PK)	Unique identifier
customer_id	Integer (FK)	Parent customer
contact_firstname	String	First name
contact_lastname	String	Last name
contact_email	String	Email address
contact_phone	String	Phone number
contact_types	String	'Primary', 'Billing', 'Technical'

Site - Physical service delivery locations

Field	Type	Description
site_id	Integer (PK)	Unique identifier
customer_id	Integer (FK)	Parent customer
site_name	String	Location name
address_line_1	String	Street address
city, state, zip_code	String	Location details
latitude, longitude	Float	GPS coordinates
google_maps_place_id	String	Google Maps reference
plus_code	String	Open Location Code

Service & Product Models

Service - Active service instances

Field	Type	Description
service_id	Integer (PK)	Unique identifier
customer_id	Integer (FK)	Parent customer
product_id	Integer (FK)	Product template
site_id	Integer (FK)	Service location
service_name	String	Display name
service_uuid	String	Billing system identifier
service_status	Enum	Current status
service_billed	Boolean	Generate transactions
wholesale_cost	Float	Provider cost
retail_cost	Float	Customer price
bundled_parent	Integer (FK)	Parent service for bundles

Product - Service offering templates

Field	Type	Description
product_id	Integer (PK)	Unique identifier
product_name	String	Display name
product_slug	String	URL-friendly name
category	Enum	'standalone', 'bundle', 'addon', 'promo'
provisioning_play	String	Ansible playbook name
provisioning_json_vars	JSON	Playbook variables
inventory_items_list	String	Required inventory
retail_cost	Float	Monthly price
retail_setup_cost	Float	One-time fee
enabled	Boolean	Available for sale

Billing Models

Transaction - Individual charges/credits

Field	Type	Description
transaction_id	Integer (PK)	Unique identifier
customer_id	Integer (FK)	Parent customer
invoice_id	Integer (FK)	Parent invoice (optional)
service_id	Integer (FK)	Related service
title	String	Transaction description
retail_cost	Float	Amount
tax_percentage	Float	Tax rate
tax_amount	Float	Calculated tax
void	Boolean	Cancelled transaction

Invoice - Grouped transactions for billing

Field	Type	Description
invoice_id	Integer (PK)	Unique identifier
customer_id	Integer (FK)	Parent customer
paid	Boolean	Payment received
void	Boolean	Cancelled invoice
payment_reference	String	Stripe transaction ID
start_date, end_date	Date	Billing period
due_date	Date	Payment deadline
retail_cost	Float	Total amount

Inventory Models

Inventory - Physical and virtual assets

Field	Type	Description
inventory_id	Integer (PK)	Unique identifier
customer_id	Integer (FK)	Assigned customer
service_id	Integer (FK)	Linked service
inventory_template_id	Integer (FK)	Item type template
item	String	Item type (SIM Card, Router, etc.)
item_state	Enum	'New', 'Assigned', 'Used', etc.
itemtext1-20	String	Flexible fields
management_url	String	Equipment admin URL
config_content	Text	Configuration file

Inventory_Template - Defines inventory item structure

Field	Type	Description
inventory_template_id	Integer (PK)	Unique identifier
item	String	Template name
itemtext1_label	String	Label for itemtext1 field
itemtext2_label	String	Label for itemtext2 field

Provisioning Models

Provision - Provisioning job tracking

Field	Type	Description
provision_id	Integer (PK)	Unique identifier
product_id	Integer (FK)	Product being provisioned
customer_id	Integer (FK)	Target customer
service_id	Integer (FK)	Created/modified service
provisioning_play	String	Ansible playbook name
provisioning_status	Integer	0=Success, 1=Running, 2=Failed

Provision_Event - Individual provisioning steps

Field	Type	Description
provision_event_id	Integer (PK)	Unique identifier
provision_id	Integer (FK)	Parent provision job
event_name	String	Task name
event_number	Integer	Sequence number
provisioning_status	Integer	0=Success, 1=Running, 2=Failed
provisioning_result_json	JSON	Full task output

User & Security Models

User - User accounts

Field	Type	Description
id	Integer (PK)	Unique identifier
username	String	Login username
email	String	Email address
email_verified	Boolean	Email confirmed
is_2fa_enabled	Boolean	Two-factor auth enabled
totp_secret	String	TOTP secret key

Role - User roles

Field	Type	Description
id	Integer (PK)	Unique identifier
name	String	Role name
description	String	Role description

Permission - Granular permissions

Field	Type	Description
id	Integer (PK)	Unique identifier
name	String	Permission name (resource.action)
description	String	Permission description

Relationships:

• Users have many Roles (many-to-many)
• Roles have many Permissions (many-to-many)
• Users can link to one Contact (for customer portal access)

Integration Points

Stripe Payment Gateway

• Tokenized payment methods
• PCI-compliant card storage
• Automated invoice payment
• Refund processing
• Expiring card notifications

Mailjet Email Service

• Transactional emails (invoices, welcome, notifications)
• Contact synchronization
• Template management
• Delivery tracking

Google Maps

• Address autocomplete
• Geocoding and reverse geocoding
• Plus Code generation
• Site location mapping

OCS/CGRateS

• Account provisioning
• Real-time rating
• Balance management
• CDR processing
• Action plans and schedules

Security Architecture

Security Features:

• JWT-based authentication
• Two-factor authentication (TOTP)
• Role-based access control (RBAC)
• Permission-based resource access
• Session management with Redis
• Password hashing (bcrypt)
• Email verification
• Audit logging via Activity Log

Deployment Architecture

Recommended Production Setup:

Technology Stack

Backend:

• Python 3.x
• Flask web framework
• SQLAlchemy ORM
• Alembic migrations
• Ansible for automation

Frontend:

• React
• State management
• React Router
• Axios for API calls

Database:

• Relational database (primary data store)
• Redis (caching & sessions)

External Services:

• CGRateS (billing/rating)
• Stripe (payments)
• Mailjet (email)
• Google Maps (geocoding)

Scalability Considerations

Horizontal Scaling:

• Stateless API design allows multiple instances
• Load balancer distributes requests
• Redis for shared session state

Database Scaling:

• Read replicas for reporting queries
• Connection pooling
• Query optimization and indexing

Provisioning at Scale:

• Background job processing
• Multiple Ansible workers
• Job queue management
• Retry logic for failed provisions

Monitoring & Observability

Key Metrics:

• API response times
• Provisioning success/failure rates
• Database connection pool usage
• Cache hit rates
• Active sessions

Logging:

• Application logs (Flask)
• Provisioning logs (Ansible output)
• Activity log (audit trail)
• Error tracking and alerts

Related Documentation

• Ansible Playbooks - Provisioning automation
• Provisioning System - Workflow details
• Products and Services - Product architecture
• API Documentation - API reference
• RBAC - Security and permissions