# palantir/phishcatch architecture

> Architecture diagram of the GitHub repository palantir/phishcatch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/palantir/phishcatch
- Repository: https://github.com/palantir/phishcatch

## Overview

##### Main components
- Chrome Extension: Located in the “extension” directory. This is the primary client-side component.
- Frontend/UI: Built using React (see the “react-popup” folder including app.tsx, debug.tsx, and form components).
- Background & Content Scripts: These include files like background.ts, content.ts, and a comprehensive “lib” folder (functions for hashing, notification handling, debouncing, etc.). They perform core phishing detection tasks.
- Testing and configuration: Contains tests under “__tests__” and configuration files such as package.json, tsconfig.json, webpack configs.
- Server Component: Found in the “server” folder.
- It has a Dockerfile and Python code (app/__init__.py, main.py) with a requirements.txt, indicating that it’s a backend service (possibly for logging alerts, further processing, or bridging extension alerts with backend analytics).
- Policy Templates: The “policy-templates” directory includes platform-specific policy files for Mac (plist) and Windows (.reg) that likely facilitate deployment or enterprise management for browsers like Chrome and Edge.
- CI/CD and Governance: Includes configuration files for CircleCI (in .circleci) and Palantir’s internal policies (.palantir/policy.yml).

##### Relationships and interactions
- The extension’s React-based popup UI interacts with state management (MobX used in “mobx” folders) and sends alerts or notifications using the library functions (e.g., sendAlert).
- The “Policy Templates” are used for enterprise configuration. Represent them as auxiliary components that might be applied to configure or restrict browser behavior on managed systems.

##### Important architectural patterns or design principles
- Separation of concerns: The project’s design clearly segregates the client (extension UI, background, content) from the server component.
- Modular design: The “src/lib” utilities and “react-popup” components show a modular approach to handling tasks (such as hashing, debouncing, interacting with notifications).
- Configurable deployments: The inclusion of multiple configuration files (ESLint, Prettier, Webpack, and policy templates) reinforces the attention to coding standards, environment configurations, and enterprise-readiness in deployment.
- Testing and Continuous Integration: Presence of Jest configuration and CircleCI settings denote a test-driven and CI/CD-driven design.

- Clear labels for each major part (e.g., “Chrome Extension - UI (React)”, “Content Script”, “Background Script”, “Shared Libraries”, “Backend Server”, “Enterprise Policy Templates”).
- From web pages → Content Script → Background Script.
- From Extension Components → Backend Server (via API calls).
- From CI/CD pipelines (CircleCI) → Deployment/Build processes.
- Optionally, highlight the testing pipeline (Jest and test files) as an auxiliary component that underpins quality assurance.
- Integration points with the policies for enterprise configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Entity
    web["Web Page (External)"]:::external

    %% Client: Chrome Extension
    subgraph "Chrome Extension"
        ext_overall["Chrome Extension (Overall)"]:::frontend
        ext_ui["Chrome Extension - UI (React)"]:::frontend
        ext_cs["Chrome Extension - Content Script"]:::frontend
        ext_bs["Chrome Extension - Background Script"]:::frontend
        ext_lib["Chrome Extension - Shared Libraries"]:::frontend
        ext_test["Chrome Extension - Testing & Config"]:::testing
    end

    %% Server Component
    subgraph "Backend Server"
        server["Backend Server"]:::backend
    end

    %% Enterprise & Governance
    subgraph "Enterprise & Governance"
        policy["Policy Templates"]:::infra
        cicd["CI/CD Configuration"]:::infra
    end

    %% Relationships
    web -->|"injects"| ext_cs
    ext_cs -->|"message"| ext_bs
    ext_ui -->|"utilizes"| ext_lib
    ext_bs -->|"APIcall"| server
    ext_overall --> ext_ui
    ext_overall --> ext_cs
    ext_overall --> ext_bs
    ext_overall --> ext_lib
    ext_overall --> ext_test
    ext_test -->|"triggers"| cicd
    policy -->|"configures"| ext_overall
    cicd -->|"deploys"| ext_overall

    %% Click Events
    click ext_overall "https://github.com/palantir/phishcatch/tree/main/extension/"
    click ext_ui "https://github.com/palantir/phishcatch/tree/main/extension/src/react-popup/"
    click ext_bs "https://github.com/palantir/phishcatch/blob/main/extension/src/background.ts"
    click ext_cs "https://github.com/palantir/phishcatch/blob/main/extension/src/content.ts"
    click ext_lib "https://github.com/palantir/phishcatch/tree/main/extension/src/lib/"
    click ext_test "https://github.com/palantir/phishcatch/tree/main/extension/src/__tests__/"
    click server "https://github.com/palantir/phishcatch/tree/main/server/"
    click policy "https://github.com/palantir/phishcatch/tree/main/policy-templates/"
    click cicd "https://github.com/palantir/phishcatch/tree/main/.circleci/"
    click cicd "https://github.com/palantir/phishcatch/tree/main/.palantir/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef infra fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef testing fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
```
