# phaseworld-creator/zipline-phase architecture

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

- Interactive diagram: https://gitdiagram.com/phaseworld-creator/zipline-phase
- Repository: https://github.com/phaseworld-creator/zipline-phase

## Overview

Zipline is a self-hosted ShareX-style file and link sharing server. Its main user journey is to authenticate, upload or manage files, then access shared files or shortened URLs; administrators configure the instance and maintain stored content. The graph separates the browser experience, server routing, persistence/storage, and operational services. The README establishes the product purpose, while the excerpts show route registration, dashboard loading, database and datasource behavior, and background tasks; most upload and authentication internals were not sampled, so those links are marked unverified.

Main entry points: [`src/client/routes.tsx`](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/routes.tsx) (Browser routes), [`src/server/startup/routes.ts`](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/startup/routes.ts) (Route registry), [`src/lib/db/index.ts`](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/db/index.ts) (Prisma database), [`src/lib/datasource/index.ts`](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/datasource/index.ts) (File datasource)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_client_app["Web application<br/>[Root.tsx]"]
  node_browser_routes["Browser routes<br/>[routes.tsx]"]
  node_auth_ui["Authentication screens<br/>[login.tsx]"]
  node_dashboard["Dashboard<br/>[index.tsx]"]
  node_file_ui["File management<br/>[index.tsx]"]
  node_upload_ui["Upload interface<br/>[index.tsx]"]
  node_view_ui["Shared file views<br/>[&#91;id&#93;.tsx]"]
end

subgraph group_server["HTTP server"]
  node_server["Zipline server<br/>[index.ts]"]
  node_route_registry["Route registry<br/>[routes.ts]"]
  node_api_routes["API endpoints"]
  node_public_routes["File and URL routes<br/>[files.dy.ts]"]
  node_ssr_views["Server-rendered views<br/>[server.tsx]"]
end

subgraph group_storage["Persistence and files"]
  node_database[("Prisma database<br/>[index.ts]")]
  node_file_model["File records<br/>[file.ts]"]
  node_datasource["File datasource<br/>[index.ts]"]
  node_local_storage["Local or S3 storage<br/>[S3.ts]"]
end

subgraph group_operations["Administration and operations"]
  node_config["Configuration<br/>[validate.ts]"]
  node_admin_ui["Admin console<br/>[index.tsx]"]
  node_maintenance_api["Maintenance actions<br/>[requery_size.ts]"]
  node_size_requery["File size reconciliation<br/>[requerySize.ts]"]
  node_scheduled_tasks["Scheduled tasks<br/>[tasks.ts]"]
end

node_user(("User"))

node_user -->|"opens"| node_browser_routes
node_browser_routes -->|"renders"| node_client_app
node_browser_routes -->|"routes to"| node_auth_ui
node_browser_routes -->|"routes to"| node_dashboard
node_browser_routes -->|"routes to"| node_file_ui
node_browser_routes -->|"routes to"| node_upload_ui
node_browser_routes -->|"routes to"| node_view_ui
node_browser_routes -->|"loads settings"| node_api_routes
node_server -->|"registers routes"| node_route_registry
node_route_registry -->|"registers"| node_api_routes
node_route_registry -->|"dispatches"| node_public_routes
node_route_registry -->|"serves views"| node_ssr_views
node_ssr_views -->|"reads records"| node_database
node_ssr_views -->|"renders"| node_view_ui
node_database -->|"extends file data"| node_file_model
node_server -->|"loads settings"| node_config
node_config -->|"selects backend"| node_datasource
node_datasource -->|"provides storage"| node_local_storage
node_admin_ui -.->|"requests action"| node_maintenance_api
node_maintenance_api -->|"invokes"| node_size_requery
node_size_requery -->|"updates records"| node_database
node_size_requery -->|"checks files"| node_datasource
node_server -->|"starts tasks"| node_scheduled_tasks
node_scheduled_tasks -->|"passes database"| node_database
node_upload_ui -.->|"submits upload"| node_api_routes
node_public_routes -.->|"serves stored files"| node_datasource

