# oracle-vfts-352/mirai_hub architecture

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

- Interactive diagram: https://gitdiagram.com/oracle-vfts-352/mirai_hub
- Repository: https://github.com/oracle-vfts-352/mirai_hub

## Overview

Mirai Hub is a feedback platform: users discover projects, follow them, submit and vote on feedback, and developers respond with status updates or official replies. The web app calls an Express API for accounts, projects, posts, feedback, and notifications; a background worker handles asynchronous notification processing. The README documents the database, Redis, object storage, and mail integrations. Some route and service implementations were not excerpted, so their internal call relationships are omitted where the available evidence does not establish them.

Main entry points: [`apps/api/src/app.ts`](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/app.ts) (Express app), [`apps/web/src/api.ts`](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/api.ts) (API client), [`apps/web/src/App.tsx`](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/App.tsx) (Web app), [`apps/api/src/controllers/auth_controller.ts`](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/controllers/auth_controller.ts) (Passkey and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web app<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_ui["Auth context<br/>[auth.tsx]"]
  node_project_ui["Project pages<br/>[ProjectPage.tsx]"]
  node_feedback_ui["Feedback UI"]
  node_post_ui["Project posts<br/>[PostList.tsx]"]
  node_profile_ui["User profiles<br/>[Profile.tsx]"]
  node_notification_ui["Notification UI"]
  node_i18n["Localization<br/>[index.ts]"]
  node_avatar["Avatar display<br/>[Avatar.tsx]"]
  node_project_logo["Project logo display<br/>[ProjectLogo.tsx]"]
  node_date_format["Date formatting<br/>[format.ts]"]
  node_labels["Feedback labels<br/>[labels.ts]"]
end

subgraph group_api["API and domain"]
  node_api_app["Express app<br/>[app.ts]"]
  node_auth_routes["Auth routes<br/>[auth.ts]"]
  node_auth_controller["Passkey and sessions<br/>[auth_controller.ts]"]
  node_auth_middleware["Session checks<br/>[auth.ts]"]
  node_project_routes["Project routes<br/>[projects.ts]"]
  node_feedback_routes["Feedback routes<br/>[feedback.ts]"]
  node_feedback_service["Feedback workflow<br/>[feedback.ts]"]
  node_domain_services["Project, post, user services"]
  node_email_verification["Email verification"]
  node_rate_limit["Rate limiting<br/>[rateLimit.ts]"]
end

subgraph group_async["Notifications"]
  node_outbox["Transactional outbox<br/>[outbox.ts]"]
  node_queue["BullMQ queue<br/>[queue.ts]"]
  node_worker["Notification worker<br/>[run-worker.ts]"]
  node_notifications["Notification service<br/>[notifications.ts]"]
end

subgraph group_infra["Persistence and integrations"]
  node_database[("PostgreSQL")]
  node_redis[("Redis<br/>[redis.ts]")]
  node_storage["Object storage<br/>[storage.ts]"]
  node_mail["SMTP mail<br/>[mail.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"calls"| node_api_client
node_web -->|"provides context"| node_auth_ui
node_project_ui -->|"requests data"| node_api_client
node_project_ui -->|"renders"| node_feedback_ui
node_project_ui -->|"renders"| node_post_ui
node_profile_ui -->|"requests data"| node_api_client
node_feedback_ui -->|"requests data"| node_api_client
node_post_ui -->|"requests data"| node_api_client
node_avatar -->|"uses user data"| node_api_client
node_web -->|"uses translations"| node_i18n
node_date_format -->|"reads locale"| node_i18n
node_web -->|"renders"| node_notification_ui
node_api_client -->|"sends API requests"| node_api_app
node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_project_routes
node_api_app -->|"mounts"| node_feedback_routes
node_api_app -->|"applies limits"| node_rate_limit
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_routes -->|"guards routes"| node_auth_middleware
node_feedback_routes -->|"calls"| node_feedback_service
node_auth_controller -->|"reads and writes"| node_database
node_auth_controller -->|"stores challenges"| node_redis
node_auth_controller -->|"requests verification"| node_email_verification
node_auth_controller -->|"formats media URL"| node_storage
node_auth_middleware -->|"checks token version"| node_database
node_auth_middleware -->|"checks revocation"| node_redis
node_feedback_service -->|"persists feedback"| node_database
node_feedback_service -->|"uses notification queue"| node_queue
node_email_verification -->|"uses"| node_database
node_email_verification -->|"sends email"| node_mail
node_api_app -->|"serves application data"| node_database
node_api_app -->|"uses image storage"| node_storage
node_api_app -->|"uses cache and limits"| node_redis
node_worker -->|"consumes jobs"| node_queue
node_worker -->|"relays events"| node_outbox
node_worker -->|"dispatches processing"| node_notifications
node_outbox -->|"publishes events"| node_queue
node_notifications -->|"creates notifications"| node_database

click node_web "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/App.tsx"
click node_api_client "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/api.ts"
click node_auth_ui "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/auth.tsx"
click node_project_ui "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/pages/ProjectPage.tsx"
click node_feedback_ui "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/FeedbackSection.tsx"
click node_post_ui "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/PostList.tsx"
click node_profile_ui "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/pages/Profile.tsx"
click node_notification_ui "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/NotificationBell.tsx"
click node_i18n "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/i18n/index.ts"
click node_api_app "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/app.ts"
click node_auth_routes "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/routes/auth.ts"
click node_auth_controller "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/controllers/auth_controller.ts"
click node_auth_middleware "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/middleware/auth.ts"
click node_project_routes "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/routes/projects.ts"
click node_feedback_routes "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/routes/feedback.ts"
click node_feedback_service "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/services/feedback.ts"
click node_domain_services "https://github.com/oracle-vfts-352/mirai_hub/tree/main/apps/api/src/services"
click node_email_verification "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/services/emailVerification.ts"
click node_redis "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/redis.ts"
click node_storage "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/storage.ts"
click node_mail "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/mail.ts"
click node_outbox "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/outbox.ts"
click node_queue "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/queue.ts"
click node_worker "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/run-worker.ts"
click node_notifications "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/services/notifications.ts"
click node_avatar "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/Avatar.tsx"
click node_project_logo "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/ProjectLogo.tsx"
click node_date_format "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/i18n/format.ts"
click node_labels "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/labels.ts"
click node_config "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/config.ts"
click node_prisma "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/prisma.ts"
click node_rate_limit "https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/middleware/rateLimit.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_web,node_api_client,node_auth_ui,node_project_ui,node_feedback_ui,node_post_ui,node_profile_ui,node_notification_ui,node_i18n,node_avatar,node_project_logo,node_date_format,node_labels,node_user toneBlue
class node_api_app,node_auth_routes,node_auth_controller,node_auth_middleware,node_project_routes,node_feedback_routes,node_feedback_service,node_domain_services,node_email_verification,node_rate_limit toneAmber
class node_outbox,node_queue,node_worker,node_notifications toneMint
class node_database,node_redis,node_storage,node_mail,node_config,node_prisma toneRose
```

## Components

### Web client

- [Web app](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Auth context](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/auth.tsx): `apps/web/src/auth.tsx`
- [Project pages](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/pages/ProjectPage.tsx): `apps/web/src/pages/ProjectPage.tsx`
- [Feedback UI](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/FeedbackSection.tsx): `apps/web/src/components/FeedbackSection.tsx`
- [Project posts](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/PostList.tsx): `apps/web/src/components/PostList.tsx`
- [User profiles](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/pages/Profile.tsx): `apps/web/src/pages/Profile.tsx`
- [Notification UI](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/NotificationBell.tsx): `apps/web/src/components/NotificationBell.tsx`
- [Localization](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/i18n/index.ts): `apps/web/src/i18n/index.ts`
- [Avatar display](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/Avatar.tsx): `apps/web/src/components/Avatar.tsx`
- [Project logo display](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/components/ProjectLogo.tsx): `apps/web/src/components/ProjectLogo.tsx`
- [Date formatting](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/i18n/format.ts): `apps/web/src/i18n/format.ts`
- [Feedback labels](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/web/src/labels.ts): `apps/web/src/labels.ts`

### API and domain

- [Express app](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Auth routes](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Passkey and sessions](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/controllers/auth_controller.ts): `apps/api/src/controllers/auth_controller.ts`
- [Session checks](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`
- [Project routes](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/routes/projects.ts): `apps/api/src/routes/projects.ts`
- [Feedback routes](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/routes/feedback.ts): `apps/api/src/routes/feedback.ts`
- [Feedback workflow](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/services/feedback.ts): `apps/api/src/services/feedback.ts`
- [Project, post, user services](https://github.com/oracle-vfts-352/mirai_hub/tree/main/apps/api/src/services): `apps/api/src/services`
- [Email verification](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/services/emailVerification.ts): `apps/api/src/services/emailVerification.ts`
- [Rate limiting](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/middleware/rateLimit.ts): `apps/api/src/middleware/rateLimit.ts`

### Notifications

- [Transactional outbox](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/outbox.ts): `apps/api/src/lib/outbox.ts`
- [BullMQ queue](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/queue.ts): `apps/api/src/lib/queue.ts`
- [Notification worker](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/run-worker.ts): `apps/api/src/run-worker.ts`
- [Notification service](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/services/notifications.ts): `apps/api/src/services/notifications.ts`

### Persistence and integrations

- **PostgreSQL**
- [Redis](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/redis.ts): `apps/api/src/lib/redis.ts`
- [Object storage](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/storage.ts): `apps/api/src/lib/storage.ts`
- [SMTP mail](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/mail.ts): `apps/api/src/lib/mail.ts`
- [Runtime config](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/config.ts): `apps/api/src/lib/config.ts`
- [Prisma client](https://github.com/oracle-vfts-352/mirai_hub/blob/main/apps/api/src/lib/prisma.ts): `apps/api/src/lib/prisma.ts`

### Other components

- **User**

## Connections

- User → Web app: uses (evidence: `README.md`)
- Web app → API client: calls
- Web app → Auth context: provides context (evidence: `apps/web/src/App.tsx`)
- Project pages → API client: requests data (evidence: `apps/web/src/pages/ProjectPage.tsx`)
- Project pages → Feedback UI: renders (evidence: `apps/web/src/pages/ProjectPage.tsx`)
- Project pages → Project posts: renders (evidence: `apps/web/src/pages/ProjectPage.tsx`)
- User profiles → API client: requests data (evidence: `apps/web/src/pages/Profile.tsx`)
- Feedback UI → API client: requests data (evidence: `apps/web/src/components/FeedbackSection.tsx`)
- Project posts → API client: requests data (evidence: `apps/web/src/components/PostList.tsx`)
- Avatar display → API client: uses user data
- Web app → Localization: uses translations (evidence: `apps/web/src/main.tsx`)
- Date formatting → Localization: reads locale (evidence: `apps/web/src/i18n/format.ts`)
- Web app → Notification UI: renders (evidence: `apps/web/src/App.tsx`)
- API client → Express app: sends API requests (evidence: `README.md`)
- Express app → Auth routes: mounts (evidence: `apps/api/src/app.ts`)
- Express app → Project routes: mounts (evidence: `apps/api/src/app.ts`)
- Express app → Feedback routes: mounts (evidence: `apps/api/src/app.ts`)
- Express app → Rate limiting: applies limits (evidence: `apps/api/src/app.ts`)
- Auth routes → Passkey and sessions: dispatches (evidence: `apps/api/src/routes/auth.ts`)
- Auth routes → Session checks: guards routes (evidence: `apps/api/src/routes/auth.ts`)
- Feedback routes → Feedback workflow: calls (evidence: `apps/api/src/routes/feedback.ts`)
- Passkey and sessions → PostgreSQL: reads and writes (evidence: `apps/api/src/controllers/auth_controller.ts`)
- Passkey and sessions → Redis: stores challenges (evidence: `apps/api/src/controllers/auth_controller.ts`)
- Passkey and sessions → Email verification: requests verification (evidence: `apps/api/src/controllers/auth_controller.ts`)
- Passkey and sessions → Object storage: formats media URL (evidence: `apps/api/src/controllers/auth_controller.ts`)
- Session checks → PostgreSQL: checks token version (evidence: `apps/api/src/middleware/auth.ts`)
- Session checks → Redis: checks revocation (evidence: `apps/api/src/middleware/auth.ts`)
- Feedback workflow → PostgreSQL: persists feedback (evidence: `apps/api/src/services/feedback.ts`)
- Feedback workflow → BullMQ queue: uses notification queue (evidence: `apps/api/src/services/feedback.ts`)
- Email verification → PostgreSQL: uses (evidence: `apps/api/src/services/emailVerification.ts`)
- Email verification → SMTP mail: sends email (evidence: `apps/api/src/services/emailVerification.ts`)
- Express app → PostgreSQL: serves application data (evidence: `README.md`)
- Express app → Object storage: uses image storage (evidence: `README.md`)
- Express app → Redis: uses cache and limits (evidence: `README.md`)
- Notification worker → BullMQ queue: consumes jobs (evidence: `apps/api/src/run-worker.ts`)
- Notification worker → Transactional outbox: relays events (evidence: `apps/api/src/run-worker.ts`)
- Notification worker → Notification service: dispatches processing (evidence: `apps/api/src/run-worker.ts`)
- Transactional outbox → BullMQ queue: publishes events (evidence: `README.md`)
- Notification service → PostgreSQL: creates notifications (evidence: `README.md`)