# zenhosta/9drive architecture

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

- Interactive diagram: https://gitdiagram.com/zenhosta/9drive
- Repository: https://github.com/zenhosta/9drive

## Overview

#### Purpose and Entry Points
9Drive is a virtual storage gateway that unifies users’ Google Drive accounts and S3-compatible providers behind a React dashboard and external upload API. The backend is an Express/TypeScript service booted by `backend/src/server.ts`, composed in `backend/src/app.ts`; the browser client starts at `frontend/src/main.tsx` and routes from `frontend/src/App.tsx`.

#### API Boundary and Authorization
HTTP routes are organized by domain modules and protected with bearer-JWT authentication or API-key middleware. Authentication includes local credentials, Google OAuth, refresh/logout flows, and OAuth handoff; app/session secrets and provider credentials are encrypted or hashed.
- `backend/src/modules/auth/auth.routes.ts`
- `backend/src/middleware/auth.middleware.ts`
- `backend/src/middleware/api-key.middleware.ts`

#### Persistent Control Plane
MySQL, accessed through Prisma, is the system of record for users, sessions, connected providers, virtual folder hierarchy, file metadata, share/preview tokens, routing policies, API keys, and audit history. Prisma migrations define the evolving persistence contract, including S3 providers and resumable upload fields.
- `backend/prisma/schema.prisma`
- `backend/src/config/prisma.ts`
- `backend/prisma/migrations/20260611120000_s3_storage_support/migration.sql`

#### Provider Integration Layer
Google Drive is both an OAuth identity source and storage backend: credentials are stored as encrypted global/provider configuration, connected accounts are managed per user, and Drive contents are synchronized into MySQL metadata. S3-compatible storage is accessed server-side so browser clients never receive storage credentials.
- `backend/src/modules/google/google.service.ts`
- `backend/src/modules/s3/s3.service.ts`
- `backend/src/modules/connected-accounts/connected-account.routes.ts`

#### Upload Routing and File Lifecycle
Uploads enter through authenticated UI uploads or `/api/v1/uploads` API-key uploads. The backend streams bytes directly to the selected Google Drive or S3 provider rather than retaining files locally. Routing policies choose a target account/provider by available capacity, round-robin, or priority. File operations then cover listing/search, virtual-folder assignment, rename/move/delete, share links, preview tokens, downloads, and provider streaming.
- `backend/src/modules/uploads/upload.routes.ts`
- `backend/src/modules/files/file.routes.ts`
- `backend/src/modules/files/stream-google-file.ts`

#### Frontend Workspace
The Vite React single-page application provides protected dashboard pages for files, sharing, quota, activity, provider setup, OAuth completion, and API-key management. A shared API/auth client bridges it to Express; upload state is centralized so progress can persist across dashboard views.
- `frontend/src/layouts/DriveLayout.tsx`
- `frontend/src/lib/api.ts`
- `frontend/src/context/UploadContext.tsx`

#### Deployment and External Dependencies
Runtime dependencies are Node.js 20+, MySQL 8+, Google OAuth/Drive API, and optionally any S3-compatible endpoint (AWS S3, MinIO, R2, etc.). Docker Compose provisions frontend, backend, and MySQL; the backend applies Prisma migrations and can seed Google configuration at startup. Production frontend is served through Nginx.
- `docker-compose.yml`
- `backend/Dockerfile`
- `frontend/nginx.conf`

