Skip to main content

Software Design Document - QR Contact Card Generator

Document Specification Block​

Document: software-design-document
Version: 1.0.0
Purpose: Define the complete software architecture using C4 model for the QR Contact Card Generator platform
Audience: Developers, architects, technical stakeholders
Date Created: 2025-10-03
Status: INITIAL

Table of Contents​

1. Introduction​

1.1 Purpose​

The QR Contact Card Generator is a viral-growth platform that enables professionals to create, share, and track digital business cards through QR codes. The system emphasizes organic growth through multiple viral loops while maintaining a transparent data exchange model.

1.2 Scope​

This document covers the complete software architecture from system context to code-level implementation details, following the C4 architecture model.

1.3 Key Architectural Principles​

  • Event-Driven Architecture: Asynchronous processing for scalability
  • Microservices Pattern: Loosely coupled services for flexibility
  • Cloud-Native Design: Built for GCP with auto-scaling capabilities
  • Security First: Defense-in-depth with multiple security layers
  • Performance Optimized: Sub-50ms latency targets globally

2. System Context (C4 Level 1)​

2.1 System Context Diagram​

2.2 Key Actors​

  • Professional Users: Primary users who create and manage contact cards
  • Card Recipients: Secondary users who scan QR codes and may convert
  • Team Admins: Manage organizational accounts and team features
  • Event Organizers: Configure event-specific networking features

2.3 External Dependencies​

  • SendGrid: Transactional email and viral invitation delivery
  • GCP: Cloud infrastructure (Cloud Run, Cloud SQL, Pub/Sub)
  • Stripe: Payment processing and subscription management
  • Mixpanel: User analytics and viral coefficient tracking
  • Social Platforms: Multi-channel sharing integration
  • Partner Systems: CRM and marketing automation integrations

3. Container Diagram (C4 Level 2)​

3.1 Container Overview​

3.2 Container Descriptions​

3.2.1 Client Layer​

  • Web Application: React-based SPA with TypeScript
  • WASM Module: Rust-compiled QR generation for client-side performance

3.2.2 API Layer​

  • Load Balancer: GCP Load Balancer handling HTTPS/WSS traffic
  • REST API: Main API server built with Rust/Axum
  • WebSocket Gateway: Real-time updates for live activity feeds

3.2.3 Application Services​

  • Auth Service: Authentication and authorization logic
  • Card Service: Contact card CRUD operations
  • Viral Service: Viral mechanics and growth features
  • Event Service: Event and conference management
  • Team Service: Organization and team features

3.2.4 Event Processing​

  • Pub/Sub: Google Cloud Pub/Sub for async messaging
  • Workers: Specialized workers for different async tasks

3.2.5 Data Storage​

  • PostgreSQL: Primary relational database
  • Redis: Caching and session storage
  • Cloud Storage: QR code image storage with CDN

4. Component Diagram (C4 Level 3)​

4.1 API Service Components​

4.2 Frontend Components​

5. Code Level Design (C4 Level 4)​

5.1 Key Design Patterns​

5.1.1 Repository Pattern​

// Example: User Repository
pub trait UserRepository {
    async fn find_by_id(&self, id: Uuid) -> Result<Option<User>, Error>;
    async fn find_by_email(&self, email: &str) -> Result<Option<User>, Error>;
    async fn create(&self, user: CreateUser) -> Result<User, Error>;
    async fn update(&self, id: Uuid, user: UpdateUser) -> Result<User, Error>;
    async fn delete(&self, id: Uuid) -> Result<(), Error>;
}

5.1.2 Event-Driven Pattern​

// Event Publisher
pub trait EventPublisher {
    async fn publish<T: Event>(&self, event: T) -> Result<(), Error>;
}

// Event Handler
pub trait EventHandler<T: Event> {
    async fn handle(&self, event: T) -> Result<(), Error>;
}

5.1.3 Circuit Breaker Pattern​

pub struct CircuitBreaker<T> {
    failure_threshold: u32,
    timeout: Duration,
    state: Arc<Mutex<CircuitState>>,
}

5.2 Domain Models​

