# anshumgupta3001/letterfromhearts architecture

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

- Interactive diagram: https://gitdiagram.com/anshumgupta3001/letterfromhearts
- Repository: https://github.com/anshumgupta3001/letterfromhearts

## Overview

Letter from Heart is a web app for writing and sharing personal, known-recipient, and “Caring Stranger” letters, then listening to or conversing with others. Users enter through authentication, navigate letter-writing and inbox/feed experiences, and can track opens, manage connections, and report issues; administrators have a separate dashboard. The server exposes these features through Express routes and controllers backed by MongoDB models, with email and notification workers for asynchronous delivery. The README provides no product detail, and unsampled page, route, and worker implementations limit which internal links can be asserted.

Main entry points: [`client/src/App.jsx`](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/App.jsx) (Page router), [`server/app.js`](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/app.js) (HTTP application), [`server/controllers/letterController.js`](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/letterController.js) (Letter domain), [`server/controllers/replyController.js`](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/replyController.js) (Conversation domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Page router<br/>[App.jsx]"]
  node_context["App state<br/>[AppContext.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_authui["Authentication UI<br/>[AuthPage.jsx]"]
end

subgraph group_letters["Letter experiences"]
  node_writeui["Write letters<br/>[WritePage.jsx]"]
  node_letterui["Letter views<br/>[MyLettersPage.jsx]"]
  node_listenui["Listen and claim<br/>[ListenPage.jsx]"]
  node_replyui["Replies<br/>[MyRepliesPage.jsx]"]
  node_sentui["Known letters"]
end

subgraph group_server["API and domain"]
  node_serverapp["HTTP application<br/>[app.js]"]
  node_authroutes["Authentication routes<br/>[authRoutes.js]"]
  node_letterroutes["Letter routes<br/>[letterRoutes.js]"]
  node_replyroutes["Reply routes<br/>[replyRoutes.js]"]
  node_letterctl["Letter domain"]
  node_replyctl["Conversation domain<br/>[replyController.js]"]
  node_notifyctl["Notifications"]
  node_models[("MongoDB models<br/>[Letter.js]")]
  node_moderation["Content moderation<br/>[moderation.js]"]
end

subgraph group_operations["Delivery and oversight"]
  node_adminui["Admin dashboard"]
  node_reportroutes["Report routes<br/>[reportRoutes.js]"]
  node_mailworker["Email workers"]
  node_webhook["Email event webhook"]
  node_reportctl["Report handling"]
end

node_user(("Seeker or listener"))
node_resend["Resend email service"]

node_user -->|"uses"| node_app
node_app -->|"provides state"| node_context
node_app -->|"renders"| node_authui
node_app -->|"routes to"| node_writeui
node_app -->|"routes to"| node_letterui
node_app -->|"routes to"| node_listenui
node_app -->|"routes to"| node_replyui
node_app -->|"routes to"| node_sentui
node_app -->|"routes to"| node_adminui
node_serverapp -->|"mounts"| node_authroutes
node_serverapp -->|"mounts"| node_letterroutes
node_serverapp -->|"mounts"| node_replyroutes
node_serverapp -->|"mounts"| node_reportroutes
node_letterroutes -->|"dispatches"| node_letterctl
node_replyroutes -->|"dispatches"| node_replyctl
node_reportroutes -->|"dispatches"| node_reportctl
node_letterctl -->|"reads and writes"| node_models
node_replyctl -->|"reads and writes"| node_models
node_letterctl -->|"checks content"| node_moderation
node_replyctl -->|"checks content"| node_moderation
node_letterctl -->|"creates alerts"| node_notifyctl
node_replyctl -->|"creates alerts"| node_notifyctl
node_mailworker -->|"reads notifications"| node_models
node_mailworker -->|"sends email"| node_resend
node_resend -.->|"posts events"| node_webhook
node_webhook -->|"updates delivery"| node_models

click node_app "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/App.jsx"
click node_context "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/context/AppContext.jsx"
click node_api "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/utils/api.js"
click node_authui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/AuthPage.jsx"
click node_writeui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/WritePage.jsx"
click node_letterui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/MyLettersPage.jsx"
click node_listenui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/ListenPage.jsx"
click node_replyui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/MyRepliesPage.jsx"
click node_sentui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/SentLettersPage.jsx"
click node_adminui "https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/AdminDashboardPage.jsx"
click node_serverapp "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/app.js"
click node_authroutes "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/authRoutes.js"
click node_letterroutes "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/letterRoutes.js"
click node_replyroutes "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/replyRoutes.js"
click node_reportroutes "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/reportRoutes.js"
click node_letterctl "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/letterController.js"
click node_replyctl "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/replyController.js"
click node_notifyctl "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/notificationController.js"
click node_models "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/models/Letter.js"
click node_moderation "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/utils/moderation.js"
click node_mailworker "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/worker/notificationEmailWorker.js"
click node_webhook "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/resendWebhookRoutes.js"
click node_reportctl "https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/reportController.js"

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_app,node_context,node_api,node_authui toneBlue
class node_writeui,node_letterui,node_listenui,node_replyui,node_sentui toneAmber
class node_serverapp,node_authroutes,node_letterroutes,node_replyroutes,node_letterctl,node_replyctl,node_notifyctl,node_models,node_moderation toneMint
class node_adminui,node_reportroutes,node_mailworker,node_webhook,node_reportctl toneRose
class node_user,node_resend toneIndigo
```

## Components

### Web client

- [Page router](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [App state](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/context/AppContext.jsx): `client/src/context/AppContext.jsx`
- [API client](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/utils/api.js): `client/src/utils/api.js`
- [Authentication UI](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/AuthPage.jsx): `client/src/pages/AuthPage.jsx`

### Letter experiences

- [Write letters](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/WritePage.jsx): `client/src/pages/WritePage.jsx`
- [Letter views](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/MyLettersPage.jsx): `client/src/pages/MyLettersPage.jsx`
- [Listen and claim](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/ListenPage.jsx): `client/src/pages/ListenPage.jsx`
- [Replies](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/MyRepliesPage.jsx): `client/src/pages/MyRepliesPage.jsx`
- [Known letters](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/SentLettersPage.jsx): `client/src/pages/SentLettersPage.jsx`

### API and domain

- [HTTP application](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/app.js): `server/app.js`
- [Authentication routes](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/authRoutes.js): `server/routes/authRoutes.js`
- [Letter routes](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/letterRoutes.js): `server/routes/letterRoutes.js`
- [Reply routes](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/replyRoutes.js): `server/routes/replyRoutes.js`
- [Letter domain](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/letterController.js): `server/controllers/letterController.js`
- [Conversation domain](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/replyController.js): `server/controllers/replyController.js`
- [Notifications](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/notificationController.js): `server/controllers/notificationController.js`
- [MongoDB models](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/models/Letter.js): `server/models/Letter.js`
- [Content moderation](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/utils/moderation.js): `server/utils/moderation.js`

### Delivery and oversight

- [Admin dashboard](https://github.com/anshumgupta3001/letterfromhearts/blob/main/client/src/pages/AdminDashboardPage.jsx): `client/src/pages/AdminDashboardPage.jsx`
- [Report routes](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/reportRoutes.js): `server/routes/reportRoutes.js`
- [Email workers](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/worker/notificationEmailWorker.js): `server/worker/notificationEmailWorker.js`
- [Email event webhook](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/routes/resendWebhookRoutes.js): `server/routes/resendWebhookRoutes.js`
- [Report handling](https://github.com/anshumgupta3001/letterfromhearts/blob/main/server/controllers/reportController.js): `server/controllers/reportController.js`

### Other components

- **Seeker or listener**
- **Resend email service**

## Connections

- Seeker or listener → Page router: uses
- Page router → App state: provides state
- Page router → Authentication UI: renders
- Page router → Write letters: routes to
- Page router → Letter views: routes to
- Page router → Listen and claim: routes to
- Page router → Replies: routes to
- Page router → Known letters: routes to
- Page router → Admin dashboard: routes to
- HTTP application → Authentication routes: mounts
- HTTP application → Letter routes: mounts
- HTTP application → Reply routes: mounts
- HTTP application → Report routes: mounts
- Letter routes → Letter domain: dispatches
- Reply routes → Conversation domain: dispatches
- Report routes → Report handling: dispatches
- Letter domain → MongoDB models: reads and writes
- Conversation domain → MongoDB models: reads and writes
- Letter domain → Content moderation: checks content
- Conversation domain → Content moderation: checks content
- Letter domain → Notifications: creates alerts
- Conversation domain → Notifications: creates alerts
- Email workers → MongoDB models: reads notifications
- Email workers → Resend email service: sends email
- Resend email service → Email event webhook: posts events
- Email event webhook → MongoDB models: updates delivery