aibhuyan/watchphish

1. High-level shape

WatchPhish is a monorepo with two deployable applications and three shared libraries. The runtime architecture is split between a React frontend (artifacts/phishwatch), an Express API server (artifacts/api-server), and a PostgreSQL-backed data layer (lib/db). The shared libraries provide the API contract and generated client/types.

2. Frontend boundary

artifacts/phishwatch is a Vite-based React app that serves the operator-facing UI: dashboard, brand monitor, attack library, emerging threats, and phishing simulation experiences. It is mostly a presentation layer and does not own the threat ingestion logic. It consumes the backend through generated API client code from lib/api-client-react.

3. API server boundary

artifacts/api-server is the central orchestration service. It exposes the HTTP API under /api/*, handles collection/enrichment triggers, serves dashboard/feed/brand data, and persists or reads data via the database layer. It is also where scheduled/background threat collection logic lives.

4. Threat ingestion pipeline

The backend collectors/ directory shows the main external-data ingestion subsystem. It pulls from multiple phishing and threat feeds: OpenPhish, URLhaus, PhishTank, ThreatFox, VirusTotal, RDAP, and crt.sh/CT logs. This is the data acquisition boundary from external services into WatchPhish.

5. Enrichment and classification

After raw collection, the server uses utility modules in src/lib/ such as enricher, classifier, typosquat, and certstream to normalize and enrich items. This is where domain intelligence, brand lookalike detection, sector tagging, and threat categorization happen before the data is exposed to clients or stored.

6. Scheduling and automation

src/lib/scheduler.ts indicates a background job layer inside the API server. This subsystem likely drives periodic feed collection, enrichment runs, and CT scanning without requiring a user request. The POST /api/collect, POST /api/enrich, and POST /api/ct-scan endpoints appear to be manual triggers for the same automated workflows.

7. Data model and persistence

The lib/db package is the shared database schema definition using Drizzle ORM for PostgreSQL. Its tables model the core persistent entities: feed entries, brand watchlists, certificate alerts, attack types, stats, and API call logs. This library is the persistence contract used by the server and referenced by the broader monorepo.

8. API contract and generated clients

lib/api-spec/openapi.yaml defines the REST contract, and lib/api-zod plus lib/api-client-react are generated artifacts from that spec. This creates a clear boundary: the backend implements the OpenAPI-described endpoints, while the frontend consumes generated, typed request/response helpers. The repo is set up so API shape, validation, and client types stay aligned.

9. Primary data flows

The main flow is: external phishing/threat sources → API collectors → enrichment/classification → PostgreSQL → API read endpoints → frontend dashboard and detail views. A second flow exists for the brand monitor: brand watchlist input → CT log scan / typosquat analysis → cert alerts → dismiss/inspect in UI. A third flow is the simulation library, which is mostly client-side content and interaction rather than backend-driven threat data.

10. Backend read vs write paths

Most GET endpoints are read paths over persisted or derived data: stats, feed pages, threat details, attack types, emerging threats, brands, and cert alerts. POST/DELETE endpoints mutate the system state: adding/removing brands, dismissing alerts, and kicking off collection/enrichment jobs. That separation is useful for diagramming request flow and storage dependencies.

11. Frontend UI subsystems

The React app is organized into feature sections such as DashboardSection, BrandMonitorSection, LibrarySection, NewTechniquesSection, ThreatDetailPanel, and SimulationModal. These are presentation and interaction modules layered over the API-backed data. The simulation components represent a distinct educational subsystem that does not appear to depend on the ingestion pipeline.

12. Operational and deployment boundaries

The README shows a three-part deployment model: PostgreSQL on Supabase, API server on Render, and frontend on Vercel. That means the system’s runtime dependency chain is frontend → API server → PostgreSQL/external threat services, with the API server also acting as the only component that talks to third-party intelligence sources and scans.

13. What to emphasize in an architecture diagram

The most important boxes are: the frontend UI, the Express API server, the collector/enrichment job subsystem, the PostgreSQL database, and the external threat/intelligence providers. Around them, show the shared API spec/generated client layer as a contract boundary, because it is how the monorepo keeps frontend and backend synchronized.