# hypeplugyoo/spamhot architecture

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

- Interactive diagram: https://gitdiagram.com/hypeplugyoo/spamhot
- Repository: https://github.com/hypeplugyoo/spamhot

## Overview

Pulso Social is an early-stage, organization-scoped social-content management SaaS. The implemented user workflow is registration/login, then managing disconnected Instagram profile records, groups and private media uploads; the dashboard is demo-only. A separate BullMQ worker and session service are present, but publishing, real Instagram access and metric collection are explicitly disabled. The worker and session internals are only partly evidenced by the excerpts, so those links are limited to visible calls and README statements.

Main entry points: [`src/lib/auth.ts`](https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/auth.ts) (Session and identity), [`src/worker/index.ts`](https://github.com/hypeplugyoo/spamhot/blob/main/src/worker/index.ts) (Job worker), [`src/app/api/media/route.ts`](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/route.ts) (Media library), [`src/app/api/media/presign/route.ts`](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/presign/route.ts) (Upload preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_authform["Login and signup<br/>[auth-form.tsx]"]
  node_authapi["Authentication endpoints"]
  node_auth["Session and identity<br/>[auth.ts]"]
  node_dashboard["Demo dashboard<br/>[dashboard.tsx]"]
end

subgraph group_domain["Organization content"]
  node_domainmodel["Content domain model<br/>[domain.ts]"]
  node_accountapi["Instagram profile endpoints"]
  node_groupapi["Account groups<br/>[route.ts]"]
  node_mediaapi["Media library<br/>[route.ts]"]
  node_upload["Upload preparation<br/>[route.ts]"]
  node_validation["Upload verification<br/>[route.ts]"]
end

subgraph group_runtime["Background runtime"]
  node_queues["Job queues<br/>[queues.ts]"]
  node_worker["Job worker<br/>[index.ts]"]
  node_lease["Account lease<br/>[account-lock.ts]"]
  node_adapter["Instagram adapter"]
  node_metrics["Metric definitions<br/>[metrics.ts]"]
  node_sessionservice["Session service<br/>[index.ts]"]
end

subgraph group_infra["Persistence and storage"]
  node_db[("PostgreSQL")]
  node_redis[("Redis")]
  node_minio[("S3-compatible storage")]
end

node_user(("User"))

node_user -->|"enters credentials"| node_authform
node_authform -->|"submits to"| node_authapi
node_authapi -->|"creates sessions"| node_auth
node_auth -->|"reads and writes"| node_db
node_user -.->|"views workspace"| node_dashboard
node_dashboard -->|"uses demo data"| node_domainmodel
node_accountapi -->|"requires identity"| node_auth
node_accountapi -->|"reads and records profiles"| node_db
node_groupapi -->|"requires identity"| node_auth
node_groupapi -->|"reads and writes groups"| node_db
node_mediaapi -->|"requires identity"| node_auth
node_mediaapi -->|"reads ready media"| node_db
node_mediaapi -->|"signs download URL"| node_minio
node_upload -->|"requires identity"| node_auth
node_upload -->|"records upload"| node_db
node_upload -->|"signs upload URL"| node_minio
node_validation -->|"requires identity"| node_auth
node_validation -->|"checks and updates media"| node_db
node_validation -->|"validates uploaded object"| node_minio
node_queues -.->|"uses BullMQ queues"| node_redis
node_worker -->|"acquires and releases"| node_lease
node_worker -->|"dispatches operations"| node_adapter
node_worker -->|"connects for jobs and leases"| node_redis
node_worker -.->|"consumes publication and metric jobs"| node_queues
node_sessionservice -.->|"serves private session channel"| node_user
node_metrics -->|"uses metric types"| node_domainmodel

click node_authform "https://github.com/hypeplugyoo/spamhot/blob/main/src/app/ui/auth-form.tsx"
click node_authapi "https://github.com/hypeplugyoo/spamhot/tree/main/src/app/api/auth"
click node_auth "https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/auth.ts"
click node_dashboard "https://github.com/hypeplugyoo/spamhot/blob/main/src/app/dashboard.tsx"
click node_domainmodel "https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/domain.ts"
click node_accountapi "https://github.com/hypeplugyoo/spamhot/tree/main/src/app/api/instagram/accounts"
click node_groupapi "https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/groups/route.ts"
click node_mediaapi "https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/route.ts"
click node_upload "https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/presign/route.ts"
click node_validation "https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/%5Bid%5D/complete/route.ts"
click node_queues "https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/queues.ts"
click node_worker "https://github.com/hypeplugyoo/spamhot/blob/main/src/worker/index.ts"
click node_lease "https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/account-lock.ts"
click node_adapter "https://github.com/hypeplugyoo/spamhot/blob/main/src/worker/instagram-adapter.ts"
click node_metrics "https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/metrics.ts"
click node_sessionservice "https://github.com/hypeplugyoo/spamhot/blob/main/src/session/index.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_authform,node_authapi,node_auth,node_dashboard,node_user toneBlue
class node_domainmodel,node_accountapi,node_groupapi,node_mediaapi,node_upload,node_validation toneAmber
class node_queues,node_worker,node_lease,node_adapter,node_metrics,node_sessionservice toneMint
class node_db,node_redis,node_minio toneRose
```

## Components

### Web experience

- [Login and signup](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/ui/auth-form.tsx): `src/app/ui/auth-form.tsx`
- [Authentication endpoints](https://github.com/hypeplugyoo/spamhot/tree/main/src/app/api/auth): `src/app/api/auth`
- [Session and identity](https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Demo dashboard](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/dashboard.tsx): `src/app/dashboard.tsx`

### Organization content

- [Content domain model](https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/domain.ts): `src/lib/domain.ts`
- [Instagram profile endpoints](https://github.com/hypeplugyoo/spamhot/tree/main/src/app/api/instagram/accounts): `src/app/api/instagram/accounts`
- [Account groups](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/groups/route.ts): `src/app/api/groups/route.ts`
- [Media library](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/route.ts): `src/app/api/media/route.ts`
- [Upload preparation](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/presign/route.ts): `src/app/api/media/presign/route.ts`
- [Upload verification](https://github.com/hypeplugyoo/spamhot/blob/main/src/app/api/media/%5Bid%5D/complete/route.ts): `src/app/api/media/[id]/complete/route.ts`

### Background runtime

- [Job queues](https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/queues.ts): `src/lib/queues.ts`
- [Job worker](https://github.com/hypeplugyoo/spamhot/blob/main/src/worker/index.ts): `src/worker/index.ts`
- [Account lease](https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/account-lock.ts): `src/lib/account-lock.ts`
- [Instagram adapter](https://github.com/hypeplugyoo/spamhot/blob/main/src/worker/instagram-adapter.ts): `src/worker/instagram-adapter.ts`
- [Metric definitions](https://github.com/hypeplugyoo/spamhot/blob/main/src/lib/metrics.ts): `src/lib/metrics.ts`
- [Session service](https://github.com/hypeplugyoo/spamhot/blob/main/src/session/index.ts): `src/session/index.ts`

### Persistence and storage

- **PostgreSQL**
- **Redis**
- **S3-compatible storage**

### Other components

- **User**

## Connections

- User → Login and signup: enters credentials (evidence: `src/app/ui/auth-form.tsx`)
- Login and signup → Authentication endpoints: submits to (evidence: `src/app/ui/auth-form.tsx`)
- Authentication endpoints → Session and identity: creates sessions (evidence: `src/app/api/auth/register/route.ts`)
- Session and identity → PostgreSQL: reads and writes (evidence: `src/lib/auth.ts`)
- User → Demo dashboard: views workspace (evidence: `README.md`)
- Demo dashboard → Content domain model: uses demo data (evidence: `src/app/dashboard.tsx`)
- Instagram profile endpoints → Session and identity: requires identity (evidence: `src/app/api/instagram/accounts/route.ts`)
- Instagram profile endpoints → PostgreSQL: reads and records profiles (evidence: `src/app/api/instagram/accounts/route.ts`)
- Account groups → Session and identity: requires identity (evidence: `src/app/api/groups/route.ts`)
- Account groups → PostgreSQL: reads and writes groups (evidence: `src/app/api/groups/route.ts`)
- Media library → Session and identity: requires identity (evidence: `src/app/api/media/route.ts`)
- Media library → PostgreSQL: reads ready media (evidence: `src/app/api/media/route.ts`)
- Media library → S3-compatible storage: signs download URL (evidence: `src/app/api/media/route.ts`)
- Upload preparation → Session and identity: requires identity (evidence: `src/app/api/media/presign/route.ts`)
- Upload preparation → PostgreSQL: records upload (evidence: `src/app/api/media/presign/route.ts`)
- Upload preparation → S3-compatible storage: signs upload URL (evidence: `src/app/api/media/presign/route.ts`)
- Upload verification → Session and identity: requires identity (evidence: `src/app/api/media/[id]/complete/route.ts`)
- Upload verification → PostgreSQL: checks and updates media (evidence: `src/app/api/media/[id]/complete/route.ts`)
- Upload verification → S3-compatible storage: validates uploaded object (evidence: `src/app/api/media/[id]/complete/route.ts`)
- Job queues → Redis: uses BullMQ queues (evidence: `README.md`)
- Job worker → Account lease: acquires and releases (evidence: `src/worker/index.ts`)
- Job worker → Instagram adapter: dispatches operations (evidence: `src/worker/index.ts`)
- Job worker → Redis: connects for jobs and leases (evidence: `src/worker/index.ts`)
- Job worker → Job queues: consumes publication and metric jobs (evidence: `README.md`)
- Session service → User: serves private session channel (evidence: `README.md`)
- Metric definitions → Content domain model: uses metric types (evidence: `src/lib/metrics.ts`)