🧩Component Customization

Guide for customizing AskGov components, branding, and integrations

This guide covers the key customization points for adapting AskGov to your organization's needs. We focus on common customization scenarios rather than exhaustive code examples.

Important: Maintain a clear separation between your customizations and core AskGov code to simplify future updates.

Branding and Visual Customization

Quick Branding Checklist

Logo and Assets

• Replace /public/icons/askgov.svg with your logo

• Update /public/favicon.ico

• Add your agency logos to /public/icons/

Metadata

• Update site title and description in app/root.jsx

• Configure Open Graph tags for social sharing

• Set your organization name throughout

Color Scheme

• Primary colors in /styles/themes/light.css (CSS variables)

• Chakra UI theme colors in /app/theme/index.js

TODO: add mermaid diagram showing the moving parts here

Authentication Integration

Common Integration Patterns

SAML/SSO

• Popular for government identity providers

• Libraries: @node-saml/node-saml or passport-saml

• Configure in app/auth/saml.server.js

• Environment variables: SAML_ENTRY_POINT, SAML_ISSUER, SAML_CERT

OAuth 2.0 / OIDC

• For Google Workspace, Microsoft Azure AD, or custom providers

• Libraries: Provider-specific SDKs

• Configure callback URLs and scopes

• Store tokens securely

Custom Authentication

• Integrate with existing government auth systems

• Implement session management carefully

• Consider MFA requirements

Email Service Integration

AskGov by default uses OGP's Postman email sender, you can swap it out with these alternatives.

Email Provider Options

Provider	Use Case	Configuration
PostmanGovSG	Singapore government services	POSTMANGOVSG_API_KEY
SMTP	Universal, works with any email server	Usually SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD
SendGrid/Mailgun	Commercial email services	API key and domain configuration
AWS SES	AWS deployments	IAM role or access keys

Email Customization Points

• Templates in /app/mail/templates/

• Sender configuration in environment variables

• Delivery tracking and bounce handling

• Unsubscribe management

Search Engine Alternatives

Vector Database Options

Default: Weaviate

• Best for hybrid search (vector + keyword)

• Requires dedicated instance

• Configure vectorizer (OpenAI, Cohere, or local)

Alternative Options

Solution	Pros	Cons
Elasticsearch	Mature, feature-rich	Complex setup, resource heavy
Pinecone	Managed service, easy scaling	Cost, vendor lock-in
PostgreSQL pgvector	Simple, no extra service	Limited features
Typesense	Fast, typo-tolerant	Smaller community

Search Configuration

Key environment variables:

• WEAVIATE_INSTANCE - Search service URL

• VECTORIZER_API_KEY - For embedding generation

---

Next Steps

• Start with branding and authentication

• Test integrations in staging environment

• Document your customizations

• Review Security Guide for hardening