5.2.1 Core Entities​

  • User: System users with authentication
  • ContactCard: Digital business card information
  • QRCode: Generated QR code metadata
  • Team: Organization grouping
  • Event: Conference/meetup events
  • ViralCampaign: Viral sharing campaigns

5.2.2 Value Objects​

  • Email: Validated email addresses
  • PhoneNumber: Formatted phone numbers
  • QRConfig: QR generation settings
  • SharingStats: Viral metrics

6. Data Architecture​

6.1 Database Schema Overview​

6.2 Caching Strategy​

  • Session Data: Redis with 24hr TTL
  • User Profiles: Redis with 1hr TTL
  • QR Images: CDN with 1yr cache
  • Analytics: Redis sorted sets for real-time metrics

7. Security Architecture​

7.1 Authentication & Authorization​

  • Authentication: JWT tokens with refresh mechanism
  • Authorization: RBAC with user, team_admin, system_admin roles
  • OAuth: Google, Microsoft integration for enterprise

7.2 Security Layers​

  1. Network Security: Cloud Armor DDoS protection
  2. Application Security: Input validation, SQL injection prevention
  3. Data Security: Encryption at rest (AES-256) and in transit (TLS 1.3)
  4. Access Control: Principle of least privilege

7.3 Compliance​

  • GDPR: Data export, deletion, consent management
  • SOC2: Audit logging, access controls
  • PCI DSS: Payment data handling via Stripe

8. Deployment Architecture​

8.1 Infrastructure Overview​

8.2 Scaling Strategy​

  • Auto-scaling: Cloud Run scales 0-100 instances based on load
  • Database: Vertical scaling for PostgreSQL, read replicas for distribution
  • Caching: Redis cluster with automatic failover
  • CDN: Global edge locations for static assets

9. Integration Points​

9.1 External API Integrations​

  • SendGrid API: Email delivery with webhooks for tracking
  • Stripe API: Payment processing and subscription management
  • Social Platform APIs: LinkedIn, WhatsApp sharing
  • Analytics APIs: Mixpanel for user behavior tracking

9.2 Webhook Endpoints​

  • Email Events: /webhooks/sendgrid - delivery status
  • Payment Events: /webhooks/stripe - subscription changes
  • Social Callbacks: /callbacks/oauth - authentication flows

9.3 Partner Integrations​

  • CRM Systems: Salesforce, HubSpot via REST APIs
  • Marketing Automation: Mailchimp, ConvertKit webhooks
  • Calendar Systems: Calendly, Cal.com for booking

10. Technology Stack Summary​

10.1 Backend Technologies​

  • Language: Rust (performance, safety)
  • Framework: Axum (async web framework)
  • Database: PostgreSQL 15+ (relational data)
  • Cache: Redis (session, real-time data)
  • Message Queue: Google Pub/Sub
  • Container: Docker with Cloud Run

10.2 Frontend Technologies​

  • Framework: React 18+ with TypeScript
  • UI Library: Chakra UI v2
  • State Management: Zustand + React Query
  • Build Tool: Vite
  • WASM: Rust-compiled QR generation
  • Testing: Jest + React Testing Library

10.3 Infrastructure​

  • Cloud Provider: Google Cloud Platform
  • CI/CD: GitHub Actions
  • Monitoring: Prometheus + Grafana
  • Logging: Cloud Logging + Loki
  • IaC: Terraform

10.4 Development Tools​

  • Version Control: Git with GitHub
  • API Documentation: OpenAPI 3.0
  • Code Quality: Clippy (Rust), ESLint (TypeScript)
  • Security Scanning: Snyk, SAST tools

Appendix A: Glossary​

  • K-Factor: Viral coefficient measuring growth rate
  • CAC: Customer Acquisition Cost
  • LTV: Lifetime Value of a customer
  • WASM: WebAssembly for client-side performance
  • Circuit Breaker: Pattern to prevent cascading failures
  • Event Sourcing: Storing state changes as events
  • RBAC: Role-Based Access Control

Appendix B: References​

  1. C4 Model: https://c4model.com/
  2. Twelve-Factor App: https://12factor.net/
  3. Cloud Native Patterns: https://www.cncf.io/
  4. OWASP Security Guidelines: https://owasp.org/