# thavasakthi/velodrive architecture

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

- Interactive diagram: https://gitdiagram.com/thavasakthi/velodrive
- Repository: https://github.com/thavasakthi/velodrive

## Overview

#### Purpose and entry points
VeloDrive is a full-stack workspace-based file storage and management system. The backend HTTP server starts at `backend/server.js`; the browser SPA starts at `frontend/src/main.jsx` and composes routing/UI in `frontend/src/App.jsx`.

#### API and request boundary
Express route modules expose domain APIs for authentication, workspaces, folders, images/assets, trash, conversion, and administration:
- `backend/routes/auth.js`
- `backend/routes/workspaces.js`
- `backend/routes/folders.js`
- `backend/routes/images.js`
- `backend/routes/trash.js`
- `backend/routes/convert.js`
- `backend/routes/admin.js`

Cross-cutting middleware enforces login rate limiting, user authentication, workspace-scoped authorization, and admin access before route handlers reach data or storage operations:
- `backend/middleware/loginLimiter.js`
- `backend/middleware/auth.js`
- `backend/middleware/workspaceAuth.js`
- `backend/middleware/admin.js`

#### Persistent domain model
The backend models four central entities: users, workspaces, folders, and stored assets. Workspace membership/ownership is the key tenant boundary; folders organize assets, while trash routes likely implement soft-delete/recovery behavior.
- `backend/models/User.js`
- `backend/models/Workspace.js`
- `backend/models/Folder.js`
- `backend/models/Asset.js`

Quota and storage-accounting logic is centralized separately from route code:
- `backend/utils/quotaHelper.js`
- `backend/scripts/recalcStorage.js`
- `backend/scripts/checkStorage.js`

#### File lifecycle and storage operations
The primary operational flow is: authenticated client selects a workspace → folder/asset APIs mutate metadata and storage → quota checks constrain usage → frontend refreshes explorer state. Asset-specific endpoints and conversion form the file-processing boundary:
- `backend/routes/images.js`
- `backend/routes/convert.js`
- `backend/models/Asset.js`

Maintenance scripts indicate storage integrity, CDN URL repair, cleanup, and upload synchronization are operational concerns:
- `backend/scripts/cleanupStorage.js`
- `backend/scripts/verify_storage.js`
- `backend/scripts/fix_cdn_urls.js`
- `backend/scripts/testUploadSync.js`

The concrete storage provider is not identifiable from the supplied tree.

#### Frontend state and API integration
The React/Vite client uses centralized stores to separate session, selected workspace, file explorer, trash, confirmation dialog, and UI state. API transport and possible realtime/socket integration are isolated under `src/api`.
- `frontend/src/api/axios.js`
- `frontend/src/api/socket.js`
- `frontend/src/stores/useAuthStore.js`
- `frontend/src/stores/useWorkspaceStore.js`
- `frontend/src/stores/useExplorerStore.js`
- `frontend/src/stores/useTrashStore.js`

#### User-facing application stages
Authentication includes standard login and two-factor setup/login, followed by protected application views. The dashboard is the main explorer surface; workspace controls alter tenant context; trash and admin are separate operational surfaces.
- `frontend/src/components/ProtectedRoute.jsx`
- `frontend/src/views/LoginView.jsx`
- `frontend/src/views/TwoFactorLogin.jsx`
- `frontend/src/views/TwoFactorSetup.jsx`
- `frontend/src/views/DashboardView.jsx`
- `frontend/src/views/TrashView.jsx`
- `frontend/src/views/AdminView.jsx`

#### Runtime and deployment boundaries
Backend is a Node.js package/service defined by `backend/package.json`. Frontend is a Vite-built React application defined by `frontend/package.json`, with Vercel deployment configuration at `frontend/vercel.json`. The production frontend environment is supplied through `frontend/.env.production`; backend deployment and database/storage infrastructure are not described in the available README.

