🧩Component Customization

This guide helps you replace specific FormSG components with your preferred alternatives while maintaining security and functionality. Perfect for teams wanting to integrate FormSG with existing infrastructure or reduce cloud provider dependencies.

Component Architecture

FormSG's architecture is designed for government needs with security, flexibility, and compliance in mind. Understanding how components connect helps you plan which parts to customize:

The colour coding shows which components are easier (🟢) or harder (🔴) to replace with your preferred alternatives.

Why Customize Components?

Teams often need to adapt FormSG for:

• 🏛️ Existing Infrastructure: Integrate with current systems and contracts

• 🌍 Data Sovereignty: Keep data within your jurisdiction

• 💰 Cost Optimization: Leverage existing volume discounts

• 🔒 Compliance: Meet specific regulatory requirements

• 🔧 Operational Consistency: Use familiar tools and processes

🎯 Component Replacement Strategy

Start with easy wins to build confidence, then tackle more complex integrations:

🟢 Easy: Email service, file storage, analytics, spam protection

• Government alternatives: Office 365 SMTP, Azure Blob Storage, Matomo, hCaptcha

🟡 Medium: Database, identity provider, monitoring, SMS service

• Government alternatives: Self-hosted MongoDB, government SSO/SAML, Prometheus + Grafana, government SMS gateways

🔴 Advanced: Payment processing, virus scanner

• Government alternatives: Local payment gateways, enterprise antivirus APIs

💡 Procurement Tip: Many government teams already have contracts for Office 365, Azure, or AWS GovCloud. Start by leveraging existing vendor relationships.

🟢 Easy Replacements: Quick Wins

Email Service (SMTP)

Most common government replacement: Use existing Office 365 or government email infrastructure.

Office 365 Configuration:

SES_HOST=smtp.office365.com
SES_PORT=587
[email protected]
SES_PASS=your-office365-app-password
[email protected]

Validation: Test admin login OTP delivery and form submission notifications.

Object Storage (S3-Compatible)

Most common government replacement: Azure Blob Storage or self-hosted MinIO.

Azure Blob Storage:

AWS_ENDPOINT=https://youraccount.blob.core.windows.net
AWS_ACCESS_KEY_ID=youraccount
AWS_SECRET_ACCESS_KEY=your-blob-storage-key
IMAGE_S3_BUCKET=formsg-images
ATTACHMENT_S3_BUCKET=formsg-attachments

Validation: Test file uploads in form builder and attachment handling in forms.

---

🟡 Medium Complexity: Infrastructure Services

Database (MongoDB Compatible)

Government options: Self-hosted MongoDB cluster or Azure Cosmos DB with MongoDB API.

Self-Hosted MongoDB:

DB_HOST=mongodb://formsg-user:[email protected]:27017,mongo2.internal:27017,mongo3.internal:27017/formsg?replicaSet=rs0&authSource=admin

Requirements: Ensure transaction support, TTL indexes, and aggregation pipelines are available.

Identity Provider (SAML/OIDC)

Government options: Existing SSO systems, Azure AD B2C, or Okta.

Azure AD B2C Configuration:

# OIDC configuration
OIDC_DISCOVERY_URL=https://yourorg.b2clogin.com/yourorg.onmicrosoft.com/v2.0/.well-known/openid_configuration?p=B2C_1_signin
OIDC_CLIENT_ID=your-application-id
OIDC_CLIENT_SECRET=your-client-secret

Requirements: Ensure SAML/OIDC compliance and user attribute mapping. Modify the Singpass Login flow.

Monitoring (Metrics & Logs)

Government options: Prometheus + Grafana or existing monitoring infrastructure.

Requirements: Ensure application metrics and log aggregation work with your monitoring stack.

Component Validation Framework

For any component replacement, follow this validation approach:

1. Functionality: Core features work identically to original

2. Performance: Response times meet your requirements

3. Security: Audit logs and error handling maintained

4. Integration: Upstream/downstream systems unaffected

5. Monitoring: Health checks and alerting configured

---

🔴 Advanced Replacements: Complex Integrations

Understanding FormSG's File Security Architecture

Before replacing virus scanning, understand how FormSG's current implementation protects against malicious files:

Current Security Implementation:

• Automatic scanning - Files scanned in background without blocking submission

• Tag-based results - Scan results stored as file metadata tags

• Polling mechanism - System checks for scan completion before allowing access

• Fail secure - Files remain quarantined until explicitly marked clean

• Audit trail - All scanning results logged for compliance

When changing implementation of virus scanner, do test with known malware samples (EICAR test files).

Common Replacement Approaches:

• Government antivirus APIs: Integrate with existing enterprise security tools

• Container-based scanning: Deploy ClamAV or commercial scanners in containers

• Cloud security services: Use Azure Defender or AWS GuardDuty alternatives

Implementation Pattern: Maintain the tag-based result system and polling mechanism for compatibility.

Understanding FormSG's Payment Reconciliation Architecture

Before replacing payment processing, understand how FormSG ensures payment reliability:

Payment Reliability Features:

• Dual verification - Webhooks + scheduled reconciliation

• Status consistency - Automatic cross-checking with payment provider

• Failure recovery - Handles missed events and processing errors

• Audit trail - Complete payment history and reconciliation logs

• Automatic cleanup - Cancels stale payments and handles edge cases

Common Replacement Approaches:

• Government payment systems: Integrate with existing financial infrastructure

• Regional payment gateways: Use local banking integrations

• Enterprise payment processors: Leverage existing contracts with payment providers

Implementation Pattern: Maintain the dual verification system (webhooks + reconciliation) for reliability.

---

🎯 Success Metrics: Your customisation is successful when FormSG functions identically to the original, but with your preferred infrastructure components.

Focus on maintaining security, performance, and user experience throughout the process.