System Architecture

Detailed technical architecture of the FlowCampaign email campaign platform.

High-Level Architecture

Technology Stack

Layer	Technology	Version	Purpose
Frontend Framework	React	18.x	Component-based UI
Build Tool	Vite	5.x	Fast build and HMR
Language	TypeScript	5.x	Type safety across stack
Styling	Tailwind CSS	3.x	Utility-first CSS framework
UI Components	Custom Components	-	Apple Weather-style design
Animations	Framer Motion	12.x	Micro-animations and transitions
Routing	React Router	6.x	Client-side routing
State Management	React Context	-	Lightweight state management
HTTP Client	Fetch API	-	Native browser fetch
Backend Framework	Hono	4.x	Lightweight web framework
Runtime	Cloudflare Workers	Latest	Serverless edge runtime
Database	SQLite	3.x	Local/edge database
ORM	Drizzle ORM	Latest	Type-safe SQL queries
Database Runtime	Cloudflare D1/Turso	-	Edge SQL database (optional)
Email Providers	ZeptoMail API	-	Primary email service
Email Providers	SMTP	-	Fallback/custom SMTP
Encryption	Web Crypto API	-	Credential encryption
Build System	npm workspaces	-	Monorepo management

Application Architecture

Monorepo Structure

email-campaign/
├── frontend/                    # React SPA application
│   ├── src/
│   │   ├── components/         # Reusable UI components
│   │   ├── pages/              # Page components
│   │   ├── features/           # Feature modules
│   │   ├── hooks/              # Custom React hooks
│   │   ├── contexts/           # React contexts
│   │   ├── layouts/            # Layout components
│   │   └── lib/                # Frontend utilities
│   └── public/                 # Static assets
├── backend/                    # Cloudflare Worker API
│   ├── src/
│   │   ├── routes/             # API route handlers
│   │   ├── services/           # Business logic services
│   │   ├── db/                # Database models and queries
│   │   └── middlewares/       # Request middleware
│   └── drizzle/               # Database migrations
└── shared/                    # Shared code
    ├── types/                 # TypeScript type definitions
    ├── utils/                 # Shared utilities
    ├── constants/            # Shared constants
    ├── validators/           # Validation schemas
    └── templates/            # Email templates

Frontend Architecture

Route Map

Path	Component	Purpose	Auth Required
`/`	Dashboard	Campaign overview and KPIs	✅
`/login`	Login	Authentication page	❌
`/compose`	Compose	Create new email campaigns	✅
`/campaigns`	Campaigns	View all campaigns	✅
`/contacts`	Contacts	Manage contact lists	✅
`/providers`	Providers	Email provider management	✅
`/templates`	Templates	Email template library	✅
`/analytics`	Analytics	Detailed campaign analytics	✅
`/settings`	Settings	Platform configuration	✅
`/campaign/:id/stats`	CampaignStats	Individual campaign stats	✅
`/campaign/:id/audience`	CampaignAudience	Campaign recipient management	✅
`/campaign/:id/review`	CampaignReview	Campaign review before sending	✅

Component Hierarchy

App (Root)
├── AuthProvider (Authentication context)
├── ThemeProvider (Light/dark theme)
├── Layout
│   ├── Sidebar (Navigation)
│   ├── Header (App header)
│   └── MainContent
│       └── Routes (Dynamic routing)
└── ToastProvider (Notifications)

Backend Architecture

API Layer (Hono on Cloudflare Workers)

Base URL: https://mails.nssoftwaresolutions.in

Route Groups:

Route Group	Endpoints	Purpose
`/api/campaigns`	GET, POST, PUT, DELETE	Campaign CRUD operations
`/api/contacts`	GET, POST, PUT, DELETE	Contact management
`/api/providers`	GET, POST, PUT, DELETE	Email provider management
`/api/templates`	GET, POST, PUT, DELETE	Email template management
`/api/tracking/open/:id`	GET	Email open tracking pixel
`/api/tracking/click/:id`	GET	Click tracking redirect
`/api/unsubscribe/:id`	GET, POST	Unsubscribe management
`/api/webhooks/:provider`	POST	Email provider webhooks
`/api/dashboard`	GET	Dashboard statistics
`/api/settings`	GET, PUT	Platform settings

Database Layer (Drizzle ORM)

Connection Strategy:

Development: Local SQLite file (local.db)
Production: Cloudflare D1 or Turso database
Migrations: Managed via Drizzle Kit

Type Safety:

Full TypeScript types for all tables
Schema validation at compile time
Type-safe queries with auto-completion

Email Tracking System Architecture

Open Tracking Flow

Click Tracking Flow

Tracking Implementation Details

Open Tracking Pixel:

<!-- Embedded in every email -->
<img 
  src="https://mails.nssoftwaresolutions.in/api/tracking/open/{{recipient_id}}" 
  width="1" 
  height="1" 
  style="display:none;" 
  alt=""
/>

