# Component Customization

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.

{% hint style="info" %}
**Important**: Maintain a clear separation between your customizations and core AskGov code to simplify future updates.
{% endhint %}

### 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`

{% hint style="danger" %}
TODO: add mermaid diagram showing the moving parts here
{% endhint %}

### 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

***

{% hint style="success" %}
**Next Steps**

* Start with branding and authentication
* Test integrations in staging environment
* Document your customizations
* Review Security Guide for hardening
  {% 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/askgov/component-customization.md?ask=<question>
```

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.