# voidqn/gspen-hub architecture

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

- Interactive diagram: https://gitdiagram.com/voidqn/gspen-hub
- Repository: https://github.com/voidqn/gspen-hub

## Overview

GSPen Hub is a multi-workspace business app spanning contact data and CRM, campaign outreach, connected mail, project management, and a separately deployable email verifier. The main outreach path is campaign setup and recipient selection, followed by assignment and message composition, then queued sending; the sampled pipeline directly supports the assignment/composition stage. Invoice Ninja webhooks feed CRM ingestion, and unsubscribe links let recipients change suppression state. The README is only the stock Next.js starter, so product capabilities and wiring are inferred from the repository tree and sampled source; unsampled links are omitted.

Main entry points: [`src/db/db.ts`](https://github.com/voidqn/gspen-hub/blob/main/src/db/db.ts) (PostgreSQL), [`src/lib/outreach/pipeline.ts`](https://github.com/voidqn/gspen-hub/blob/main/src/lib/outreach/pipeline.ts) (Assign and compose), [`src/lib/mail`](https://github.com/voidqn/gspen-hub/tree/main/src/lib/mail) (Mail sync and replies), [`src/app/(app)/email/campaigns`](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/email/campaigns) (Campaign workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Hub application"]
  node_app_ui["Workspace UI"]
  node_auth["Sessions and access"]
  node_project_ui["Project management"]
end

subgraph group_crm["Contacts and CRM"]
  node_database_ui["Contact database"]
  node_database_ops["Import and tables"]
  node_crm_ui["CRM review"]
  node_crm_ingest["Invoice ingestion<br/>[ingest.ts]"]
end

subgraph group_outreach["Campaign outreach"]
  node_outreach_ui["Campaign workspace"]
  node_segments["Audience segments"]
  node_pipeline["Assign and compose<br/>[pipeline.ts]"]
  node_queue["Send queue<br/>[sender.ts]"]
  node_sender_job["Sender worker<br/>[sender.ts]"]
end

subgraph group_mail["Mail operations"]
  node_mail_ui["Inbox and reports"]
  node_mail_ops["Mail sync and replies"]
  node_mail_sync_job["Mail sync job<br/>[mail-sync.ts]"]
  node_unsubscribe["Unsubscribe handler<br/>[route.ts]"]
end

subgraph group_verification["Email verification"]
  node_verifier_ui["Verifier tools<br/>[page.tsx]"]
  node_verifier_routes["Verifier API routes"]
  node_verifier_proxy["Verifier client<br/>[proxy.ts]"]
  node_verifier_service["Verifier HTTP service<br/>[main.py]"]
  node_verifier_core["Probe and generate"]
end

node_user(("Hub user"))
node_invoice_hook["Invoice Ninja webhook<br/>[route.ts]"]
node_database[("PostgreSQL<br/>[db.ts]")]
node_gmail["Gmail"]
node_smtp["Recipient mail servers"]
node_invoice_service["Invoice Ninja"]

node_user -->|"uses"| node_app_ui
node_app_ui -->|"checks access"| node_auth
node_database_ui -->|"imports and edits"| node_database_ops
node_database_ops -->|"reads and writes"| node_database
node_crm_ui -->|"loads CRM data"| node_database
node_invoice_service -->|"posts events"| node_invoice_hook
node_invoice_hook -->|"ingests payload"| node_crm_ingest
node_crm_ingest -->|"stores and matches"| node_database
node_outreach_ui -->|"configures audience"| node_segments
node_outreach_ui -->|"starts campaign"| node_pipeline
node_pipeline -->|"loads and updates"| node_database
node_pipeline -->|"composes messages"| node_queue
node_sender_job -->|"processes sends"| node_queue
node_mail_ui -->|"manages conversations"| node_mail_ops
node_mail_ops -->|"syncs and replies"| node_gmail
node_mail_sync_job -->|"runs sync"| node_mail_ops
node_unsubscribe -->|"updates suppression"| node_database
node_verifier_ui -->|"requests checks"| node_verifier_routes
node_verifier_routes -->|"proxies requests"| node_verifier_proxy
node_verifier_proxy -.->|"calls API"| node_verifier_service
node_verifier_service -->|"runs verification"| node_verifier_core
node_verifier_core -->|"probes MX hosts"| node_smtp
node_user -->|"manages projects"| node_project_ui

click node_app_ui "https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)"
click node_auth "https://github.com/voidqn/gspen-hub/tree/main/src/lib/auth"
click node_database_ui "https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/database"
click node_database_ops "https://github.com/voidqn/gspen-hub/tree/main/src/lib/database"
click node_crm_ui "https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/crm"
click node_crm_ingest "https://github.com/voidqn/gspen-hub/blob/main/src/lib/crm/ingest.ts"
click node_invoice_hook "https://github.com/voidqn/gspen-hub/blob/main/src/app/api/webhooks/invoice-ninja/route.ts"
click node_outreach_ui "https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/email/campaigns"
click node_segments "https://github.com/voidqn/gspen-hub/tree/main/src/lib/segments"
click node_pipeline "https://github.com/voidqn/gspen-hub/blob/main/src/lib/outreach/pipeline.ts"
click node_queue "https://github.com/voidqn/gspen-hub/blob/main/src/lib/outreach/sender.ts"
click node_sender_job "https://github.com/voidqn/gspen-hub/blob/main/scripts/sender.ts"
click node_mail_ui "https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/email"
click node_mail_ops "https://github.com/voidqn/gspen-hub/tree/main/src/lib/mail"
click node_mail_sync_job "https://github.com/voidqn/gspen-hub/blob/main/scripts/mail-sync.ts"
click node_unsubscribe "https://github.com/voidqn/gspen-hub/blob/main/src/app/unsubscribe/%5Btoken%5D/route.ts"
click node_verifier_ui "https://github.com/voidqn/gspen-hub/blob/main/src/app/(app)/email/verifier/page.tsx"
click node_verifier_routes "https://github.com/voidqn/gspen-hub/tree/main/src/app/api/verifier"
click node_verifier_proxy "https://github.com/voidqn/gspen-hub/blob/main/src/lib/verifier/proxy.ts"
click node_verifier_service "https://github.com/voidqn/gspen-hub/blob/main/services/verifier/api/main.py"
click node_verifier_core "https://github.com/voidqn/gspen-hub/tree/main/services/verifier/core"
click node_database "https://github.com/voidqn/gspen-hub/blob/main/src/db/db.ts"
click node_project_ui "https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/project-management"

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_ui,node_auth,node_project_ui,node_user toneBlue
class node_database_ui,node_database_ops,node_crm_ui,node_crm_ingest,node_database toneAmber
class node_outreach_ui,node_segments,node_pipeline,node_queue,node_sender_job,node_invoice_hook,node_smtp toneMint
class node_mail_ui,node_mail_ops,node_mail_sync_job,node_unsubscribe toneRose
class node_verifier_ui,node_verifier_routes,node_verifier_proxy,node_verifier_service,node_verifier_core,node_gmail,node_invoice_service toneIndigo
```

## Components

### Hub application

- [Workspace UI](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)): `src/app/(app)`
- [Sessions and access](https://github.com/voidqn/gspen-hub/tree/main/src/lib/auth): `src/lib/auth`
- [Project management](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/project-management): `src/app/(app)/project-management`

### Contacts and CRM

- [Contact database](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/database): `src/app/(app)/database`
- [Import and tables](https://github.com/voidqn/gspen-hub/tree/main/src/lib/database): `src/lib/database`
- [CRM review](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/crm): `src/app/(app)/crm`
- [Invoice ingestion](https://github.com/voidqn/gspen-hub/blob/main/src/lib/crm/ingest.ts): `src/lib/crm/ingest.ts`

### Campaign outreach

- [Campaign workspace](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/email/campaigns): `src/app/(app)/email/campaigns`
- [Audience segments](https://github.com/voidqn/gspen-hub/tree/main/src/lib/segments): `src/lib/segments`
- [Assign and compose](https://github.com/voidqn/gspen-hub/blob/main/src/lib/outreach/pipeline.ts): `src/lib/outreach/pipeline.ts`
- [Send queue](https://github.com/voidqn/gspen-hub/blob/main/src/lib/outreach/sender.ts): `src/lib/outreach/sender.ts`
- [Sender worker](https://github.com/voidqn/gspen-hub/blob/main/scripts/sender.ts): `scripts/sender.ts`

### Mail operations

- [Inbox and reports](https://github.com/voidqn/gspen-hub/tree/main/src/app/(app)/email): `src/app/(app)/email`
- [Mail sync and replies](https://github.com/voidqn/gspen-hub/tree/main/src/lib/mail): `src/lib/mail`
- [Mail sync job](https://github.com/voidqn/gspen-hub/blob/main/scripts/mail-sync.ts): `scripts/mail-sync.ts`
- [Unsubscribe handler](https://github.com/voidqn/gspen-hub/blob/main/src/app/unsubscribe/%5Btoken%5D/route.ts): `src/app/unsubscribe/[token]/route.ts`

### Email verification

- [Verifier tools](https://github.com/voidqn/gspen-hub/blob/main/src/app/(app)/email/verifier/page.tsx): `src/app/(app)/email/verifier/page.tsx`
- [Verifier API routes](https://github.com/voidqn/gspen-hub/tree/main/src/app/api/verifier): `src/app/api/verifier`
- [Verifier client](https://github.com/voidqn/gspen-hub/blob/main/src/lib/verifier/proxy.ts): `src/lib/verifier/proxy.ts`
- [Verifier HTTP service](https://github.com/voidqn/gspen-hub/blob/main/services/verifier/api/main.py): `services/verifier/api/main.py`
- [Probe and generate](https://github.com/voidqn/gspen-hub/tree/main/services/verifier/core): `services/verifier/core`

### Other components

- **Hub user**
- [Invoice Ninja webhook](https://github.com/voidqn/gspen-hub/blob/main/src/app/api/webhooks/invoice-ninja/route.ts): `src/app/api/webhooks/invoice-ninja/route.ts`
- [PostgreSQL](https://github.com/voidqn/gspen-hub/blob/main/src/db/db.ts): `src/db/db.ts`
- **Gmail**
- **Recipient mail servers**
- **Invoice Ninja**

## Connections

- Hub user → Workspace UI: uses
- Workspace UI → Sessions and access: checks access
- Contact database → Import and tables: imports and edits
- Import and tables → PostgreSQL: reads and writes
- CRM review → PostgreSQL: loads CRM data
- Invoice Ninja → Invoice Ninja webhook: posts events
- Invoice Ninja webhook → Invoice ingestion: ingests payload
- Invoice ingestion → PostgreSQL: stores and matches
- Campaign workspace → Audience segments: configures audience
- Campaign workspace → Assign and compose: starts campaign
- Assign and compose → PostgreSQL: loads and updates
- Assign and compose → Send queue: composes messages
- Sender worker → Send queue: processes sends
- Inbox and reports → Mail sync and replies: manages conversations
- Mail sync and replies → Gmail: syncs and replies
- Mail sync job → Mail sync and replies: runs sync
- Unsubscribe handler → PostgreSQL: updates suppression
- Verifier tools → Verifier API routes: requests checks
- Verifier API routes → Verifier client: proxies requests
- Verifier client → Verifier HTTP service: calls API
- Verifier HTTP service → Probe and generate: runs verification
- Probe and generate → Recipient mail servers: probes MX hosts
- Hub user → Project management: manages projects