# minemap-nl/nexoshare architecture

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

- Interactive diagram: https://gitdiagram.com/minemap-nl/nexoshare
- Repository: https://github.com/minemap-nl/nexoshare

## Overview

Nexo Share is a self-hosted file-sharing application. Its principal workflow is an authenticated user uploading files, creating a protected share, and a recipient downloading it; reverse-share links let guests upload back without accounts. The graph also preserves the documented security, identity, administration, and preview capabilities. The backend entry point is shown as the server-side orchestrator; several frontend pages and backend subsystems are unsampled, so uncertain page-to-API links are dashed rather than asserted.

Main entry points: [`backend/src/index.ts`](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/index.ts) (API and workflows), [`frontend/src/App.tsx`](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/pages/Dashboard.tsx`](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/Dashboard.tsx) (Dashboard and admin), [`frontend/src/pages/GuestUploadPage.tsx`](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/GuestUploadPage.tsx) (Guest drop-off)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_webapp["App routing<br/>[App.tsx]"]
  node_authui["Login and session<br/>[useAuth.ts]"]
  node_dashboard["Dashboard and admin<br/>[Dashboard.tsx]"]
  node_previews["File previews"]
end

subgraph group_sharing["Sharing workflows"]
  node_uploadui["File upload<br/>[UploadView.tsx]"]
  node_downloadui["Share download<br/>[DownloadPage.tsx]"]
  node_reverseui["Guest drop-off"]
  node_reversemanage["Reverse shares<br/>[ReverseView.tsx]"]
end

subgraph group_server["Backend services"]
  node_backend["API and workflows<br/>[index.ts]"]
  node_database[("PostgreSQL")]
  node_zipcache[("Prebuilt ZIP cache<br/>[sharePrezip.ts]")]
  node_email["Email rendering<br/>[emailTemplate.ts]"]
end

subgraph group_security["Security and identity"]
  node_uploadsafety["Upload validation"]
  node_pathpolicy["Storage path policy"]
  node_virus["ClamAV scanning<br/>[clamScan.ts]"]
  node_sso["SSO group mapping<br/>[ssoGroups.ts]"]
  node_blocked["Blocked extensions"]
end

node_user(("Account user"))
node_guest(("Guest recipient"))

node_user -->|"uses"| node_webapp
node_guest -->|"opens link"| node_webapp
node_webapp -->|"checks session"| node_authui
node_webapp -->|"routes authenticated"| node_dashboard
node_webapp -->|"routes share link"| node_downloadui
node_webapp -->|"routes drop-off link"| node_reverseui
node_user -.->|"selects files"| node_uploadui
node_user -.->|"manages account"| node_dashboard
node_guest -->|"uploads files"| node_reverseui
node_dashboard -.->|"manages links"| node_reversemanage
node_uploadui -.->|"uploads files"| node_backend
node_downloadui -.->|"requests share"| node_backend
node_reverseui -.->|"submits files"| node_backend
node_reversemanage -.->|"manages shares"| node_backend
node_backend -->|"reads and writes"| node_database
node_backend -.->|"validates uploads"| node_uploadsafety
node_uploadsafety -->|"checks extensions"| node_blocked
node_backend -->|"checks storage paths"| node_pathpolicy
node_backend -->|"scans uploaded files"| node_virus
node_backend -->|"invalidates ZIP cache"| node_zipcache
node_backend -->|"renders email"| node_email
node_backend -->|"resolves OIDC groups"| node_sso
node_backend -.->|"serves file content"| node_previews
node_user -.->|"previews files"| node_previews
node_backend -->|"scans reverse uploads"| node_virus
node_backend -->|"supports OIDC SSO"| node_sso

click node_webapp "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/hooks/useAuth.ts"
click node_dashboard "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/Dashboard.tsx"
click node_uploadui "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/UploadView.tsx"
click node_downloadui "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/DownloadPage.tsx"
click node_reverseui "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/GuestUploadPage.tsx"
click node_reversemanage "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/ReverseView.tsx"
click node_previews "https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/components/preview/FilePreviewModal.tsx"
click node_backend "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/index.ts"
click node_zipcache "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/sharePrezip.ts"
click node_email "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/emailTemplate.ts"
click node_uploadsafety "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/uploadValidation.ts"
click node_pathpolicy "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/uploadPathPolicy.ts"
click node_virus "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/clamScan.ts"
click node_sso "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/ssoGroups.ts"
click node_blocked "https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/blockedExtensions.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_webapp,node_authui,node_dashboard,node_previews,node_user toneBlue
class node_uploadui,node_downloadui,node_reverseui,node_reversemanage toneAmber
class node_backend,node_database,node_zipcache,node_email toneMint
class node_uploadsafety,node_pathpolicy,node_virus,node_sso,node_blocked toneRose
class node_guest toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login and session](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Dashboard and admin](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [File previews](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/components/preview/FilePreviewModal.tsx): `frontend/src/components/preview/FilePreviewModal.tsx`

### Sharing workflows

- [File upload](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/UploadView.tsx): `frontend/src/pages/UploadView.tsx`
- [Share download](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/DownloadPage.tsx): `frontend/src/pages/DownloadPage.tsx`
- [Guest drop-off](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/GuestUploadPage.tsx): `frontend/src/pages/GuestUploadPage.tsx`
- [Reverse shares](https://github.com/minemap-nl/nexoshare/blob/main/frontend/src/pages/ReverseView.tsx): `frontend/src/pages/ReverseView.tsx`

### Backend services

- [API and workflows](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/index.ts): `backend/src/index.ts`
- **PostgreSQL**
- [Prebuilt ZIP cache](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/sharePrezip.ts): `backend/src/lib/sharePrezip.ts`
- [Email rendering](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/emailTemplate.ts): `backend/src/lib/emailTemplate.ts`

### Security and identity

- [Upload validation](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/uploadValidation.ts): `backend/src/lib/uploadValidation.ts`
- [Storage path policy](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/uploadPathPolicy.ts): `backend/src/lib/uploadPathPolicy.ts`
- [ClamAV scanning](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/clamScan.ts): `backend/src/lib/clamScan.ts`
- [SSO group mapping](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/ssoGroups.ts): `backend/src/lib/ssoGroups.ts`
- [Blocked extensions](https://github.com/minemap-nl/nexoshare/blob/main/backend/src/lib/blockedExtensions.ts): `backend/src/lib/blockedExtensions.ts`

### Other components

- **Account user**
- **Guest recipient**

## Connections

- Account user → App routing: uses (evidence: `frontend/src/App.tsx`)
- Guest recipient → App routing: opens link (evidence: `frontend/src/App.tsx`)
- App routing → Login and session: checks session (evidence: `frontend/src/App.tsx`)
- App routing → Dashboard and admin: routes authenticated (evidence: `frontend/src/App.tsx`)
- App routing → Share download: routes share link (evidence: `frontend/src/App.tsx`)
- App routing → Guest drop-off: routes drop-off link (evidence: `frontend/src/App.tsx`)
- Account user → File upload: selects files
- Account user → Dashboard and admin: manages account
- Guest recipient → Guest drop-off: uploads files (evidence: `README.md`)
- Dashboard and admin → Reverse shares: manages links
- File upload → API and workflows: uploads files
- Share download → API and workflows: requests share
- Guest drop-off → API and workflows: submits files
- Reverse shares → API and workflows: manages shares
- API and workflows → PostgreSQL: reads and writes (evidence: `README.md`)
- API and workflows → Upload validation: validates uploads (evidence: `backend/src/index.ts`)
- Upload validation → Blocked extensions: checks extensions (evidence: `backend/src/lib/uploadValidation.ts`)
- API and workflows → Storage path policy: checks storage paths (evidence: `backend/src/index.ts`)
- API and workflows → ClamAV scanning: scans uploaded files (evidence: `backend/src/index.ts`)
- API and workflows → Prebuilt ZIP cache: invalidates ZIP cache (evidence: `backend/src/index.ts`)
- API and workflows → Email rendering: renders email (evidence: `backend/src/index.ts`)
- API and workflows → SSO group mapping: resolves OIDC groups (evidence: `backend/src/index.ts`)
- API and workflows → File previews: serves file content
- Account user → File previews: previews files
- API and workflows → ClamAV scanning: scans reverse uploads (evidence: `README.md`)
- API and workflows → SSO group mapping: supports OIDC SSO (evidence: `README.md`)
