# 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://international.open.gov.sg/self-hosting/formsg/component-customization.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.