Main entry points: [`backend/routes/images.js`](https://github.com/thavasakthi/velodrive/blob/main/backend/routes/images.js) (Domain API routes), [`backend/models/Asset.js`](https://github.com/thavasakthi/velodrive/blob/main/backend/models/Asset.js) (Stored assets), [`frontend/src/App.jsx`](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/App.jsx) (App routing), [`frontend/src/components/ProtectedRoute.jsx`](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/components/ProtectedRoute.jsx) (Protected routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_spa_entry["SPA entry<br/>React/Vite entry<br/>[main.jsx]"]
  node_app_router["App routing<br/>React composition<br/>[App.jsx]"]
  node_auth_views["Authentication views<br/>login and 2FA<br/>[LoginView.jsx]"]
  node_protected_route["Protected routes<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_workspace_views["Explorer workspace views<br/>dashboard and trash<br/>[DashboardView.jsx]"]
  node_admin_view["Admin view<br/>admin surface<br/>[AdminView.jsx]"]
  node_client_stores["Client state stores<br/>Zustand stores"]
  node_api_transport["API and socket client<br/>HTTP/realtime transport<br/>[axios.js]"]
end

subgraph group_backend["Node API service"]
  node_server["HTTP server<br/>Express entry<br/>[server.js]"]
  node_api_routes["Domain API routes<br/>Express routers<br/>[images.js]"]
  node_access_middleware["Access middleware<br/>authentication and authorization<br/>[auth.js]"]
end

subgraph group_domain["Domain and operations"]
  node_users[("Users<br/>domain model<br/>[User.js]")]
  node_workspaces[("Workspaces<br/>tenant model<br/>[Workspace.js]")]
  node_folders[("Folders<br/>organization model<br/>[Folder.js]")]
  node_assets[("Stored assets<br/>asset metadata model<br/>[Asset.js]")]
  node_quota["Quota accounting<br/>storage policy<br/>[quotaHelper.js]"]
  node_file_storage[("File storage provider<br/>external storage")]
  node_storage_maintenance["Storage maintenance<br/>operational scripts<br/>[recalcStorage.js]"]
end

node_spa_entry -->|"mounts"| node_app_router
node_app_router -->|"routes to"| node_auth_views
node_app_router -->|"guards app routes"| node_protected_route
node_protected_route -->|"permits"| node_workspace_views
node_protected_route -->|"permits"| node_admin_view
node_auth_views -->|"updates session"| node_client_stores
node_workspace_views -->|"reads and refreshes"| node_client_stores
node_client_stores -->|"uses"| node_api_transport
node_api_transport -->|"HTTP and possible realtime"| node_server
node_server -->|"applies"| node_access_middleware
node_access_middleware -->|"authorizes"| node_api_routes
node_api_routes -->|"authenticates"| node_users
node_api_routes -->|"manages membership"| node_workspaces
node_api_routes -->|"organizes"| node_folders
node_api_routes -->|"creates and mutates"| node_assets
node_api_routes -->|"checks usage"| node_quota
node_api_routes -->|"stores and processes files"| node_file_storage
node_assets -->|"belongs to"| node_folders
node_folders -->|"scoped to"| node_workspaces
node_assets -->|"scoped to"| node_workspaces
node_quota -->|"accounts for"| node_assets
node_storage_maintenance -.->|"reconciles metadata"| node_assets
node_storage_maintenance -.->|"verifies and repairs"| node_file_storage

click node_spa_entry "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/main.jsx"
click node_app_router "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/App.jsx"
click node_auth_views "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/views/LoginView.jsx"
click node_protected_route "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_workspace_views "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/views/DashboardView.jsx"
click node_admin_view "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/views/AdminView.jsx"
click node_client_stores "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/stores/useExplorerStore.js"
click node_api_transport "https://github.com/thavasakthi/velodrive/blob/main/frontend/src/api/axios.js"
click node_server "https://github.com/thavasakthi/velodrive/blob/main/backend/server.js"
click node_api_routes "https://github.com/thavasakthi/velodrive/blob/main/backend/routes/images.js"
click node_access_middleware "https://github.com/thavasakthi/velodrive/blob/main/backend/middleware/auth.js"
click node_users "https://github.com/thavasakthi/velodrive/blob/main/backend/models/User.js"
click node_workspaces "https://github.com/thavasakthi/velodrive/blob/main/backend/models/Workspace.js"
click node_folders "https://github.com/thavasakthi/velodrive/blob/main/backend/models/Folder.js"
click node_assets "https://github.com/thavasakthi/velodrive/blob/main/backend/models/Asset.js"
click node_quota "https://github.com/thavasakthi/velodrive/blob/main/backend/utils/quotaHelper.js"
click node_storage_maintenance "https://github.com/thavasakthi/velodrive/blob/main/backend/scripts/recalcStorage.js"

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_entry,node_app_router,node_auth_views,node_protected_route,node_workspace_views,node_admin_view,node_client_stores,node_api_transport toneBlue
class node_server,node_api_routes,node_access_middleware toneAmber
class node_users,node_workspaces,node_folders,node_assets,node_quota,node_file_storage,node_storage_maintenance toneMint
```

## Components

### React client

- [SPA entry](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/main.jsx): React/Vite entry · `frontend/src/main.jsx`
- [App routing](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/App.jsx): React composition · Composes routes and application UI. · `frontend/src/App.jsx`
- [Authentication views](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/views/LoginView.jsx): login and 2FA · `frontend/src/views/LoginView.jsx`
- [Protected routes](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/components/ProtectedRoute.jsx): route guard · `frontend/src/components/ProtectedRoute.jsx`
- [Explorer workspace views](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/views/DashboardView.jsx): dashboard and trash · `frontend/src/views/DashboardView.jsx`
- [Admin view](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/views/AdminView.jsx): admin surface · `frontend/src/views/AdminView.jsx`
- [Client state stores](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/stores/useExplorerStore.js): Zustand stores · Holds session, workspace, explorer, trash, and UI state. · `frontend/src/stores/useExplorerStore.js`
- [API and socket client](https://github.com/thavasakthi/velodrive/blob/main/frontend/src/api/axios.js): HTTP/realtime transport · `frontend/src/api/axios.js`

### Node API service

- [HTTP server](https://github.com/thavasakthi/velodrive/blob/main/backend/server.js): Express entry · `backend/server.js`
- [Domain API routes](https://github.com/thavasakthi/velodrive/blob/main/backend/routes/images.js): Express routers · Auth, workspace, folder, asset, trash, conversion, and admin APIs. · `backend/routes/images.js`
- [Access middleware](https://github.com/thavasakthi/velodrive/blob/main/backend/middleware/auth.js): authentication and authorization · Rate limits login and enforces user, workspace, and admin access. · `backend/middleware/auth.js`

### Domain and operations

- [Users](https://github.com/thavasakthi/velodrive/blob/main/backend/models/User.js): domain model · `backend/models/User.js`
- [Workspaces](https://github.com/thavasakthi/velodrive/blob/main/backend/models/Workspace.js): tenant model · Membership and ownership define the tenant boundary. · `backend/models/Workspace.js`
- [Folders](https://github.com/thavasakthi/velodrive/blob/main/backend/models/Folder.js): organization model · `backend/models/Folder.js`
- [Stored assets](https://github.com/thavasakthi/velodrive/blob/main/backend/models/Asset.js): asset metadata model · `backend/models/Asset.js`
- [Quota accounting](https://github.com/thavasakthi/velodrive/blob/main/backend/utils/quotaHelper.js): storage policy · Centralizes storage usage checks and accounting. · `backend/utils/quotaHelper.js`
- **File storage provider**: external storage · Concrete provider is not identified.
- [Storage maintenance](https://github.com/thavasakthi/velodrive/blob/main/backend/scripts/recalcStorage.js): operational scripts · Recalculates, verifies, repairs, cleans, and synchronizes storage. · `backend/scripts/recalcStorage.js`

## Connections

- SPA entry → App routing: mounts
- App routing → Authentication views: routes to
- App routing → Protected routes: guards app routes
- Protected routes → Explorer workspace views: permits
- Protected routes → Admin view: permits
- Authentication views → Client state stores: updates session
- Explorer workspace views → Client state stores: reads and refreshes
- Client state stores → API and socket client: uses
- API and socket client → HTTP server: HTTP and possible realtime
- HTTP server → Access middleware: applies
- Access middleware → Domain API routes: authorizes
- Domain API routes → Users: authenticates
- Domain API routes → Workspaces: manages membership
- Domain API routes → Folders: organizes
- Domain API routes → Stored assets: creates and mutates
- Domain API routes → Quota accounting: checks usage
- Domain API routes → File storage provider: stores and processes files
- Stored assets → Folders: belongs to
- Folders → Workspaces: scoped to
- Stored assets → Workspaces: scoped to
- Quota accounting → Stored assets: accounts for
- Storage maintenance → Stored assets: reconciles metadata
- Storage maintenance → File storage provider: verifies and repairs