click node_client_app "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/Root.tsx"
click node_browser_routes "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/routes.tsx"
click node_auth_ui "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/auth/login.tsx"
click node_dashboard "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/dashboard/index.tsx"
click node_file_ui "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/components/pages/files/index.tsx"
click node_upload_ui "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/components/pages/upload/File/index.tsx"
click node_view_ui "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/view/%5Bid%5D.tsx"
click node_server "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/index.ts"
click node_route_registry "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/startup/routes.ts"
click node_api_routes "https://github.com/phaseworld-creator/zipline-phase/tree/trunk/src/server/routes/api"
click node_public_routes "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/routes/files.dy.ts"
click node_ssr_views "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/ssr-view/server.tsx"
click node_database "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/db/index.ts"
click node_file_model "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/db/models/file.ts"
click node_datasource "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/datasource/index.ts"
click node_local_storage "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/datasource/S3.ts"
click node_config "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/config/validate.ts"
click node_admin_ui "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/dashboard/admin/index.tsx"
click node_maintenance_api "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/routes/api/server/requery_size.ts"
click node_size_requery "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/server-util/requerySize.ts"
click node_scheduled_tasks "https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/startup/tasks.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_client_app,node_browser_routes,node_auth_ui,node_dashboard,node_file_ui,node_upload_ui,node_view_ui,node_user toneBlue
class node_server,node_route_registry,node_api_routes,node_public_routes,node_ssr_views toneAmber
class node_database,node_file_model,node_datasource,node_local_storage toneMint
class node_config,node_admin_ui,node_maintenance_api,node_size_requery,node_scheduled_tasks toneRose
```

## Components

### Browser experience

- [Web application](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/Root.tsx): `src/client/Root.tsx`
- [Browser routes](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/routes.tsx): `src/client/routes.tsx`
- [Authentication screens](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/auth/login.tsx): `src/client/pages/auth/login.tsx`
- [Dashboard](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/dashboard/index.tsx): `src/client/pages/dashboard/index.tsx`
- [File management](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/components/pages/files/index.tsx): `src/components/pages/files/index.tsx`
- [Upload interface](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/components/pages/upload/File/index.tsx): `src/components/pages/upload/File/index.tsx`
- [Shared file views](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/view/%5Bid%5D.tsx): `src/client/pages/view/[id].tsx`

### HTTP server

- [Zipline server](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/index.ts): `src/server/index.ts`
- [Route registry](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/startup/routes.ts): `src/server/startup/routes.ts`
- [API endpoints](https://github.com/phaseworld-creator/zipline-phase/tree/trunk/src/server/routes/api): `src/server/routes/api`
- [File and URL routes](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/routes/files.dy.ts): `src/server/routes/files.dy.ts`
- [Server-rendered views](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/ssr-view/server.tsx): `src/client/ssr-view/server.tsx`

### Persistence and files

- [Prisma database](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/db/index.ts): `src/lib/db/index.ts`
- [File records](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/db/models/file.ts): `src/lib/db/models/file.ts`
- [File datasource](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/datasource/index.ts): `src/lib/datasource/index.ts`
- [Local or S3 storage](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/datasource/S3.ts): `src/lib/datasource/S3.ts`

### Administration and operations

- [Configuration](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/config/validate.ts): `src/lib/config/validate.ts`
- [Admin console](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/client/pages/dashboard/admin/index.tsx): `src/client/pages/dashboard/admin/index.tsx`
- [Maintenance actions](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/routes/api/server/requery_size.ts): `src/server/routes/api/server/requery_size.ts`
- [File size reconciliation](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/lib/server-util/requerySize.ts): `src/lib/server-util/requerySize.ts`
- [Scheduled tasks](https://github.com/phaseworld-creator/zipline-phase/blob/trunk/src/server/startup/tasks.ts): `src/server/startup/tasks.ts`

### Other components

- **User**

## Connections

- User → Browser routes: opens (evidence: `src/client/routes.tsx`)
- Browser routes → Web application: renders (evidence: `src/client/routes.tsx`)
- Browser routes → Authentication screens: routes to (evidence: `src/client/routes.tsx`)
- Browser routes → Dashboard: routes to (evidence: `src/client/routes.tsx`)
- Browser routes → File management: routes to (evidence: `src/client/routes.tsx`)
- Browser routes → Upload interface: routes to (evidence: `src/client/routes.tsx`)
- Browser routes → Shared file views: routes to
- Browser routes → API endpoints: loads settings (evidence: `src/client/routes.tsx`)
- Zipline server → Route registry: registers routes (evidence: `src/server/index.ts`)
- Route registry → API endpoints: registers (evidence: `src/server/startup/routes.ts`)
- Route registry → File and URL routes: dispatches (evidence: `src/server/startup/routes.ts`)
- Route registry → Server-rendered views: serves views (evidence: `src/server/startup/routes.ts`)
- Server-rendered views → Prisma database: reads records (evidence: `src/client/ssr-view/server.tsx`)
- Server-rendered views → Shared file views: renders (evidence: `src/client/ssr-view/server.tsx`)
- Prisma database → File records: extends file data (evidence: `src/lib/db/index.ts`)
- Zipline server → Configuration: loads settings (evidence: `src/server/index.ts`)
- Configuration → File datasource: selects backend (evidence: `src/lib/datasource/index.ts`)
- File datasource → Local or S3 storage: provides storage (evidence: `src/lib/datasource/index.ts`)
- Admin console → Maintenance actions: requests action
- Maintenance actions → File size reconciliation: invokes (evidence: `src/server/routes/api/server/requery_size.ts`)
- File size reconciliation → Prisma database: updates records (evidence: `src/lib/server-util/requerySize.ts`)
- File size reconciliation → File datasource: checks files (evidence: `src/lib/server-util/requerySize.ts`)
- Zipline server → Scheduled tasks: starts tasks (evidence: `src/server/index.ts`)
- Scheduled tasks → Prisma database: passes database (evidence: `src/server/startup/tasks.ts`)
- Upload interface → API endpoints: submits upload
- File and URL routes → File datasource: serves stored files
