CRM Architecture Design Document

C4 Model Analysis with Integrated Diagrams

Document Information

• Version: 1.0
• Date: October 2025
• Methodology: C4 Model (Context, Container, Component, Code)

Executive Summary

This document presents the CRM module architecture using the C4 model methodology. The CRM transforms our QR Contact Card Generator into a comprehensive professional networking platform with viral growth mechanics, AI-powered enrichment, and social graph visualization.

Key Architectural Decisions

1. Modular Monolith: CRM as a module within existing platform (ADR-001)
2. Multi-Provider Enrichment: Orchestrated data enrichment (ADR-002)
3. PostgreSQL Graph Storage: With Redis caching layer (ADR-003)
4. Multi-Loop Viral System: Credit-based incentives (ADR-004)

Level 1: System Context

Context Diagram

Context Description

Users:

• Professionals: Real estate agents, entrepreneurs, students using CRM
• Team Members: Colleagues sharing contact databases
• Contacts: People scanned via QR joining the network

External Systems:

• Email Providers: Two-way sync for communication tracking
• Enrichment APIs: AI-powered contact data enhancement
• Social Networks: Profile imports and verification
• Payment Gateway: Premium subscriptions and credits
• Analytics: Usage tracking and viral metrics

Level 2: Container Diagram

Container Architecture

Container Descriptions

Container	Technology	Purpose	Interfaces
Web Application	React, TypeScript, Chakra UI	Primary user interface	REST API, WebSocket
Mobile App	React Native	Mobile experience	REST API
API Gateway	Cloud Run, Rust	Request routing, auth	HTTP/2, gRPC
CRM Service	Rust, Actix-web	Contact management core	REST API
Enrichment Service	Rust, Tokio	AI data enrichment	Pub/Sub, REST
Social Graph	Rust, PostgreSQL	Relationship mapping	REST API
Viral Engine	Rust	Growth mechanics	Pub/Sub events
PostgreSQL	PostgreSQL 15	Primary data store	SQL
Redis	Redis 7	Caching layer	Redis protocol

Level 3: Component Diagram - CRM Service

CRM Service Components

Component Responsibilities

Component	Responsibility	Key Methods
Contact API	HTTP request handling	create(), update(), search()
Contact Manager	Business logic orchestration	createContact(), mergeContacts()
Import Engine	Bulk import processing	importCSV(), importVCard()
Search Engine	Full-text search	searchContacts(), filterByTags()
QR Bridge	QR integration	qrToContact(), contactToQR()
Contact Repository	Database operations	save(), find(), delete()
Cache Repository	Redis caching	get(), set(), invalidate()

Level 4: Code Level - Contact Creation Flow

Sequence Diagram: Create Contact from QR Scan

Code Implementation Example

// Contact creation with QR integration
pub async fn create_contact_from_qr(
    qr_data: QRScanData,
    services: Arc<Services>,
) -> Result<Contact, ServiceError> {
    // 1. Parse vCard from QR
    let vcard = parse_vcard(&qr_data.content)?;
    
    // 2. Check for duplicates
    if let Some(existing) = services.crm
        .find_duplicate(&qr_data.user_id, &vcard.email)
        .await? 
    {
        // Merge with existing
        return services.crm.merge_contact(existing.id, vcard).await;
    }
    
    // 3. Create contact
    let contact = services.crm
        .create_contact(CreateContactRequest {
            user_id: qr_data.user_id,
            email: vcard.email,
            name: vcard.name,
            source: ContactSource::QRScan,
            qr_code_id: Some(qr_data.qr_code_id),
        })
        .await?;
    
    // 4. Trigger enrichment
    services.events
        .publish(Event::ContactCreated {
            contact_id: contact.id,
            trigger_enrichment: true,
        })
        .await?;
    
    // 5. Award viral credits
    services.viral
        .award_action(ViralAction::QRScanned {
            owner_id: qr_data.qr_owner_id,
            scanner_id: qr_data.user_id,
            credits: 2,
        })
        .await?;
    
    Ok(contact)
}

Data Flow Analysis

Contact Enrichment Flow

Performance Architecture

Caching Strategy

Cache Level	Storage	TTL	Purpose
L1 - Hot	Redis	1 hour	Active contacts
L2 - Warm	Redis	24 hours	Recent searches
L3 - Cold	PostgreSQL	7 days	Enrichment data

Query Optimization

-- Optimized contact search
CREATE INDEX idx_contacts_search 
ON contacts USING gin(
    to_tsvector('english', 
        name || ' ' || email || ' ' || company
    )
);

-- Efficient relationship traversal
CREATE INDEX idx_relationships_graph 
ON relationships(from_contact_id, to_contact_id)
INCLUDE (strength, relationship_type);

Deployment Architecture

Multi-Region Setup

Security Architecture

Security Layers

1. API Gateway: Rate limiting, API key validation
2. Authentication: Firebase Auth, JWT tokens
3. Authorization: RBAC with team permissions
4. Data Protection: Field-level encryption for PII
5. Privacy: GDPR compliance, consent tracking

Monitoring & Observability

Key Metrics

Metric	Target	Alert Threshold
API Latency	<200ms p95	>500ms
Enrichment Success	>85%	<70%
Cache Hit Rate	>80%	<60%
K-Factor	>2.5	<2.0
Error Rate	<0.1%	>1%

Value Proposition Summary

Technical Excellence

• Performance: Sub-200ms API responses
• Scalability: Handles 10M+ contacts
• Reliability: 99.9% uptime SLA
• Security: Enterprise-grade protection

Business Value

• Viral Growth: K-factor 2.5+ through multi-loop system
• Network Effects: Value increases with n² users
• Data Quality: AI enrichment + community validation
• Integration: Seamless QR + CRM synergy

User Benefits

• Free Tier: 100 contacts with basic features
• Credit System: Earn by contributing
• Rich Profiles: AI-powered enrichment
• Relationship Insights: Social graph visualization

Implementation Roadmap

1. Phase 1 (Weeks 1-3): Core CRM + QR Integration
2. Phase 2 (Weeks 4-6): Enrichment + Social Graph
3. Phase 3 (Weeks 7-9): Viral Mechanics + Frontend
4. Phase 4 (Weeks 10-12): Advanced Features + Launch

Conclusion

The CRM architecture leverages modern cloud-native patterns while maintaining pragmatic simplicity. The modular monolith approach allows rapid development with a clear path to microservices. The multi-loop viral system creates sustainable growth through aligned incentives, while the technical architecture ensures performance and scalability.

Key success factors:

• Tight integration with QR platform
• Multi-provider enrichment strategy
• PostgreSQL-based graph with smart caching
• Credit-based viral mechanics
• Progressive feature unlocking

This architecture positions the platform as a genuine LinkedIn alternative focused on relationship building rather than professional posturing.