Main entry points: [`backend/src/app.ts`](https://github.com/zenhosta/9drive/blob/main/backend/src/app.ts) (API composition), [`backend/prisma/schema.prisma`](https://github.com/zenhosta/9drive/blob/main/backend/prisma/schema.prisma) (MySQL control plane), [`backend/src/modules/google/google.service.ts`](https://github.com/zenhosta/9drive/blob/main/backend/src/modules/google/google.service.ts) (Provider adapters), [`backend/src/modules/files/file.routes.ts`](https://github.com/zenhosta/9drive/blob/main/backend/src/modules/files/file.routes.ts) (File lifecycle API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Workspace"]
  node_spa["React SPA<br/>Vite React client<br/>[main.tsx]"]
  node_app_routes["Dashboard routes<br/>React routing<br/>[App.tsx]"]
  node_drive_layout["Drive workspace<br/>protected layout<br/>[DriveLayout.tsx]"]
  node_api_client["API and auth client<br/>frontend client<br/>[api.ts]"]
  node_upload_state["Upload state<br/>React context<br/>[UploadContext.tsx]"]
end

subgraph group_backend["Gateway Backend"]
  node_express_server["Express service<br/>Node.js entrypoint<br/>[server.ts]"]
  node_express_app["API composition<br/>Express app<br/>[app.ts]"]
  node_auth_routes["Auth and OAuth<br/>route module<br/>[auth.routes.ts]"]
  node_access_middleware["JWT and API-key guard<br/>middleware<br/>[auth.middleware.ts]"]
  node_api_key_middleware["API-key uploads<br/>middleware"]
  node_file_api["File lifecycle API<br/>route module<br/>[file.routes.ts]"]
  node_upload_router["Upload routing<br/>route module<br/>[upload.routes.ts]"]
  node_provider_layer["Provider adapters<br/>storage integration<br/>[google.service.ts]"]
end

subgraph group_data["Control Plane"]
  node_mysql[("MySQL control plane<br/>Prisma database<br/>[schema.prisma]")]
  node_migration["S3 persistence migration<br/>Prisma migration<br/>[migration.sql]"]
end

subgraph group_providers["External Providers"]
  node_google{{"Google OAuth and Drive<br/>identity and storage API"}}
  node_s3{{"S3-compatible storage<br/>object storage"}}
end

subgraph group_deploy["Deployment"]
  node_compose["Docker Compose<br/>runtime orchestration<br/>[docker-compose.yml]"]
  node_nginx["Nginx<br/>frontend server<br/>[nginx.conf]"]
end

node_spa -->|"boots"| node_app_routes
node_app_routes -->|"protected pages"| node_drive_layout
node_drive_layout -->|"shares progress"| node_upload_state
node_spa -->|"calls API"| node_api_client
node_api_client -->|"HTTPS"| node_express_server
node_express_server -->|"hosts"| node_express_app
node_express_app -->|"auth endpoints"| node_auth_routes
node_express_app -->|"protects routes"| node_access_middleware
node_access_middleware -->|"authorizes UI operations"| node_file_api
node_api_key_middleware -->|"authorizes external uploads"| node_upload_router
node_express_app -->|"upload API"| node_api_key_middleware
node_express_app -->|"upload routes"| node_upload_router
node_express_app -->|"file routes"| node_file_api
node_auth_routes -->|"sessions and credentials"| node_mysql
node_auth_routes -->|"OAuth"| node_google
node_file_api -->|"metadata and tokens"| node_mysql
node_upload_router -->|"routing policies and quota"| node_mysql
node_upload_router -->|"stream bytes"| node_provider_layer
node_file_api -->|"provider operations"| node_provider_layer
node_provider_layer -->|"Drive API"| node_google
node_provider_layer -->|"S3 API"| node_s3
node_provider_layer -->|"connected accounts and sync"| node_mysql
node_migration -->|"evolves schema"| node_mysql
node_compose -->|"runs backend"| node_express_server
node_compose -->|"runs database"| node_mysql
node_compose -->|"runs frontend"| node_nginx
node_nginx -->|"serves production build"| node_spa

click node_spa "https://github.com/zenhosta/9drive/blob/main/frontend/src/main.tsx"
click node_app_routes "https://github.com/zenhosta/9drive/blob/main/frontend/src/App.tsx"
click node_drive_layout "https://github.com/zenhosta/9drive/blob/main/frontend/src/layouts/DriveLayout.tsx"
click node_api_client "https://github.com/zenhosta/9drive/blob/main/frontend/src/lib/api.ts"
click node_upload_state "https://github.com/zenhosta/9drive/blob/main/frontend/src/context/UploadContext.tsx"
click node_express_server "https://github.com/zenhosta/9drive/blob/main/backend/src/server.ts"
click node_express_app "https://github.com/zenhosta/9drive/blob/main/backend/src/app.ts"
click node_auth_routes "https://github.com/zenhosta/9drive/blob/main/backend/src/modules/auth/auth.routes.ts"
click node_access_middleware "https://github.com/zenhosta/9drive/blob/main/backend/src/middleware/auth.middleware.ts"
click node_api_key_middleware "https://github.com/zenhosta/9drive/blob/main/backend/src/middleware/api-key.middleware.ts"
click node_file_api "https://github.com/zenhosta/9drive/blob/main/backend/src/modules/files/file.routes.ts"
click node_upload_router "https://github.com/zenhosta/9drive/blob/main/backend/src/modules/uploads/upload.routes.ts"
click node_provider_layer "https://github.com/zenhosta/9drive/blob/main/backend/src/modules/google/google.service.ts"
click node_mysql "https://github.com/zenhosta/9drive/blob/main/backend/prisma/schema.prisma"
click node_migration "https://github.com/zenhosta/9drive/blob/main/backend/prisma/migrations/20260611120000_s3_storage_support/migration.sql"
click node_compose "https://github.com/zenhosta/9drive/blob/main/docker-compose.yml"
click node_nginx "https://github.com/zenhosta/9drive/blob/main/frontend/nginx.conf"

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_spa,node_app_routes,node_drive_layout,node_api_client,node_upload_state toneBlue
class node_express_server,node_express_app,node_auth_routes,node_access_middleware,node_api_key_middleware,node_file_api,node_upload_router,node_provider_layer toneAmber
class node_mysql,node_migration toneMint
class node_google,node_s3 toneRose
class node_compose,node_nginx toneIndigo
```

## Components

### React Workspace

- [React SPA](https://github.com/zenhosta/9drive/blob/main/frontend/src/main.tsx): Vite React client · Dashboard and external-upload user interface. · `frontend/src/main.tsx`
- [Dashboard routes](https://github.com/zenhosta/9drive/blob/main/frontend/src/App.tsx): React routing · `frontend/src/App.tsx`
- [Drive workspace](https://github.com/zenhosta/9drive/blob/main/frontend/src/layouts/DriveLayout.tsx): protected layout · `frontend/src/layouts/DriveLayout.tsx`
- [API and auth client](https://github.com/zenhosta/9drive/blob/main/frontend/src/lib/api.ts): frontend client · `frontend/src/lib/api.ts`
- [Upload state](https://github.com/zenhosta/9drive/blob/main/frontend/src/context/UploadContext.tsx): React context · Keeps upload progress across dashboard views. · `frontend/src/context/UploadContext.tsx`

### Gateway Backend

- [Express service](https://github.com/zenhosta/9drive/blob/main/backend/src/server.ts): Node.js entrypoint · `backend/src/server.ts`
- [API composition](https://github.com/zenhosta/9drive/blob/main/backend/src/app.ts): Express app · `backend/src/app.ts`
- [Auth and OAuth](https://github.com/zenhosta/9drive/blob/main/backend/src/modules/auth/auth.routes.ts): route module · Local login, Google OAuth, refresh, logout, and handoff. · `backend/src/modules/auth/auth.routes.ts`
- [JWT and API-key guard](https://github.com/zenhosta/9drive/blob/main/backend/src/middleware/auth.middleware.ts): middleware · `backend/src/middleware/auth.middleware.ts`
- [API-key uploads](https://github.com/zenhosta/9drive/blob/main/backend/src/middleware/api-key.middleware.ts): middleware · `backend/src/middleware/api-key.middleware.ts`
- [File lifecycle API](https://github.com/zenhosta/9drive/blob/main/backend/src/modules/files/file.routes.ts): route module · Files, folders, sharing, preview, download, and streaming. · `backend/src/modules/files/file.routes.ts`
- [Upload routing](https://github.com/zenhosta/9drive/blob/main/backend/src/modules/uploads/upload.routes.ts): route module · Selects provider targets and streams upload bytes. · `backend/src/modules/uploads/upload.routes.ts`
- [Provider adapters](https://github.com/zenhosta/9drive/blob/main/backend/src/modules/google/google.service.ts): storage integration · Server-side Google Drive and S3 access. · `backend/src/modules/google/google.service.ts`

### Control Plane

- [MySQL control plane](https://github.com/zenhosta/9drive/blob/main/backend/prisma/schema.prisma): Prisma database · System of record for identities, metadata, policies, tokens, and audit history. · `backend/prisma/schema.prisma`
- [S3 persistence migration](https://github.com/zenhosta/9drive/blob/main/backend/prisma/migrations/20260611120000_s3_storage_support/migration.sql): Prisma migration · Adds S3 provider and resumable-upload persistence. · `backend/prisma/migrations/20260611120000_s3_storage_support/migration.sql`

### External Providers

- **Google OAuth and Drive**: identity and storage API
- **S3-compatible storage**: object storage · AWS S3, MinIO, R2, or compatible endpoint.

### Deployment

- [Docker Compose](https://github.com/zenhosta/9drive/blob/main/docker-compose.yml): runtime orchestration · Provisions frontend, backend, and MySQL. · `docker-compose.yml`
- [Nginx](https://github.com/zenhosta/9drive/blob/main/frontend/nginx.conf): frontend server · `frontend/nginx.conf`

## Connections

- React SPA → Dashboard routes: boots
- Dashboard routes → Drive workspace: protected pages
- Drive workspace → Upload state: shares progress
- React SPA → API and auth client: calls API
- API and auth client → Express service: HTTPS
- Express service → API composition: hosts
- API composition → Auth and OAuth: auth endpoints
- API composition → JWT and API-key guard: protects routes
- JWT and API-key guard → File lifecycle API: authorizes UI operations
- API-key uploads → Upload routing: authorizes external uploads
- API composition → API-key uploads: upload API
- API composition → Upload routing: upload routes
- API composition → File lifecycle API: file routes
- Auth and OAuth → MySQL control plane: sessions and credentials
- Auth and OAuth → Google OAuth and Drive: OAuth
- File lifecycle API → MySQL control plane: metadata and tokens
- Upload routing → MySQL control plane: routing policies and quota
- Upload routing → Provider adapters: stream bytes
- File lifecycle API → Provider adapters: provider operations
- Provider adapters → Google OAuth and Drive: Drive API
- Provider adapters → S3-compatible storage: S3 API
- Provider adapters → MySQL control plane: connected accounts and sync
- S3 persistence migration → MySQL control plane: evolves schema
- Docker Compose → Express service: runs backend
- Docker Compose → MySQL control plane: runs database
- Docker Compose → Nginx: runs frontend
- Nginx → React SPA: serves production build