Click Tracking Wrapper:

// URL transformation during email sending
function trackUrl(originalUrl, recipientId) {
  const encodedUrl = encodeURIComponent(originalUrl);
  return `https://mails.nssoftwaresolutions.in/api/tracking/click/${recipientId}?url=${encodedUrl}`;
}

Email Delivery Architecture

Multi-Provider Strategy

Provider Configuration

Credentials Encryption:

AES-256-GCM encryption for provider credentials
Unique initialization vector (IV) per provider
Encrypted credentials stored in database
Decryption only during email sending

Rate Limiting:

Daily and monthly email limits per provider
Automatic provider rotation when limits reached
Queue-based sending to respect provider limits
Real-time usage tracking

Database Schema Overview

Core Tables

campaigns - Email campaign definitions
campaign_recipients - Individual email recipients
contacts - Contact information and metadata
providers - Email provider configurations
campaign_templates - Reusable email templates
campaign_events - Tracking events (opens, clicks)
activity_logs - Audit trail of system actions
provider_usage - Provider usage statistics
tags - Contact segmentation tags
contact_tags - Contact-tag relationships
settings - System configuration

Indexing Strategy

Performance Indexes:

idx_campaigns_status - Filter campaigns by status
idx_campaigns_created - Sort campaigns by creation date
idx_recipients_campaign - Fast recipient lookup by campaign
idx_recipients_status - Filter recipients by delivery status
idx_contacts_email - Unique email constraint
idx_providers_type - Filter providers by type
idx_usage_provider_date - Daily usage statistics

Security Architecture

Authentication & Authorization

JWT-based Authentication:

Edge-verified JWT tokens
Short-lived access tokens (15 minutes)
Secure token storage in memory
Automatic token refresh

Role-Based Access Control:

Super Admin: Full system access (info.nssoftwaresolutions@gmail.com)
Workspace Member: Standard user permissions
API Key: Programmatic access with limited scope

Data Protection

At Rest Encryption:

Provider credentials encrypted with AES-256-GCM
Unique IV per encryption operation
Encryption keys managed via environment variables

In Transit Security:

TLS 1.3 for all external communications
HTTPS-only API endpoints
Secure WebSocket connections for real-time updates

Input Validation:

Schema validation for all API inputs
SQL injection protection via parameterized queries
XSS prevention through output encoding
Rate limiting per IP and per account

Performance Optimization

Edge Caching Strategy

Cache Levels:

Browser Cache: Static assets (JS, CSS, images)
CDN Cache: API responses with appropriate headers
Memory Cache: Frequently accessed data in Worker memory
Database Cache: Materialized views for analytics

Cache Invalidation:

Time-based expiration (TTL)
Event-based invalidation
Manual cache clearing via admin interface

Database Optimization

Query Optimization:

Indexed queries for all common access patterns
Batch operations for bulk email sending
Connection pooling for database connections
Read replicas for analytics queries

Data Partitioning:

Campaign data partitioned by date
Contact data segmented by workspace
Event data sharded by campaign ID

Deployment Architecture

Cloudflare Workers Deployment

Continuous Deployment

Development Workflow:

Local development with npm run dev
Preview deployment via wrangler dev
Production deployment via wrangler deploy
Automatic rollback on failure

Monitoring & Observability:

Real-time error tracking via Cloudflare Analytics
Performance monitoring with Web Vitals
Email delivery tracking with provider webhooks
Custom dashboards for business metrics

Scalability Considerations

Horizontal Scaling

Stateless Workers:

Each request handled independently
No shared state between workers
Automatic load balancing across edge locations

Database Scaling:

SQLite → Turso for production scaling
Read replicas for analytics workloads
Connection pooling for high concurrency

Email Sending Scalability

Queue-Based Sending:

Asynchronous email delivery queues
Batch processing for efficiency
Retry logic with exponential backoff
Dead letter queue for failed deliveries

Provider Optimization:

Intelligent provider selection
Parallel sending to multiple providers
Dynamic rate limit adjustment
Cost optimization across providers

← Overview | → Database Schema

High-Level Architecture​

Technology Stack​

Application Architecture​

Monorepo Structure​

Frontend Architecture​

Route Map​

Component Hierarchy​

Backend Architecture​

API Layer (Hono on Cloudflare Workers)​

Database Layer (Drizzle ORM)​

Email Tracking System Architecture​

Open Tracking Flow​

Click Tracking Flow​

Tracking Implementation Details​

Email Delivery Architecture​

Multi-Provider Strategy​

Provider Configuration​

Database Schema Overview​

Core Tables​

Indexing Strategy​

Security Architecture​

Authentication & Authorization​

Data Protection​

Performance Optimization​

Edge Caching Strategy​

Database Optimization​

Deployment Architecture​

Cloudflare Workers Deployment​

Continuous Deployment​

Scalability Considerations​

Horizontal Scaling​

Email Sending Scalability​

Navigation​