# nyllon-software/signudoc architecture

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

- Interactive diagram: https://gitdiagram.com/nyllon-software/signudoc
- Repository: https://github.com/nyllon-software/signudoc

## Overview

SignuDoc is a self-hosted electronic-signature application. The main workflow is: an authenticated sender uploads a PDF, prepares an envelope with ordered signers and fields, sends signing links, and signers complete it without accounts; the finished PDF and audit certificate are sealed, stored, and made downloadable and publicly verifiable. Templates, dashboard tracking, organizational administration, branding, and security are parallel product capabilities. Several connections below reflect README-documented behavior; unsampled route and service internals are represented at their existing directory paths.

Main entry points: [`src/lib/signing.ts`](https://github.com/nyllon-software/signudoc/blob/main/src/lib/signing.ts) (Signing workflow), [`src/lib/db/connection.ts`](https://github.com/nyllon-software/signudoc/blob/main/src/lib/db/connection.ts) (Postgres database), [`src/components/envelopes`](https://github.com/nyllon-software/signudoc/tree/main/src/components/envelopes) (Envelope preparation), [`src/lib/envelopes.ts`](https://github.com/nyllon-software/signudoc/blob/main/src/lib/envelopes.ts) (Envelope workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Envelope authoring"]
  node_dashboard["Dashboard"]
  node_envelope_ui["Envelope preparation"]
  node_envelope_routes["Envelope endpoints"]
  node_envelope_domain["Envelope workflow<br/>[envelopes.ts]"]
  node_template_ui["Template screens"]
  node_template_routes["Template endpoints"]
end

subgraph group_identity["Identity and administration"]
  node_auth_ui["Account screens"]
  node_auth_server["Authentication<br/>[server.ts]"]
  node_admin_ui["Organization settings"]
  node_admin_routes["Admin endpoints"]
  node_settings["Application settings<br/>[settings.ts]"]
end

subgraph group_signing["Signing and evidence"]
  node_signing_ui["Signing screens"]
  node_signing_routes["Signing endpoints"]
  node_signing_domain["Signing workflow<br/>[signing.ts]"]
  node_audit["Audit trail<br/>[audit.ts]"]
  node_pdf_seal["PDF sealing<br/>[pdf-seal.ts]"]
end

subgraph group_documents["Document access"]
  node_verify_page["Verify page<br/>[page.tsx]"]
  node_verify_api["Verify endpoint<br/>[route.ts]"]
  node_download_routes["Download endpoints"]
end

subgraph group_platform["Persistence and services"]
  node_email["Email delivery<br/>[email.ts]"]
  node_storage["PDF storage<br/>[storage.ts]"]
  node_database[("Postgres database<br/>[connection.ts]")]
end

node_sender(("Sender"))
node_signer(("Signer"))

node_sender -->|"signs in"| node_auth_ui
node_auth_ui -->|"authenticates"| node_auth_server
node_sender -->|"prepares PDF"| node_envelope_ui
node_envelope_ui -->|"uploads draft"| node_envelope_routes
node_envelope_routes -->|"creates draft"| node_envelope_domain
node_envelope_domain -.->|"stores documents"| node_storage
node_envelope_domain -.->|"persists envelope"| node_database
node_envelope_ui -->|"saves template"| node_template_routes
node_template_routes -.->|"persists templates"| node_database
node_sender -->|"tracks envelopes"| node_dashboard
node_dashboard -.->|"loads envelope data"| node_envelope_routes
node_sender -->|"sends envelope"| node_signing_routes
node_signing_routes -.->|"handles signing"| node_signing_domain
node_signing_domain -.->|"records events"| node_audit
node_signing_domain -->|"finalizes signed PDF"| node_pdf_seal
node_signing_domain -->|"delivers signing links"| node_email
node_signer -->|"opens signing link"| node_signing_ui
node_signing_ui -.->|"submits signature"| node_signing_routes
node_signing_domain -->|"stores completed PDF"| node_storage
node_signing_domain -->|"sends completed copy"| node_email
node_signer -->|"downloads document"| node_download_routes
node_verify_page -->|"checks fingerprint"| node_verify_api
node_verify_api -.->|"checks document"| node_storage
node_admin_ui -.->|"updates settings"| node_admin_routes
node_admin_routes -->|"reads and updates"| node_settings
node_settings -->|"reads settings"| node_database
node_auth_server -->|"uses database"| node_database

click node_auth_ui "https://github.com/nyllon-software/signudoc/tree/main/src/components/auth"
click node_auth_server "https://github.com/nyllon-software/signudoc/blob/main/src/lib/auth/server.ts"
click node_dashboard "https://github.com/nyllon-software/signudoc/blob/main/src/components/dashboard/dashboard-documents-surface.tsx"
click node_envelope_ui "https://github.com/nyllon-software/signudoc/tree/main/src/components/envelopes"
click node_envelope_routes "https://github.com/nyllon-software/signudoc/tree/main/src/app/api/envelopes"
click node_envelope_domain "https://github.com/nyllon-software/signudoc/blob/main/src/lib/envelopes.ts"
click node_template_ui "https://github.com/nyllon-software/signudoc/tree/main/src/components/templates"
click node_template_routes "https://github.com/nyllon-software/signudoc/tree/main/src/app/api/templates"
click node_signing_ui "https://github.com/nyllon-software/signudoc/tree/main/src/components/signing"
click node_signing_routes "https://github.com/nyllon-software/signudoc/tree/main/src/app/api/signing"
click node_signing_domain "https://github.com/nyllon-software/signudoc/blob/main/src/lib/signing.ts"
click node_audit "https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/audit.ts"
click node_pdf_seal "https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/pdf-seal.ts"
click node_verify_page "https://github.com/nyllon-software/signudoc/blob/main/src/app/verify/page.tsx"
click node_verify_api "https://github.com/nyllon-software/signudoc/blob/main/src/app/api/verify/route.ts"
click node_download_routes "https://github.com/nyllon-software/signudoc/tree/main/src/app/api/download"
click node_email "https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/email.ts"
click node_storage "https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/storage.ts"
click node_database "https://github.com/nyllon-software/signudoc/blob/main/src/lib/db/connection.ts"
click node_admin_ui "https://github.com/nyllon-software/signudoc/tree/main/src/components/settings"
click node_admin_routes "https://github.com/nyllon-software/signudoc/tree/main/src/app/api/admin"
click node_settings "https://github.com/nyllon-software/signudoc/blob/main/src/lib/settings.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_dashboard,node_envelope_ui,node_envelope_routes,node_envelope_domain,node_template_ui,node_template_routes toneBlue
class node_auth_ui,node_auth_server,node_admin_ui,node_admin_routes,node_settings toneAmber
class node_signing_ui,node_signing_routes,node_signing_domain,node_audit,node_pdf_seal toneMint
class node_verify_page,node_verify_api,node_download_routes toneRose
class node_email,node_storage,node_database,node_sender,node_signer toneIndigo
```

## Components

### Envelope authoring

- [Dashboard](https://github.com/nyllon-software/signudoc/blob/main/src/components/dashboard/dashboard-documents-surface.tsx): `src/components/dashboard/dashboard-documents-surface.tsx`
- [Envelope preparation](https://github.com/nyllon-software/signudoc/tree/main/src/components/envelopes): `src/components/envelopes`
- [Envelope endpoints](https://github.com/nyllon-software/signudoc/tree/main/src/app/api/envelopes): `src/app/api/envelopes`
- [Envelope workflow](https://github.com/nyllon-software/signudoc/blob/main/src/lib/envelopes.ts): `src/lib/envelopes.ts`
- [Template screens](https://github.com/nyllon-software/signudoc/tree/main/src/components/templates): `src/components/templates`
- [Template endpoints](https://github.com/nyllon-software/signudoc/tree/main/src/app/api/templates): `src/app/api/templates`

### Identity and administration

- [Account screens](https://github.com/nyllon-software/signudoc/tree/main/src/components/auth): `src/components/auth`
- [Authentication](https://github.com/nyllon-software/signudoc/blob/main/src/lib/auth/server.ts): `src/lib/auth/server.ts`
- [Organization settings](https://github.com/nyllon-software/signudoc/tree/main/src/components/settings): `src/components/settings`
- [Admin endpoints](https://github.com/nyllon-software/signudoc/tree/main/src/app/api/admin): `src/app/api/admin`
- [Application settings](https://github.com/nyllon-software/signudoc/blob/main/src/lib/settings.ts): `src/lib/settings.ts`

### Signing and evidence

- [Signing screens](https://github.com/nyllon-software/signudoc/tree/main/src/components/signing): `src/components/signing`
- [Signing endpoints](https://github.com/nyllon-software/signudoc/tree/main/src/app/api/signing): `src/app/api/signing`
- [Signing workflow](https://github.com/nyllon-software/signudoc/blob/main/src/lib/signing.ts): `src/lib/signing.ts`
- [Audit trail](https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/audit.ts): `src/lib/services/audit.ts`
- [PDF sealing](https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/pdf-seal.ts): `src/lib/services/pdf-seal.ts`

### Document access

- [Verify page](https://github.com/nyllon-software/signudoc/blob/main/src/app/verify/page.tsx): `src/app/verify/page.tsx`
- [Verify endpoint](https://github.com/nyllon-software/signudoc/blob/main/src/app/api/verify/route.ts): `src/app/api/verify/route.ts`
- [Download endpoints](https://github.com/nyllon-software/signudoc/tree/main/src/app/api/download): `src/app/api/download`

### Persistence and services

- [Email delivery](https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/email.ts): `src/lib/services/email.ts`
- [PDF storage](https://github.com/nyllon-software/signudoc/blob/main/src/lib/services/storage.ts): `src/lib/services/storage.ts`
- [Postgres database](https://github.com/nyllon-software/signudoc/blob/main/src/lib/db/connection.ts): `src/lib/db/connection.ts`

### Other components

- **Sender**
- **Signer**

## Connections

- Sender → Account screens: signs in (evidence: `README.md`)
- Account screens → Authentication: authenticates (evidence: `README.md`)
- Sender → Envelope preparation: prepares PDF (evidence: `README.md`)
- Envelope preparation → Envelope endpoints: uploads draft (evidence: `README.md`)
- Envelope endpoints → Envelope workflow: creates draft (evidence: `src/app/api/envelopes/route.ts`)
- Envelope workflow → PDF storage: stores documents (evidence: `src/lib/envelopes.ts`)
- Envelope workflow → Postgres database: persists envelope (evidence: `src/lib/envelopes.ts`)
- Envelope preparation → Template endpoints: saves template (evidence: `README.md`)
- Template endpoints → Postgres database: persists templates
- Sender → Dashboard: tracks envelopes (evidence: `README.md`)
- Dashboard → Envelope endpoints: loads envelope data
- Sender → Signing endpoints: sends envelope (evidence: `README.md`)
- Signing endpoints → Signing workflow: handles signing
- Signing workflow → Audit trail: records events
- Signing workflow → PDF sealing: finalizes signed PDF (evidence: `README.md`)
- Signing workflow → Email delivery: delivers signing links (evidence: `README.md`)
- Signer → Signing screens: opens signing link (evidence: `README.md`)
- Signing screens → Signing endpoints: submits signature
- Signing workflow → PDF storage: stores completed PDF (evidence: `README.md`)
- Signing workflow → Email delivery: sends completed copy (evidence: `README.md`)
- Signer → Download endpoints: downloads document (evidence: `README.md`)
- Verify page → Verify endpoint: checks fingerprint (evidence: `src/app/api/verify/route.ts`)
- Verify endpoint → PDF storage: checks document
- Organization settings → Admin endpoints: updates settings
- Admin endpoints → Application settings: reads and updates (evidence: `src/app/api/admin/settings/route.ts`)
- Application settings → Postgres database: reads settings (evidence: `src/lib/settings.ts`)
- Authentication → Postgres database: uses database (evidence: `src/lib/auth/server.ts`)
