# 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 {% hint style="success" %} **💡 Procurement Tip**: Many government teams already have contracts for Office 365, Azure, or AWS GovCloud. Start by leveraging existing vendor relationships. {% endhint %} #### 🟢 Easy Replacements: Quick Wins {% tabs %} {% tab title="Email Service (SMTP)" %} **Most common government replacement**: Use existing Office 365 or government email infrastructure. **Office 365 Configuration:** ```bash SES_HOST=smtp.office365.com SES_PORT=587 SES_USER=formsg@yourorg.gov SES_PASS=your-office365-app-password MAIL_FROM=noreply@yourorg.gov ``` **Validation**: Test admin login OTP delivery and form submission notifications. {% endtab %} {% tab title="Object Storage (S3-Compatible)" %} **Most common government replacement**: Azure Blob Storage or self-hosted MinIO. **Azure Blob Storage:** ```bash 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. {% endtab %} {% endtabs %} *** #### 🟡 Medium Complexity: Infrastructure Services {% tabs %} {% tab title="Database (MongoDB Compatible)" %} **Government options**: Self-hosted MongoDB cluster or Azure Cosmos DB with MongoDB API. **Self-Hosted MongoDB:** ```bash DB_HOST=mongodb://formsg-user:password@mongo1.internal:27017,mongo2.internal:27017,mongo3.internal:27017/formsg?replicaSet=rs0&authSource=admin ``` **Requirements**: Ensure transaction support, TTL indexes, and aggregation pipelines are available. {% endtab %} {% tab title="Identity Provider (SAML/OIDC)" %} **Government options**: Existing SSO systems, Azure AD B2C, or Okta. **Azure AD B2C Configuration:** ```bash # 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. {% endtab %} {% tab title="Monitoring (Metrics & Logs)" %} **Government options**: Prometheus + Grafana or existing monitoring infrastructure. **Requirements**: Ensure application metrics and log aggregation work with your monitoring stack. {% endtab %} {% endtabs %} ### 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: {% @mermaid/diagram content="graph TD %% User Actions User\[👤 User Uploads File] Admin\[👨‍💼 Admin Downloads File] ``` %% Storage Components Quarantine[🔒 Quarantine Storage
Temporary holding] Clean[✅ Clean Storage
Verified safe files] %% Security Pipeline Scanner[🛡️ Malware Protection
Automatic background scanning] Tagging[🏷️ Scan Result Tags
Status metadata] Checker[🔍 Scan Checker
Polls for completion] %% Results CleanResult[✅ File Clean
Safe for access] InfectedResult[⚠️ Threat Detected
File quarantined] %% Form Processing FormData[📝 Form Submission
Encrypted metadata stored] %% Main Flow User --> Quarantine User --> FormData %% Security Pipeline Quarantine -.-> Scanner Scanner --> Tagging Tagging -.-> Quarantine %% Result Checking Checker --> Quarantine Checker --> CleanResult Checker --> InfectedResult %% Clean File Access CleanResult --> Clean Clean --> Admin %% Infected File Handling InfectedResult --> Quarantine %% Styling classDef user fill:#e3f2fd,stroke:#1976d2,stroke-width:2px classDef storage fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px classDef security fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef safe fill:#e8f5e8,stroke:#4caf50,stroke-width:2px classDef danger fill:#ffebee,stroke:#f44336,stroke-width:2px classDef process fill:#f8f9fa,stroke:#6c757d,stroke-width:2px class User,Admin user class Quarantine,Clean storage class Scanner,Tagging,Checker security class CleanResult,Clean safe class InfectedResult danger class FormData process" %} ``` **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: {% @mermaid/diagram content="graph TD %% User Actions User\[👤 User Submits Form
with Payment] Admin\[👨‍💼 Admin Reviews
Completed Submissions] ``` %% Initial Processing Pending[📋 Pending Submission
Temporary storage] PaymentDoc[💳 Payment Document
Status tracking] Provider[💰 Payment Provider
External processing] %% Real-time Updates Webhook[🔔 Webhook Events
Status notifications] Processor[⚙️ Event Processor
Status updates] %% Reconciliation System Scheduler[⏰ Scheduled Reconciliation
Every 30 minutes] Verification[🔍 Status Verification
Cross-check with provider] %% Final States Finalized[✅ Finalized Submission
Payment confirmed] Failed[❌ Failed Payment
Submission rejected] Notifications[📧 Notifications
Confirmations sent] %% Main Flow User --> Pending User --> PaymentDoc PaymentDoc --> Provider %% Real-time Updates Provider --> Webhook Webhook --> Processor Processor --> PaymentDoc %% Reconciliation Flow Scheduler --> Verification Verification --> PaymentDoc Verification --> Provider %% Final Processing Processor --> Finalized Processor --> Failed Verification --> Finalized Verification --> Failed %% Completion Finalized --> Admin Finalized --> Notifications %% Styling classDef user fill:#e3f2fd,stroke:#1976d2,stroke-width:2px classDef processing fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px classDef payment fill:#fff3e0,stroke:#f57c00,stroke-width:2px classDef reconciliation fill:#e8f5e8,stroke:#4caf50,stroke-width:2px classDef final fill:#f8f9fa,stroke:#6c757d,stroke-width:2px classDef success fill:#e8f5e8,stroke:#4caf50,stroke-width:2px classDef failure fill:#ffebee,stroke:#f44336,stroke-width:2px class User,Admin user class Pending,PaymentDoc,Processor processing class Provider,Webhook payment class Scheduler,Verification reconciliation class Notifications final class Finalized success class Failed failure" %} ``` **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. *** {% hint style="success" %} **🎯 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. {% endhint %}