# sachinsh97/mail-tracker architecture

> Architecture diagram of the GitHub repository sachinsh97/mail-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sachinsh97/mail-tracker
- Repository: https://github.com/sachinsh97/mail-tracker

## Overview

Mail Tracker is a web app and API for creating email-open trackers. A signed-in user creates a tracker, copies its pixel into an email, and later views open status and history; recipient mail clients load the pixel, which the service evaluates and records. The README also documents collections, notifications, Google sign-in, and filtering false opens. Edges reflect the excerpts, SOURCE INDEX references, and README; several implementation details, especially storage and live-event wiring, were not sampled.

Main entry points: [`client/src/router.tsx`](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/router.tsx) (Screen routing), [`service/src/routes/api-v1.routes.ts`](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/routes/api-v1.routes.ts) (API routing), [`service/src/modules/trackers/tracker.controller.ts`](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/trackers/tracker.controller.ts) (Tracker endpoints), [`client/src/services/http.ts`](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/services/http.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_router["Screen routing<br/>[router.tsx]"]
  node_trackerform["Create tracker"]
  node_screens["Tracker views<br/>[TrackerScreen.tsx]"]
  node_collectionsui["Collections views"]
  node_notificationsui["Notifications view"]
  node_authclient["Sign-in client<br/>[auth.service.ts]"]
  node_httpclient["API client<br/>[http.ts]"]
end

subgraph group_api["API and identity"]
  node_apiroutes["API routing<br/>[api-v1.routes.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_authmw["Session guard<br/>[authenticate.ts]"]
  node_trackerapi["Tracker endpoints"]
  node_collectionapi["Collection endpoints"]
  node_notificationapi["Notification endpoints"]
end

subgraph group_tracking["Open detection"]
  node_pixelroute["Pixel route<br/>[tracking.routes.ts]"]
  node_pixelhandler["Pixel handling"]
  node_trackinglogic["Hit evaluation"]
end

subgraph group_data["Persistence and updates"]
  node_db[("PostgreSQL")]
  node_liveevents["Live event stream"]
end

node_user(("Email sender"))
node_mailapp(("Recipient mail app"))
node_google{{"Google sign-in"}}

node_user -->|"uses app"| node_router
node_router -->|"routes to"| node_trackerform
node_router -->|"routes to"| node_screens
node_router -->|"routes to"| node_collectionsui
node_router -->|"routes to"| node_notificationsui
node_trackerform -->|"requests API"| node_httpclient
node_authclient -->|"sends requests"| node_httpclient
node_authclient -->|"redirects for sign-in"| node_google
node_httpclient -->|"calls API"| node_apiroutes
node_apiroutes -->|"guards routes"| node_authmw
node_apiroutes -->|"dispatches tracker routes"| node_trackerapi
node_apiroutes -->|"dispatches collection routes"| node_collectionapi
node_apiroutes -->|"dispatches notifications"| node_notificationapi
node_trackerapi -->|"creates trackers"| node_trackinglogic
node_mailapp -->|"loads pixel"| node_pixelroute
node_pixelroute -->|"dispatches request"| node_pixelhandler
node_pixelhandler -->|"handles hit"| node_trackinglogic
node_trackinglogic -.->|"records hits"| node_db
node_trackerapi -.->|"persists tracker data"| node_db
node_collectionapi -.->|"persists collections"| node_db
node_notificationapi -.->|"reads notifications"| node_db
node_liveevents -.->|"streams updates"| node_user
node_screens -->|"shows open history"| node_user

click node_router "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/router.tsx"
click node_trackerform "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/hooks/useAddTrackerForm.ts"
click node_screens "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/screens/TrackerScreen.tsx"
click node_collectionsui "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/screens/CollectionScreen.tsx"
click node_notificationsui "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/screens/NotificationsScreen.tsx"
click node_authclient "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/services/auth.service.ts"
click node_httpclient "https://github.com/sachinsh97/mail-tracker/blob/master/client/src/services/http.ts"
click node_apiroutes "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/routes/api-v1.routes.ts"
click node_auth "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/auth/auth.service.ts"
click node_authmw "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/middlewares/authenticate.ts"
click node_trackerapi "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/trackers/tracker.controller.ts"
click node_collectionapi "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/collections/collection.controller.ts"
click node_notificationapi "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/notifications/notification.controller.ts"
click node_pixelroute "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/tracking/tracking.routes.ts"
click node_pixelhandler "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/tracking/tracking.controller.ts"
click node_trackinglogic "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/tracking/tracking.service.ts"
click node_liveevents "https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/live-events/live-events.controller.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_router,node_trackerform,node_screens,node_collectionsui,node_notificationsui,node_authclient,node_httpclient toneBlue
class node_apiroutes,node_auth,node_authmw,node_trackerapi,node_collectionapi,node_notificationapi toneAmber
class node_pixelroute,node_pixelhandler,node_trackinglogic toneMint
class node_db,node_liveevents toneRose
class node_user,node_mailapp,node_google toneIndigo
```

## Components

### Web client

- [Screen routing](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/router.tsx): `client/src/router.tsx`
- [Create tracker](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/hooks/useAddTrackerForm.ts): `client/src/hooks/useAddTrackerForm.ts`
- [Tracker views](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/screens/TrackerScreen.tsx): `client/src/screens/TrackerScreen.tsx`
- [Collections views](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/screens/CollectionScreen.tsx): `client/src/screens/CollectionScreen.tsx`
- [Notifications view](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/screens/NotificationsScreen.tsx): `client/src/screens/NotificationsScreen.tsx`
- [Sign-in client](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/services/auth.service.ts): `client/src/services/auth.service.ts`
- [API client](https://github.com/sachinsh97/mail-tracker/blob/master/client/src/services/http.ts): `client/src/services/http.ts`

### API and identity

- [API routing](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/routes/api-v1.routes.ts): `service/src/routes/api-v1.routes.ts`
- [Authentication](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/auth/auth.service.ts): `service/src/modules/auth/auth.service.ts`
- [Session guard](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/middlewares/authenticate.ts): `service/src/middlewares/authenticate.ts`
- [Tracker endpoints](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/trackers/tracker.controller.ts): `service/src/modules/trackers/tracker.controller.ts`
- [Collection endpoints](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/collections/collection.controller.ts): `service/src/modules/collections/collection.controller.ts`
- [Notification endpoints](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/notifications/notification.controller.ts): `service/src/modules/notifications/notification.controller.ts`

### Open detection

- [Pixel route](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/tracking/tracking.routes.ts): `service/src/modules/tracking/tracking.routes.ts`
- [Pixel handling](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/tracking/tracking.controller.ts): `service/src/modules/tracking/tracking.controller.ts`
- [Hit evaluation](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/tracking/tracking.service.ts): `service/src/modules/tracking/tracking.service.ts`

### Persistence and updates

- **PostgreSQL**
- [Live event stream](https://github.com/sachinsh97/mail-tracker/blob/master/service/src/modules/live-events/live-events.controller.ts): `service/src/modules/live-events/live-events.controller.ts`

### Other components

- **Email sender**
- **Recipient mail app**
- **Google sign-in**

## Connections

- Email sender → Screen routing: uses app
- Screen routing → Create tracker: routes to (evidence: `client/src/router.tsx`)
- Screen routing → Tracker views: routes to (evidence: `client/src/router.tsx`)
- Screen routing → Collections views: routes to (evidence: `client/src/router.tsx`)
- Screen routing → Notifications view: routes to (evidence: `client/src/router.tsx`)
- Create tracker → API client: requests API (evidence: `client/src/hooks/useAddTrackerForm.ts`)
- Sign-in client → API client: sends requests (evidence: `client/src/services/auth.service.ts`)
- Sign-in client → Google sign-in: redirects for sign-in (evidence: `client/src/services/auth.service.ts`)
- API client → API routing: calls API
- API routing → Session guard: guards routes (evidence: `service/src/routes/api-v1.routes.ts`)
- API routing → Tracker endpoints: dispatches tracker routes (evidence: `service/src/routes/api-v1.routes.ts`)
- API routing → Collection endpoints: dispatches collection routes (evidence: `service/src/routes/api-v1.routes.ts`)
- API routing → Notification endpoints: dispatches notifications (evidence: `service/src/routes/api-v1.routes.ts`)
- Tracker endpoints → Hit evaluation: creates trackers (evidence: `service/src/modules/trackers/tracker.controller.ts`)
- Recipient mail app → Pixel route: loads pixel
- Pixel route → Pixel handling: dispatches request (evidence: `service/src/modules/tracking/tracking.routes.ts`)
- Pixel handling → Hit evaluation: handles hit (evidence: `service/src/modules/tracking/tracking.controller.ts`)
- Hit evaluation → PostgreSQL: records hits
- Tracker endpoints → PostgreSQL: persists tracker data
- Collection endpoints → PostgreSQL: persists collections
- Notification endpoints → PostgreSQL: reads notifications
- Live event stream → Email sender: streams updates
- Tracker views → Email sender: shows open history
