# bikramdhami0100/localshare architecture

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

- Interactive diagram: https://gitdiagram.com/bikramdhami0100/localshare
- Repository: https://github.com/bikramdhami0100/localshare

## Overview

LocalShare is a no-account shared content space for devices on the same LAN. A visitor opens the shared-space page, which loads content and folders, lets them create or edit notes, links, folders, and files, and reflects persisted changes to connected devices in real time. API routes validate requests and delegate persistence to the PostgreSQL-backed store; uploads additionally stream bytes to host storage. The README documents persistence, optimistic concurrency, and live updates; unsampled route and UI behavior is represented only where documented or indexed.

Main entry points: [`hooks/useSharedSpace.ts`](https://github.com/bikramdhami0100/localshare/blob/master/hooks/useSharedSpace.ts) (Shared-space state), [`app/page.tsx`](https://github.com/bikramdhami0100/localshare/blob/master/app/page.tsx) (Shared-space page), [`server/store.mjs`](https://github.com/bikramdhami0100/localshare/blob/master/server/store.mjs) (Shared data store), [`app/api/content/route.ts`](https://github.com/bikramdhami0100/localshare/blob/master/app/api/content/route.ts) (Content and folders API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Shared-space client"]
  node_home["Shared-space page<br/>[page.tsx]"]
  node_device["Device identity<br/>[useDevice.ts]"]
  node_space["Shared-space state<br/>[useSharedSpace.ts]"]
  node_compose["Content composer<br/>[Compose.tsx]"]
  node_addmodal["Add content modal"]
  node_editmodal["Edit content modal"]
  node_card["Content cards<br/>[ContentCard.tsx]"]
  node_header["Space header<br/>[Header.tsx]"]
  node_notices["Change notices<br/>[NoticeStack.tsx]"]
  node_ui["UI primitives<br/>[Button.tsx]"]
end

subgraph group_api["API and validation"]
  node_api["Content and folders API<br/>[route.ts]"]
  node_contentitem["Content item API<br/>[route.ts]"]
  node_folderapi["Folder API<br/>[route.ts]"]
  node_folderitem["Folder item API<br/>[route.ts]"]
  node_deviceapi["Device API<br/>[route.ts]"]
  node_upload["File upload API<br/>[route.ts]"]
  node_download["File serving API<br/>[route.ts]"]
  node_validate["Input validation<br/>[validation.ts]"]
  node_apiresponse["API responses<br/>[api.ts]"]
end

subgraph group_realtime["Live updates"]
  node_broadcast["Broadcast bridge<br/>[broadcast.ts]"]
  node_hub["WebSocket event hub<br/>[hub.mjs]"]
  node_server["Custom server<br/>[server.mjs]"]
end

subgraph group_persistence["Persistence and files"]
  node_store["Shared data store<br/>[store.mjs]"]
  node_pool["PostgreSQL pool<br/>[pool.mjs]"]
  node_filedisk["File storage<br/>[files.ts]"]
end

node_lan(("LAN visitors"))
node_postgres[("PostgreSQL")]
node_filesystem[("Host filesystem")]

node_lan -->|"opens"| node_home
node_home -->|"gets identity"| node_device
node_home -->|"loads shared state"| node_space
node_home -->|"renders editor"| node_compose
node_home -->|"renders creation"| node_addmodal
node_home -->|"renders items"| node_card
node_home -->|"renders header"| node_header
node_home -->|"renders notices"| node_notices
node_compose -->|"uses state"| node_space
node_addmodal -->|"uses controls"| node_ui
node_editmodal -->|"uses controls"| node_ui
node_space -->|"fetches content"| node_api
node_space -->|"fetches folders"| node_folderapi
node_space -->|"checks health"| node_deviceapi
node_space -->|"updates content"| node_contentitem
node_space -->|"deletes folders"| node_folderitem
node_space -->|"uploads files"| node_upload
node_space -->|"builds download URL"| node_download
node_space -->|"connects by WebSocket"| node_hub
node_api -->|"validates writes"| node_validate
node_api -->|"reads and creates"| node_store
node_api -->|"announces creation"| node_broadcast
node_contentitem -->|"changes content"| node_store
node_contentitem -->|"announces changes"| node_broadcast
node_folderapi -->|"validates writes"| node_validate
node_folderapi -->|"reads and creates"| node_store
node_folderapi -->|"announces creation"| node_broadcast
node_folderitem -->|"changes folders"| node_store
node_deviceapi -->|"manages devices"| node_store
node_upload -->|"checks upload"| node_validate
node_upload -->|"stores bytes"| node_filedisk
node_upload -->|"persists metadata"| node_store
node_upload -->|"announces upload"| node_broadcast
node_download -->|"loads metadata"| node_store
node_download -->|"serves bytes"| node_filedisk
node_broadcast -->|"forwards events"| node_hub
node_server -->|"mounts hub"| node_hub
node_hub -->|"loads initial state"| node_store
node_store -->|"queries database"| node_pool
node_pool -->|"connects"| node_postgres
node_filedisk -->|"reads and writes"| node_filesystem
node_api -->|"formats responses"| node_apiresponse

click node_home "https://github.com/bikramdhami0100/localshare/blob/master/app/page.tsx"
click node_device "https://github.com/bikramdhami0100/localshare/blob/master/hooks/useDevice.ts"
click node_space "https://github.com/bikramdhami0100/localshare/blob/master/hooks/useSharedSpace.ts"
click node_compose "https://github.com/bikramdhami0100/localshare/blob/master/components/Compose.tsx"
click node_addmodal "https://github.com/bikramdhami0100/localshare/blob/master/components/AddContentModal.tsx"
click node_editmodal "https://github.com/bikramdhami0100/localshare/blob/master/components/EditContentModal.tsx"
click node_card "https://github.com/bikramdhami0100/localshare/blob/master/components/ContentCard.tsx"
click node_header "https://github.com/bikramdhami0100/localshare/blob/master/components/Header.tsx"
click node_notices "https://github.com/bikramdhami0100/localshare/blob/master/components/NoticeStack.tsx"
click node_ui "https://github.com/bikramdhami0100/localshare/blob/master/components/ui/Button.tsx"
click node_api "https://github.com/bikramdhami0100/localshare/blob/master/app/api/content/route.ts"
click node_contentitem "https://github.com/bikramdhami0100/localshare/blob/master/app/api/content/%5Bid%5D/route.ts"
click node_folderapi "https://github.com/bikramdhami0100/localshare/blob/master/app/api/folders/route.ts"
click node_folderitem "https://github.com/bikramdhami0100/localshare/blob/master/app/api/folders/%5Bid%5D/route.ts"
click node_deviceapi "https://github.com/bikramdhami0100/localshare/blob/master/app/api/device/route.ts"
click node_upload "https://github.com/bikramdhami0100/localshare/blob/master/app/api/files/upload/route.ts"
click node_download "https://github.com/bikramdhami0100/localshare/blob/master/app/api/files/%5Bid%5D/route.ts"
click node_validate "https://github.com/bikramdhami0100/localshare/blob/master/lib/validation.ts"
click node_apiresponse "https://github.com/bikramdhami0100/localshare/blob/master/lib/api.ts"
click node_broadcast "https://github.com/bikramdhami0100/localshare/blob/master/lib/broadcast.ts"
click node_hub "https://github.com/bikramdhami0100/localshare/blob/master/server/websocket/hub.mjs"
click node_server "https://github.com/bikramdhami0100/localshare/blob/master/server.mjs"
click node_store "https://github.com/bikramdhami0100/localshare/blob/master/server/store.mjs"
click node_pool "https://github.com/bikramdhami0100/localshare/blob/master/server/pool.mjs"
click node_filedisk "https://github.com/bikramdhami0100/localshare/blob/master/server/storage/files.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_home,node_device,node_space,node_compose,node_addmodal,node_editmodal,node_card,node_header,node_notices,node_ui toneBlue
class node_api,node_contentitem,node_folderapi,node_folderitem,node_deviceapi,node_upload,node_download,node_validate,node_apiresponse,node_postgres,node_filesystem toneAmber
class node_broadcast,node_hub,node_server toneMint
class node_store,node_pool,node_filedisk toneRose
class node_lan toneIndigo
```

## Components

### Shared-space client

- [Shared-space page](https://github.com/bikramdhami0100/localshare/blob/master/app/page.tsx): `app/page.tsx`
- [Device identity](https://github.com/bikramdhami0100/localshare/blob/master/hooks/useDevice.ts): `hooks/useDevice.ts`
- [Shared-space state](https://github.com/bikramdhami0100/localshare/blob/master/hooks/useSharedSpace.ts): `hooks/useSharedSpace.ts`
- [Content composer](https://github.com/bikramdhami0100/localshare/blob/master/components/Compose.tsx): `components/Compose.tsx`
- [Add content modal](https://github.com/bikramdhami0100/localshare/blob/master/components/AddContentModal.tsx): `components/AddContentModal.tsx`
- [Edit content modal](https://github.com/bikramdhami0100/localshare/blob/master/components/EditContentModal.tsx): `components/EditContentModal.tsx`
- [Content cards](https://github.com/bikramdhami0100/localshare/blob/master/components/ContentCard.tsx): `components/ContentCard.tsx`
- [Space header](https://github.com/bikramdhami0100/localshare/blob/master/components/Header.tsx): `components/Header.tsx`
- [Change notices](https://github.com/bikramdhami0100/localshare/blob/master/components/NoticeStack.tsx): `components/NoticeStack.tsx`
- [UI primitives](https://github.com/bikramdhami0100/localshare/blob/master/components/ui/Button.tsx): `components/ui/Button.tsx`

### API and validation

- [Content and folders API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/content/route.ts): `app/api/content/route.ts`
- [Content item API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/content/%5Bid%5D/route.ts): `app/api/content/[id]/route.ts`
- [Folder API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/folders/route.ts): `app/api/folders/route.ts`
- [Folder item API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/folders/%5Bid%5D/route.ts): `app/api/folders/[id]/route.ts`
- [Device API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/device/route.ts): `app/api/device/route.ts`
- [File upload API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/files/upload/route.ts): `app/api/files/upload/route.ts`
- [File serving API](https://github.com/bikramdhami0100/localshare/blob/master/app/api/files/%5Bid%5D/route.ts): `app/api/files/[id]/route.ts`
- [Input validation](https://github.com/bikramdhami0100/localshare/blob/master/lib/validation.ts): `lib/validation.ts`
- [API responses](https://github.com/bikramdhami0100/localshare/blob/master/lib/api.ts): `lib/api.ts`

### Live updates

- [Broadcast bridge](https://github.com/bikramdhami0100/localshare/blob/master/lib/broadcast.ts): `lib/broadcast.ts`
- [WebSocket event hub](https://github.com/bikramdhami0100/localshare/blob/master/server/websocket/hub.mjs): `server/websocket/hub.mjs`
- [Custom server](https://github.com/bikramdhami0100/localshare/blob/master/server.mjs): `server.mjs`

### Persistence and files

- [Shared data store](https://github.com/bikramdhami0100/localshare/blob/master/server/store.mjs): `server/store.mjs`
- [PostgreSQL pool](https://github.com/bikramdhami0100/localshare/blob/master/server/pool.mjs): `server/pool.mjs`
- [File storage](https://github.com/bikramdhami0100/localshare/blob/master/server/storage/files.ts): `server/storage/files.ts`

### Other components

- **LAN visitors**
- **PostgreSQL**
- **Host filesystem**

## Connections

- LAN visitors → Shared-space page: opens (evidence: `README.md`)
- Shared-space page → Device identity: gets identity (evidence: `app/page.tsx`)
- Shared-space page → Shared-space state: loads shared state (evidence: `app/page.tsx`)
- Shared-space page → Content composer: renders editor (evidence: `app/page.tsx`)
- Shared-space page → Add content modal: renders creation (evidence: `app/page.tsx`)
- Shared-space page → Content cards: renders items (evidence: `app/page.tsx`)
- Shared-space page → Space header: renders header (evidence: `app/page.tsx`)
- Shared-space page → Change notices: renders notices (evidence: `app/page.tsx`)
- Content composer → Shared-space state: uses state (evidence: `components/Compose.tsx`)
- Add content modal → UI primitives: uses controls (evidence: `components/AddContentModal.tsx`)
- Edit content modal → UI primitives: uses controls (evidence: `components/EditContentModal.tsx`)
- Shared-space state → Content and folders API: fetches content (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → Folder API: fetches folders (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → Device API: checks health (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → Content item API: updates content (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → Folder item API: deletes folders (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → File upload API: uploads files (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → File serving API: builds download URL (evidence: `hooks/useSharedSpace.ts`)
- Shared-space state → WebSocket event hub: connects by WebSocket (evidence: `README.md`)
- Content and folders API → Input validation: validates writes (evidence: `app/api/content/route.ts`)
- Content and folders API → Shared data store: reads and creates (evidence: `app/api/content/route.ts`)
- Content and folders API → Broadcast bridge: announces creation (evidence: `app/api/content/route.ts`)
- Content item API → Shared data store: changes content (evidence: `app/api/content/[id]/route.ts`)
- Content item API → Broadcast bridge: announces changes (evidence: `app/api/content/[id]/route.ts`)
- Folder API → Input validation: validates writes (evidence: `app/api/folders/route.ts`)
- Folder API → Shared data store: reads and creates (evidence: `app/api/folders/route.ts`)
- Folder API → Broadcast bridge: announces creation (evidence: `app/api/folders/route.ts`)
- Folder item API → Shared data store: changes folders (evidence: `app/api/folders/[id]/route.ts`)
- Device API → Shared data store: manages devices (evidence: `app/api/device/route.ts`)
- File upload API → Input validation: checks upload (evidence: `app/api/files/upload/route.ts`)
- File upload API → File storage: stores bytes (evidence: `app/api/files/upload/route.ts`)
- File upload API → Shared data store: persists metadata (evidence: `app/api/files/upload/route.ts`)
- File upload API → Broadcast bridge: announces upload (evidence: `app/api/files/upload/route.ts`)
- File serving API → Shared data store: loads metadata (evidence: `app/api/files/[id]/route.ts`)
- File serving API → File storage: serves bytes (evidence: `app/api/files/[id]/route.ts`)
- Broadcast bridge → WebSocket event hub: forwards events (evidence: `lib/broadcast.ts`)
- Custom server → WebSocket event hub: mounts hub (evidence: `server.mjs`)
- WebSocket event hub → Shared data store: loads initial state (evidence: `server/websocket/hub.mjs`)
- Shared data store → PostgreSQL pool: queries database (evidence: `server/store.mjs`)
- PostgreSQL pool → PostgreSQL: connects (evidence: `README.md`)
- File storage → Host filesystem: reads and writes (evidence: `README.md`)
- Content and folders API → API responses: formats responses (evidence: `app/api/content/route.ts`)
